install

Run capa install after you edit capabilities.yaml / .json. capa installs skills, MCP client config, rules, hooks, agents blocks, and plugins for your providers, then wires the local server.

Synopsis

capa install [-e [file]] [-p <provider>] [--no-cache] [--passthrough] [--dry-run] [-y]

Flags

Flag	Description
-e, --env [file]	Load variables from a .env file instead of the credential web UI. Omitting the path uses .env in the project directory
-p, --provider <id>	Install for a single provider (e.g. cursor, claude-code). Overrides providers in the file
--no-cache	Bypass the on-disk cache and lockfile; re-resolve every remote source
--passthrough	Write provider-native files from the capabilities file (no capa server/proxy management)
--dry-run	Print the executable surface and exit without installing
-y, --yes	Skip the executable-surface confirmation (required in non-interactive / CI environments)

Executable surface confirmation

Before installing (managed or --passthrough), capa lists everything the install can execute on your machine:

• MCP stdio servers (command and arguments)
• MCP secret commands (fromCommand env / header values)
• Hooks
• Tool formatters
• Command tools
• Plugins

capa then asks you to confirm. Your answer is remembered per project: later installs only prompt again when that surface changes (for example, a new stdio server or an edited hook command). Unchanged surfaces install without a prompt.

capa install --dry-run   # review the surface, change nothing
capa install --yes       # accept the surface without prompting

Caution

Without a TTY, capa cannot prompt. If the surface is new or changed, capa install fails unless you pass --yes. Only use --yes in CI for capabilities files you trust.

Install errors

By default, operational errors warn instead of aborting: a missing required CLI (options.requiresCommands), a skill or rule that fails to fetch, a plugin that fails to resolve, hook install failures, tool validation errors, or an unsafe install path. capa installs everything that succeeds, prints the warnings and a summary, and exits 0.

To abort on the first failure and exit non-zero (useful in CI), set onInstallError under options:

options:
  onInstallError: stop   # warn (default) | stop

Safety checks

capa install refuses to write where it does not own the path:

• Project root containment: every provider install path (skills, rules, MCP config, hooks, sub-agents, instruction files, plugin manifests) must resolve inside the project. Path traversal and, on Windows, writes to a different drive are refused.
• No symlink escapes: capa refuses to write through a symlink or junction anywhere along the install path (for example .cursor/skills → ../skills).
• Wrap workspaces: capa install refuses to run inside a wrap workspace or register a path under ~/.capa/workspaces as a project.
• Remote URLs: remote rule, hook, and agent-snippet URLs must be public https URLs. URLs with embedded credentials, and hosts that are (or resolve to) loopback, private, link-local, or cloud-metadata addresses, are rejected.
• Pinned hook bodies: remote hook bodies are hashed in capabilities.lock. If upstream content changes under the same pin, install reports content changed upstream instead of installing it. Re-resolve deliberately with --no-cache. See Lockfile and cache.

After a managed install, every MCP server declared in the capabilities file is enabled on the capa server: you don’t need to toggle them on in the Web UI.

Provider resolution

When providers is omitted from the capabilities file, capa picks a provider in this order:

1. --provider flag
2. providers in the capabilities file
3. Stored providers from a previous install
4. Interactive prompt (TTY only)

Caution

In CI or other non-TTY environments, pass -p / --provider explicitly. Without a TTY, capa cannot prompt and the install fails.

Examples

capa install
capa install -e
capa install -e .prod.env
capa install -p cursor
capa install --no-cache
capa install --passthrough -p cursor
capa install --dry-run
capa install -p cursor --yes   # CI

With secrets in .env:

echo "BraveApiKey=your-api-key" > .env
capa install -e

See also

• init
• add
• Managed vs passthrough
• Credentials
• cache