sh

capa sh turns every configured tool into a CLI. MCP tools live under the server id; command tools appear at the top level (or under a custom group). Tool ids are slugified to kebab-case.

Requires a capabilities file in the current project. If the capa server is not running, capa sh starts it.

Synopsis

capa sh [args...]
capa sh [--raw] <group> <subcommand> [--arg value...]
capa sh [--raw] <command> [--arg value...]
capa sh --exec -- <program> [args...]

Flags

Flag	Description
--raw	Return raw tool output (skip the formatter). Position-independent: works before or after the command tokens
--exec	Run a program that is not a capa tool. Tokens after -- are spawned directly as argv (no shell), in the current directory

capa sh does not take a dedicated --json for tool payloads. Global --json only affects machine-readable CLI status from capa itself.

Caution

Older workflows used capa sh --json for tool output. Use capa sh --raw to skip the formatter. Global --json is only for machine-readable CLI status: it does not replace --raw.

Usage patterns

Invocation	Effect
capa sh	List available commands
capa sh <group>	List subcommands for an MCP server group
capa sh <group> <tool> [--args]	Run an MCP tool
capa sh <command> [--args]	Run a top-level command tool
capa sh <unknown> ...	Error: No such tool, exit code 1
capa sh --exec -- <program> [args]	Spawn the program directly; exits with its exit code
capa sh --help / … --help	Contextual help at any level

Note

Unknown commands no longer fall through to the OS shell. Earlier versions ran capa sh git log as a shell command; use capa sh --exec -- git log instead. --exec never goes through sh -c or cmd /C, so pipes, redirects, and variable expansion are not interpreted. Because it is an explicit flag, agent allow-lists can deny capa sh --exec separately from tool calls.

Examples

capa sh
capa sh gitlab
capa sh gitlab list-merge-requests --help

capa sh gitlab list-merge-requests --project-id 123 --state opened

# Raw tool output (any position)
capa sh --raw gitlab list-merge-requests --project-id 123
capa sh gitlab list-merge-requests --project-id 123 --raw

# Top-level command tool
capa sh find-skills --query "git automation"

# Run a non-capa program (argv spawn, no shell)
capa sh --exec -- git log --oneline

See also

• Server lifecycle
• install
• Global flags
• Tool exposure