Prowl CLI Input Contract #

This document owns argv/stdin grammar. Shared target semantics live in targeting.md; JSON response contracts live in the command documents and the executable schema bundle.

Root grammar #

prowl [path]
prowl open [path]
prowl list | agents [read|signal|dispatch|dispatch-complete|dispatch-abandon|wait] | profiles | skills | focus | read | send | key | handoff | create | close

Bare path forms (/, ./, ../, ~/, file://, ., ..) enter open. -- stops option parsing. --json and --no-color are leaf-command output options; JSON stdout always contains exactly one response envelope when parsing succeeds.

Shared target rules #

• Generic target positions use GenericTarget from targeting.md. Prefixed pN/tN handles work in --target and positional auto-targets.
• Typed selectors are mutually exclusive. A positional target plus selector flag is INVALID_ARGUMENT; no selector silently overrides another.
• send and key retain count-sensitive positional grammar:

send p12 remains text to the focused pane. Use send p12 'text', or stdin with --target p12, for a target-first send.

Lifecycle grammar #

prowl create tab <worktree> [--path <directory>] [--profile <name|uuid> [--prompt -] [--background]]
prowl create tab --worktree <worktree> [--path <directory>] [--profile <name|uuid> [--prompt -] [--background]]
prowl create pane <pN|pane-uuid> --direction <right|left|up|down> [--profile <name|uuid> [--prompt -] [--background]]
prowl create pane --pane <pN|pane-uuid> --direction <right|left|up|down> [--profile <name|uuid> [--prompt -] [--background]]
prowl profiles list
prowl close <pN|tN|uuid> [--force]
prowl close --pane <uuid|pN|N> [--force]
prowl close --tab <uuid|tN|N> [--force]

create tab requires a worktree-only target. create pane requires a pane-only anchor and explicit direction; it rejects --target, --worktree, --tab, bare numbers, and focus fallback. --prompt accepts only -, reads non-empty UTF-8 piped stdin up to 256 KiB, rejects an interactive terminal and NUL bytes, and requires --profile; --background also requires --profile. profiles list is a read-only global snapshot and accepts no target. close requires a pane-or-tab-only target and rejects --target, --worktree, bare-number positions, and focus fallback. See create.md and close.md.

tab create, tab close, and pane close remain deprecated aliases for one shipped release. They keep their legacy parser/transport behavior while emitting a stderr warning; new automation must use the lifecycle grammar above.

Local skills grammar #

prowl skills list
prowl skills install [<skill>...] [--target <claude|codex|agents>]... [--scope user|project] [--path <dir>]
prowl skills uninstall [<skill>...] [--target <claude|codex|agents>]... [--scope user|project] [--path <dir>]
prowl skills path <skill>

skills is local-only: it resolves the bundle beside the executable (or PROWL_SKILLS_DIR) and never opens the socket. --target is repeatable; --path requires --scope project (INVALID_ARGUMENT); path requires exactly one skill id. See skills.md.

Agent signal grammar #

prowl agents signal <turn-ended|needs-input|session-start|session-end|progress>
                    [--progress <0...100>] [--session <id>]
                    [--origin <claimed-origin>] [--detail <text>]

--progress is valid only with progress; omitting it means indeterminate progress. Session/origin are at most 256 UTF-8 bytes and detail is at most 32768. All are non-empty and control-free when present. Parser and handler enforce the same shared validation. See agents-signal.md.

Agent dispatch grammar #

prowl agents dispatch <pN|pane-uuid> --prompt -
prowl agents dispatch-complete --outcome <succeeded|failed> --summary <text>
prowl agents dispatch-abandon --dispatch <id> --reason <text>
prowl agents wait --dispatch <id> [--timeout <1...600>] [--include-screen <1...200>]
prowl agents wait <pN|pane-uuid> --until <idle|blocked|changed|exit> [--timeout <1...600>]
                  [--min-confidence <auto|exact|high|heuristic>] [--include-screen <1...200>]

agents dispatch requires a pane-only target and --prompt -: the prompt is piped UTF-8 stdin up to 256 KiB, CRLF-normalized, trailing newlines dropped, non-empty, and free of control characters other than newline and tab. dispatch-complete takes no id; it forwards a launch-scoped PROWL_DISPATCH_ID only when present. See agents-wait.md.

Command-specific exceptions #

• agents read <pN|pane-uuid> is a pane-only semantic snapshot, no selectors or focus fallback.
• agents dispatch <pN|pane-uuid> is pane-only as well; it never falls back to focus.
• agents signal accepts no selector. Its source is the caller pane resolved from the socket peer process ancestry, never UI focus or PROWL_PANE_ID.
• handoff defaults to the calling pane, not UI focus.
• list, agents, and profiles list are global discovery commands with no target selector.
• skills accepts no target selector and never contacts the app; it acts on the local filesystem only.
• open consumes a path rather than a target.

Transport request model #

The CLI sends one typed CommandEnvelope over the local socket. Command spelling is owned by ProwlCLI ArgumentParser declarations; target state resolution remains app-side. Parser and handler both enforce destructive lifecycle constraints so a malformed direct socket request cannot gain a focus fallback.