capa install

Install capabilities, skills, and start the CAPA server.

Usage

capa install [options]

Description

Reads the capabilities file and performs the following actions:

  1. Resolves and installs any plugins (clones remote repos, parses manifests, installs plugin skills and merges plugin tools and servers)
  2. Installs all skills to configured MCP clients (e.g., .cursor/skills/, ~/Library/Application Support/Claude/skills/)
  3. Installs or updates agent instructions files (AGENTS.md always; CLAUDE.md when claude-code is in providers) if the agents section is present — downloads the base file, upserts/prunes snippets
  4. Configures the CAPA server with your tools and servers and persists project capabilities to the database (so they survive server restarts)
  5. Prompts for any required credentials via web UI (unless -e flag is used)
  6. Registers the project's MCP endpoint in client config files
  7. Starts the CAPA server

Options

--env, -e [file]

Load environment variables from a .env file instead of using the interactive web UI for credentials.

  • Without filename: Uses .env in the project directory
  • With filename: Uses the specified file (e.g., .prod.env, .staging.env)
  • The env file must exist, or the command will fail with an error
  • All required variables must be present in the env file

Examples

Basic Installation

capa install

Installs capabilities and prompts for credentials via web UI.

Install with Default .env File

capa install -e

Loads variables from .env file in the current directory.

Install with Custom .env File

capa install -e .prod.env

Loads variables from .prod.env file.

Environment File Format

When using the -e flag, create a .env file with your credentials:

# Comments are supported
BraveApiKey=your-api-key-here
GitHubToken=ghp_token123
DatabaseUrl=postgresql://localhost:5432/db

Variable Substitution

In your capabilities file, reference environment variables using the ${VarName} syntax:

servers:
  - id: brave
    type: mcp
    def:
      cmd: npx -y @modelcontextprotocol/server-brave-search
      env:
        BRAVE_API_KEY: ${BraveApiKey}

Security Checks

If options.security is configured in your capabilities file, CAPA applies security checks during skill installation:

  • Blocked phrases: When present, skills are scanned for forbidden phrases. If found, installation stops immediately and reports which skill (or plugin skill) and file contains the phrase. No skills are installed until the issue is resolved. Omit or comment out blockedPhrases to disable.
  • Character sanitization: When present, characters outside the allowed set are replaced with spaces. A hardcoded baseline (printable ASCII + standard whitespace) is always preserved, so markdown-critical characters like -, :, ", ', and newlines are never stripped. The allowedCharacters value extends the baseline with extra Unicode ranges. Omit or comment out allowedCharacters to disable.

See the Capabilities File - security options for configuration details.

Tool Exposure Warning

During install, CAPA checks which tools are required by at least one skill (or provided by a plugin). Tools that are defined in your capabilities file but not required by any skill are not exposed to MCP clients (in both expose-all and on-demand modes). If any such tools exist, capa install prints a warning listing them and reminds you to add them to the requires array of the skills that use them.

When to Use

  • After creating or modifying the capabilities file
  • When adding new skills, tools, or plugins
  • To refresh the CAPA server configuration
  • When setting up a project on a new machine

Related Commands