Command reference

CAP CLI Command Guide

A clear reference for every CAP CLI command. Start with the task, review the right options, run safe checks, pin packages to a project, and execute them with confidence.

Browse Commands Copy A Recipe Tool Registry 
$ cap resolve "set up a lightning testnet node" --json
$ cap try lightningnode/voltage-sandbox --json
$ cap add lightningnode/voltage-sandbox --yes
$ cap run lightningnode/voltage-sandbox -- brief

Read This First

CAP CLI is project-first. Package commands use the current project's ./.cap store by default, and write project pins to Capfile plus exact install details to Capfile.lock. Use --global or -g when you really want the old ~/.cap package scope.

Find

resolve, search, and info help an agent pick a tool with context instead of guessing.

Try

try runs declared safe checks in an isolated temp home with host secrets stripped out.

Use

add, install, run, and remove manage tools in a reviewable project workflow.

Publish

init, preview, review, and publish --local turn a local CLI into a registry package.

Recipes

Use these when you want the happy path without reading every card first.

Let an agent pick a tool

Good for task-first work where you know the outcome, not the package name.

cap resolve "set up a new lightning testnet node" --json
cap info lightningnode/voltage-sandbox --json
cap try lightningnode/voltage-sandbox --json
Pin a tool to this project

Good for teams. The important bits land in Capfile and Capfile.lock.

cap add lightningnode/voltage-sandbox --yes
cap list
git diff Capfile Capfile.lock
Rebuild tools from a fresh checkout

Good after cloning a repo that already has a lockfile.

cap install --yes
cap run lightningnode/voltage-sandbox -- brief
Use the global scope on purpose

Good for personal scratch tools. It skips project pins.

cap add lightningnode/voltage-sandbox --yes --global
cap list --global
cap run lightningnode/voltage-sandbox --global -- brief
Publish a local package

Good for package authors working against a checked-in registry JSON file.

cap init acme/my-tool
cap preview --json
cap review --run-trials --json
cap publish --local --registry registry/packages.json --dry-run --json

All Commands

Every command below has a job, a syntax line, and a small example. The examples use lightningnode/voltage-sandbox, the first CAP package.

cap helpPrint the built-in map.
cap help
cap --help
cap -h

Use this when your brain wants a local cheat sheet.

cap help
cap resolveStart from a task.
cap resolve <task> [--json] [--limit <n>] [--global|-g] [--project <path>]

Ranks candidate packages and includes policy decisions, review summaries, and install plans.

cap resolve "set up a new lightning testnet node" --json
cap resolve "inspect postgres schema" --limit 3
cap searchSearch by keyword.
cap search <query> [--json]

Fast list view. Good when you already know a useful word like voltage or postgres.

cap search voltage
cap search lightning --json
cap infoOpen the package card.
cap info <package> [--json] [--global|-g] [--project <path>]

Shows summary, capability card, review record, policy decision, safe trials, and exact install plan.

cap info lightningnode/voltage-sandbox
cap info lightningnode/voltage-sandbox --policy-profile safe --json
cap tryRun safe checks first.
cap try <package> [--json] [--yes] [--global|-g] [--project <path>]

Installs into a temporary isolated home, strips common host secrets, and runs declared safe trials.

cap try lightningnode/voltage-sandbox --json
cap try lightningnode/voltage-sandbox --yes --policy-profile prototype-local
cap addInstall and pin.
cap add <package> [--yes] [--force] [--global|-g] [--project <path>]

In project scope, installs the package, updates Capfile, and writes an exact Capfile.lock. With --global, it installs to ~/.cap and skips project pins.

cap add lightningnode/voltage-sandbox --yes
cap add lightningnode/voltage-sandbox --yes --global
  • --yes accepts policy steps that require explicit approval.
  • --force allows replacing an existing non-symlink bin when needed.
cap install
cap install [--json] [--yes] [--project <path>]
cap install <package> ...

With no package argument, reviews policy for every locked package from Capfile.lock, then installs after approval or --yes. With a package argument, it is kept as an alias for cap add.

cap install --yes
cap install --yes --project ../starter-kit
cap install lightningnode/voltage-sandbox --yes
cap sync
cap sync [--json] [--yes] [--project <path>]

Same lockfile review and install path as cap install. Use whichever word makes your team happiest.

cap sync --yes --json
cap removeUnpin one package.
cap remove <package> [--json] [--global|-g] [--project <path>]
cap rm <package> ...

Removes the installed record and bin. In project scope, it also removes the package from Capfile and Capfile.lock.

cap remove lightningnode/voltage-sandbox
cap rm lightningnode/voltage-sandbox --global
cap list
cap list [--json] [--global|-g] [--project <path>]
cap ls ...

Shows installed packages. In project scope, it also reports pins from Capfile.

cap list
cap list --json
cap ls --global
cap run
cap run <package> [--yes] [--global|-g] [--project <path>] -- <args>

