# CLI reference (/docs/pounce/cli) ```sh pounce --launcher # apps + commands palette (the default mode) pounce --max-empty 7 # rows to show before you type pounce -p "Pick:" # generic picker; reads lines from stdin pounce -i "sf.symbol.name" # icon for the picker pounce -p "Search:" --chain # picker whose free-text Enter feeds another pounce step pounce -p "Project:" --grid # the same rows as a two-column card grid pounce -p "Ask:" --dial "model=sonnet|opus|haiku" # a chip the user cycles with ⇥ pounce run cmd:emoji # run one item by its key (for external binders) open 'pounce://run?item=cmd:emoji' # …the same, from anything that opens a URL # built-in windows (items, not flags) pounce run mode:clipboard # clipboard history pounce run mode:emoji # emoji + symbols picker pounce run mode:screenshots # screenshot browser pounce run mode:camera # live camera preview pounce run mode:filesearch # file/folder search (Spotlight index) pounce run mode:settings # the Settings window pounce run app:/Applications/Ghostty.app pounce --cheatsheet [path] # cheatsheet overlay pounce --transform 'tr a-z A-Z' # rewrite the selected text through a shell filter # settings pounce settings # open the Settings window pounce config print # print the annotated config, touching nothing pounce config init # write ~/.config/pounce/config.json # reading the palette pounce list # every command on this Mac, and what it declares pounce list --json # the same as data pounce skill # the agent skill compiled into the binary pounce skill install # write it where this Mac's agents look # housekeeping pounce doctor # diagnose a dead/slow hotkey or binding pounce --request-accessibility # ask the daemon to raise the TCC dialog pounce --check-accessibility # the daemon's grant: true/false/unknown pounce --request-bluetooth / --check-bluetooth pounce --help / --version ``` ## Flags [#flags] | Flag | Purpose | | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `-p`, `--placeholder` | Prompt text for the search field | | `-i`, `--icon` | SF Symbol icon for the picker | | `--chain [keys]` | Mark a free-text commit as feeding another `pounce` step. Optional comma-separated action list (`--chain enter,opt`); bare `--chain` means `enter` | | `--chain-rows [keys]` | The same for a picked **row**. Same grammar. Two flags rather than one because a single step often wants opposite answers for the same key: Enter on a search box that reopens the picker should hold the window, Enter on a row that opens something should not | | `--actions ` | Label the action bar on a rowless step: `"Go\|shift:New line\|cmd:Screenshot\|opt:Drafts"` | | `--grid` | Draw the step's rows as a two-column card grid instead of a list: a rectangle each, with an icon and a line of description. Same stdin, same output, same exit code. `--launcher` ignores it | | `--dial ` | A small set of values the user cycles in place with `⇥` / `⇧⇥`: `"model=sonnet\|opus\|haiku"`. Repeatable. **Adds a middle field to the output** ([what a picker hands back](/docs/pounce/writing-commands#what-a-picker-hands-back)) | | `--draft ` | Keep typed text on any non-commit dismissal, filed under `` | | `--query ` | Open with the box pre-filled, caret at the end | | `--transform ` | Pipe the current selection through a shell filter and paste the result back (needs Accessibility) | | `--copy-file ` | Copy a file's contents to the clipboard | | `--max-empty ` | How many rows to show before anything is typed | | `--cheatsheet [path]` | Open the cheatsheet overlay | ## Subcommands [#subcommands] | Subcommand | Purpose | | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `run ` | Run one item by the key `items` uses, for binders that own the keystroke | | `list [--json]` | Every command script installed on this Mac: its item key, its name, [what its header declares](/docs/pounce/writing-commands#what-a-command-says-it-will-do) it will do, its description and the file it runs, so a command can be read before it is run. TSV by default. It asks the running daemon, whose command dirs are the ones ⌘Space actually sees, and falls back to discovering them from your shell; `--json` says which happened. Installed rather than on screen: a row a `whenFile` vetoes is left out, one your `items` map hides is still listed | | `skill` / `skill install` | Print the [agent skill](https://github.com/hausfold/pounce/blob/main/ai/SKILL.md) compiled into the binary, or write it where this Mac's agent clients look. `--client claude\|codex\|opencode\|pi` or `--dir ` for one destination. It refuses rather than clobbers, and skips anything haus already filled in | | `settings` | Open the Settings window: panes of cards over the same table `config print` writes, and a click rewrites one line of your `config.json` | | `config print` / `config init` | Print the annotated config, or write one | | `doctor` | Report the daemon, the grant, and every binding actually armed | | `report [--print]` | Open Pounce's bug form with `doctor`'s whole report already in it, above the version, your macOS build, your Mac model and which install route this copy came from. `--print` writes the block and the URL to stdout and opens nothing, for a Mac you reached over ssh. There is no telemetry in Pounce, so that form is the only way anything gets back to us | | `focus ` | Focus/DND: `focus status\|toggle\|on\|off`, forwarded to the daemon | | `drafts ` | `save` (stdin) / `list` / `get ` / `rm ` / `clear`. Files live in `~/.local/state/pounce/drafts/.tsv`, newest first, capped at 20 | ## From a link [#from-a-link] The item keys `run` takes are also reachable as a URL, so anything that can open one — a row in an Obsidian base, a note, a spreadsheet cell, a Shortcut, a web page — can run a palette command with no plugin of its own: ``` pounce://run?item=cmd:todos pounce://run?item=cmd:new-lane&arg=/Users/me/notes/a%20task.md ``` `arg` is repeatable (up to four) and positional (`$1`, `$2` …) and only a `cmd:` item takes any; nothing crosses a shell, so a value with spaces or quotes in it arrives as one argument. Percent-encode `&`, `#`, `%` or a space. A link that would **run** something is confirmed on screen first — `cmd:`, `app:`, `shortcut:`, and `mode:camera`, which starts a capture session rather than drawing a list. The sheet names the app that opened the link and every argument it carries. A link that only **opens** something (the other `mode:`s, `setting:`) isn't, and a link that arrives while pounce already has something on screen is refused rather than taking it. Both dials are in [`urlScheme`](/docs/pounce/config#running-an-item-from-a-link-urlscheme): `confirm: false` trusts a link as much as your keyboard, `enabled: false` refuses every link. There is no exit code to hand back — a URL's caller has already moved on — so a link pounce can't honour says so in a notification rather than failing quietly. ## Reading it as data [#reading-it-as-data] `--json` is on the read verbs and the write receipts around them: `list`, `doctor`, `config`, `config print`, `focus status`, `autostart` and every `drafts` verb. It is strictly additive, so a script that already parses the plain output keeps working: `drafts list` still prints TSV, `focus status` still prints a bare `on`/`off`. Every record carries sorted keys, unescaped slashes and a schema number. Two shapes are worth knowing. `config print --json` answers a different question from `config print`: the **effective** settings, every key at the value pounce will actually use, plus `set`, the keys your file really names, so "unset" and "set to the default" stop looking alike. And `doctor --json` leaves a fact it couldn't reach as `null` rather than `false`, because "no grant" and "no daemon answered" are the two things that command exists to tell apart. ## Exit codes [#exit-codes] | | | | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **0** | ok | | **1** | nothing came back: a dismissed picker, a draft index that isn't there, an item key `run` can't resolve, an unhealthy `doctor`, a daemon that isn't running, a file `skill install` tried to write and couldn't | | **2** | usage: a verb, subcommand or flag pounce doesn't have | | **3** | refused: pounce won't do it *here*. A `config.json` haus generated, a `SKILL.md` that is already there with different bytes. Nothing to retry | A skills directory haus manages is **not** a refusal: those are read-only Nix symlinks, the skill is already at that path, and `skill install` names them and exits 0. Anything else would send an agent back at a store path with more force. `focus` keeps its own finer table; it predates this one, and haus's hush scripts read it. ## Homebrew binaries [#homebrew-binaries] The Homebrew install puts `pounce` (the app/daemon), `pounce-palette` (the launcher wrapper, for binding a hotkey externally), and one `pounce-` wrapper per built-in on your `PATH`. Inside haus, set the palette up via `haus.launcher` instead; the module handles the daemon, the hotkey, and permission survival for you.