# Commands (/docs/pounce/commands)



Every command on this page is a shell script, every built-in included. There is
no privileged tier: read one, copy it, or replace it with your own.

## Built-in commands [#built-in-commands]

Out of the box: **Activity Monitor**, **Brew Services**, **Camera**,
**Capitalize** / **Lowercase** (rewrite the text selected in *any* app),
**Clipboard History**, **Emoji & Symbols**, **Find Files**, **Force Quit**,
**Lock Screen**, **Ports**, **Report Pounce Issue**, **Screenshots**, and
**System Settings**, which opens the app.

System Settings panes are not commands. Every pane, and every setting inside
one, is a launcher row in its own right, read from the panes' own search index
rather than from a table in the repo, so "Displays" goes to Displays and "night
shift" goes to the switch. Nothing to install and nothing
to enable; the three knobs are under
[`systemSettings`](/docs/pounce/config#config-file).

On a Homebrew install there is one more: **Update Pounce**, which self-updates in
place. It is `brew upgrade pounce` on Homebrew and an in-place swap for a
dragged-in app, but only a nudge to `haus update` on Nix and haus, where the next
rebuild would revert it anyway.

## Two-step commands [#two-step-commands]

Some open a second picker instead of acting immediately (**Brew Services** lists
services, **Force Quit** lists processes), and the list swaps **in place**, with
no window flicker. Not a special capability: it is [a script calling `pounce`
again](/docs/pounce/writing-commands#submenus-and-chaining).

## Your Shortcuts, as rows [#your-shortcuts-as-rows]

Every entry in your Shortcuts library is an ordinary launcher row: type its name,
press `⏎`, it runs. No mode, no prefix, no submenu. They take the same
[per-item](/docs/pounce/config#per-item-settings-items) overrides under the key
`shortcut:<uuid>` (from `shortcuts list --show-identifiers`), and
`"shortcuts": { "enabled": false }` turns the whole source off.

They start at the bottom on purpose: a shortcut carries a small negative rank so
a sixty-entry library can't take over an empty query on the day you install
Pounce. Typed search is unaffected, and using one once lifts it out.

<Callout title="This is also how you reach an app's Spotlight action">
  macOS 26's Spotlight fires an app's **App Intents** directly, and Pounce cannot:
  there is no public API for running one. The bridge is a shortcut. In
  Shortcuts.app, make one whose single action is the app's intent, name it what
  you'd type, and it becomes a library entry Pounce shows and runs like any other
  row.
</Callout>

## The plugin shelf [#the-plugin-shelf]

A shelf of plugins ships **off by default**, because each assumes a specific
tool, service, or app:

| Plugin            | What it does                                    | Needs                               |
| ----------------- | ----------------------------------------------- | ----------------------------------- |
| **Audio Devices** | Switch sound output & input                     | `switchaudio-osx`                   |
| **Bluetooth**     | Connect & disconnect paired devices             | `blueutil`                          |
| **Caffeinate**    | Keep the Mac awake, indefinitely or on a timer  | nothing                             |
| **Docker**        | Start/stop/restart & tail container logs        | any engine that answers `docker ps` |
| **GitHub**        | Jump to your PRs, reviews, issues & repos       | `gh`, authenticated                 |
| **Perplexity**    | A fresh Perplexity thread from a typed question | a browser                           |
| **Spotify**       | Playback controls                               | Spotify.app                         |
| **SSH Hosts**     | Pick a host from `~/.ssh/config`                | hosts in `~/.ssh/config`            |
| **Tailscale**     | Connect/disconnect, copy an IP                  | the `tailscale` CLI                 |

On Nix, enable by id:

```nix
pounce-commands.override { plugins = [ "docker" "ssh" ]; }
```

Off Nix, every plugin is still just one script: copy it from
[`pkgs/pounce-commands/optional/`](https://github.com/hausfold/pounce/tree/main/pkgs/pounce-commands/optional)
into `~/.config/pounce/commands/` and it is live on the next ⌘Space.

## Where commands are discovered [#where-commands-are-discovered]

Later sources **shadow** earlier ones by filename, so yours always win:

1. `$POUNCE_BUILTIN_DIR`: the built-ins that ship with the package
2. `$POUNCE_EXTRA_COMMAND_DIRS` (colon-separated): layers added by Nix consumers like haus
3. `$POUNCE_COMMAND_PATH` (colon-separated): ad-hoc extra directories
4. `~/.config/pounce/commands`: **yours**, highest precedence

<Callout type="info" title="Override a built-in">
  Want to change what "Lock Screen" does? Drop your own `lock.sh` in
  `~/.config/pounce/commands/` with the same filename, and yours takes over.
</Callout>

A non-`.sh` file is ignored wherever it sits, and a helper that shouldn't itself
be a command belongs in a subdirectory (`data/`), which Pounce doesn't descend
into.

## Hiding, renaming and binding a row [#hiding-renaming-and-binding-a-row]

Any command, app or built-in mode can be dropped from the list, given a search
shorthand, or given a global key of its own. It is one map,
[`items`](/docs/pounce/config#per-item-settings-items), and it can also list a
row only on the workspaces or over the apps where it means something.