capa sh

Run any configured tool directly from the command line, or explore what tools are available in the current project. capa sh turns every MCP server and command tool in your capabilities.yaml into a CLI command that can be invoked by both humans and AI agents.

Requires a capabilities.yaml (or capabilities.json) in the current directory and the CAPA server running (capa start). Run capa install at least once to register the project with the server.

Usage

# Show all available commands
capa sh

# Show subcommands for an MCP server group
capa sh <group>

# Run a tool
capa sh <group> <subcommand> [--arg value ...]
capa sh <command> [--arg value ...]

# Show help at any level
capa sh --help
capa sh <group> --help
capa sh <group> <subcommand> --help

# Pass through to the OS shell
capa sh git log --oneline
capa sh ls -la

How Commands Are Organised

CAPA maps every tool in your capabilities file to a shell command. Tool IDs are automatically slugified — underscores and camelCase are converted to kebab-case:

list_merge_requests → list-merge-requests
listMergeRequests → list-merge-requests
SEARCH_CONFLUENCE → search-confluence

Tools are organised into two levels:

MCP server tools — grouped under the server's ID (e.g. all tools from id: gitlab appear under the gitlab group)
Command tools — appear at the top level, or optionally nested under a group you define

Exploring Available Commands

Running capa sh with no arguments prints all available commands:

$ capa sh

Capa Shell - Available commands:

  gitlab                  Manage GitLab merge requests and issues
  atlassian               Access to Atlassian Confluence and Jira
  capa-install            Install capabilities
  find-skills             Find skills from the skills.sh ecosystem

Usage:
  capa sh                              Show this help
  capa sh <group>                      List tools in a group
  capa sh <group> <tool> [--arg val]   Run a tool
  capa sh <command> [--arg val]        Run a top-level command
  capa sh <other>                      Pass through to OS shell

Drill into a group to see its subcommands:

$ capa sh gitlab

gitlab - subcommands:

  list-merge-requests  [--project-id*] [--state]  — List open merge requests
  create-issue  [--title*] [--description]         — Create a new issue

Get argument details for a specific tool:

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

  list-merge-requests  —  List open merge requests

  Arguments:

    --project-id <string> (required)
    --state <string>

Running Tools

Pass arguments using --key value pairs. Argument names are slugified in the same way as command names:

# MCP server tool
capa sh gitlab list-merge-requests --project-id 123 --state opened

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

# Boolean flag (value optional — presence implies true)
capa sh my-tool --verbose

Required arguments are marked with * in the help output. Running a command without its required arguments prints a usage hint and exits with an error.

OS Shell Pass-Through

Any command that isn't recognised as a CAPA tool is forwarded to the operating system's default shell (/bin/sh on macOS/Linux, cmd.exe on Windows), in the current working directory:

capa sh git status
capa sh ls -la
capa sh python3 --version

One-Shot Mode for AI Agents

capa sh is intentionally non-interactive. Every invocation runs a single command, prints the result, and exits. This makes it well-suited for AI agents that call tools via shell commands:

# An agent can explore, then execute in separate calls
capa sh                                         # discover groups
capa sh atlassian                               # discover subcommands
capa sh atlassian search --query "infragate"    # execute

Tool Grouping for Command Tools

Command tools can be nested under a shared parent group using the group field. This keeps the top-level command list clean when you have many related tools:

tools:
  - id: deploy_service
    type: command
    group: deploy
    description: Deploy a service to production
    def:
      run:
        cmd: ./deploy.sh {service}
        args:
          - name: service
            type: string
            required: true

  - id: rollback_service
    type: command
    group: deploy
    description: Roll back a service to the previous version
    def:
      run:
        cmd: ./rollback.sh {service}
        args:
          - name: service
            type: string
            required: true

This produces:

$ capa sh

Capa Shell - Available commands:

  deploy                  2 subcommands available

$ capa sh deploy

deploy - subcommands:

  deploy-service  [--service*]   — Deploy a service to production
  rollback-service  [--service*] — Roll back a service to the previous version

Single-subcommand groups are promoted. If a group contains only one command tool, that tool is displayed directly at the top level instead of being nested — keeping the interface clean.