Runs the selected package's first declared CLI bin through CAP's policy gate. Everything after -- is passed to the package.

cap run lightningnode/voltage-sandbox -- brief
cap run lightningnode/voltage-sandbox --yes --json -- report --json
cap run lightningnode/voltage-sandbox --global -- doctor
cap doctor
cap doctor [--json]

Checks CAP home, bin path, registry, policy, uninstall plan, and next actions.

cap doctor
cap doctor --json
cap setup
cap setup codex [--json] [--dry-run]
cap setup claude [--json] [--dry-run] [--project <path>]

Connects CAP to agent hosts. Codex gets a skill and MCP config. Claude Code gets a project .mcp.json and marked CLAUDE.md guidance.

cap setup codex
cap setup claude
cap setup claude --project ../my-app --dry-run
cap uninstall
cap uninstall [--yes] [--project <path>]

Removes the CAP runtime store, shell profile PATH setup, and recorded host integrations. Use --project for old Claude Code integrations that were not recorded yet.

cap uninstall
cap uninstall --yes
cap uninstall --project ../legacy-claude-project
cap bin
cap bin [--global|-g] [--project <path>]

Prints the active package scope's bin directory.

cap bin
cap bin --global
cap bin --project ../my-app
cap initCreate a package manifest.
cap init [package-id] [--manifest <path>] [--force] [--json]

Creates capability.json. It infers package metadata, command bins, nearby skills, and MCP server names where possible.

cap init acme/my-tool
cap init acme/my-tool --manifest cap/capability.json --force --json
cap previewCompile without publishing.
cap preview [--manifest <path>] [--registry <path>] [--json]

Shows the normalized package, capability card, generated review record, install plan, and quality warnings before anything is written.

cap preview --json
cap preview --manifest cap/capability.json --registry registry/packages.json
cap reviewRun publisher preflight.
cap review [--manifest <path>] [--registry <path>] [--run-trials] [--json]

Validates manifest shape, package tasks, safe trials, bins, artifact digest, skill frontmatter, MCP tool names, and structured-output quality signals. With --run-trials, local-bin safe trials run in an isolated temp home.

cap review --json
cap review --run-trials --json
cap publishWrite a local registry.
cap publish --local [--manifest <path>] [--registry <path>] [--dry-run] [--force] [--json]

Runs review and writes the compiled package into a filesystem registry JSON. Remote publish is not implemented in this prototype.

cap publish --local --registry registry/packages.json
cap publish --local --registry registry/packages.json --dry-run --json
  • Publishing refuses the same id@version unless --force is set.
  • See publisher workflow for manifest examples and CI checks.

Options

Most options are boring in the best way. They make scope, policy, registry, and output explicit.

--json

Machine-readable output for agents, scripts, and tests.

--registry <path-or-url>

Use a local or remote registry JSON file. Default: registry/packages.json in development or the hosted CAP registry in the public CLI.

--manifest <path>

Select a publisher manifest file for init, preview, review, or publish. Default: capability.json.

--project <path>

Select a project directory. Package commands default to ., which maps to ./.cap, Capfile, and Capfile.lock.

--global, -g

Use the global package scope at ~/.cap. This is handy for personal tools and scratch work.

--home <path>

Advanced package store override. For package commands, this overrides --project and --global.

--policy <profile-or-file>

Use a policy profile such as balanced, or point at a JSON policy file.

--policy-profile <name>

Choose a named policy profile. Current profiles include balanced, safe, prototype-local, and power.

--policy-file <path>

Overlay policy settings from a JSON file.

--limit <n>

Used by resolve to cap the number of candidates.

--yes

Accept an approval-gated action in non-interactive flows. CAP still blocks actions that policy marks as blocked.

--force

Used by add when replacing an existing non-symlink command is intentional, and by publisher commands when overwriting a manifest or republishing the same id@version.

--dry-run

Used by setup and publish to show changes without writing them.

--run-trials

Used by review to execute declared safe trials for local-bin packages in an isolated temporary home.

--local

Required by publish in the prototype because hosted marketplace publishing is not implemented yet.

The -- separator matters

In cap run, everything after -- belongs to the package command. Example: cap run lightningnode/voltage-sandbox -- report --json.

Files CAP Writes

Project files are meant to be reviewable in Git. The local package store is meant to be reproducible from the lockfile.

Capfile

Small project intent file: schema, version, exact package refs, and policy profile.

{
  "schema": "capfile.v0",
  "version": 1,
  "capabilities": [
    "lightningnode/voltage-sandbox@0.1.7"
  ],
  "policy": {
    "profile": "balanced"
  }
}
Capfile.lock

Exact resolved details: registry source, install source, digest, review, policy decision, and install plan.

cap add lightningnode/voltage-sandbox --yes
git diff Capfile Capfile.lock
cap sync --yes