CAMI Documentation

CLI Commands Reference

CAMI provides a command-line interface for agent management operations. While the MCP server (natural language with Claude) is the primary interface, the CLI is useful for scripting, CI/CD pipelines, and direct terminal usage.

Quick Reference

bash
# Core commands
cami --mcp                          # Start MCP server (primary interface)
cami list                           # List available agents
cami deploy                         # Deploy agents to project
cami scan                           # Scan deployed agents
cami update-docs                    # Update CLAUDE.md
# Source management
cami source add <git-url>           # Add agent source
cami source list                    # List sources
cami source update [name]           # Update sources (git pull)
cami source status                  # Show git status
cami source remove <name>           # Remove source
# Location management
cami locations                      # List locations
cami location add -n <name> -p <path>
cami location remove -n <name>
# Help and info
cami --help                         # Show help
cami --version                      # Show version
cami <command> --help               # Command-specific help

Core Commands

cami --mcp

Purpose: Start CAMI as an MCP server for Claude Code integration.

Usage:

bash
cami --mcp

When to Use:

  • Claude Code integration (configured in ~/.config/claude/mcp.json)
  • Automatic startup by Claude Code
  • Never run manually (Claude manages the process)

How It Works:

  1. Loads configuration from ~/cami-workspace/config.yaml
  2. Initializes MCP server with stdio transport
  3. Registers all 19 MCP tools
  4. Waits for tool calls from Claude Code
  5. Logs to stderr for debugging

Configuration:

In ~/.config/claude/mcp.json:

json
{
  "mcpServers": {
    "cami": {
      "command": "cami",
      "args": ["--mcp"]
    }
  }
}

Output: None (runs as background server until Claude Code exits)

Troubleshooting:

  • No output: Normal behavior (stdio used for MCP protocol)
  • Logs: Check Claude Code's MCP console
  • Errors: Logged to stderr, visible in Claude Code

See Also:

cami list

Purpose: List all available agents from configured sources.

Usage:

bash
cami list

Output Example:

text
Available agents (12 total):
## Core (3 agents)
• architect (v3.2.0)
  Expert application architect specializing in system design
• backend (v2.1.0)
  Back-end specialist for Node.js and API development
• frontend (v2.0.1)
  Front-end specialist for React and modern web UIs
## Specialized (2 agents)
• designer (v1.1.0)
  Visual design and UI/UX specialist
• qa (v1.0.0)
  Quality assurance and testing specialist

Details:

  • Groups agents by category (from folder structure)
  • Shows name, version, and description
  • Uses priority-based deduplication (lowest priority number wins)
  • Requires configured sources (cami source add first)

Error Conditions:

  • No sources configured: Error with setup instructions
  • Sources exist but no agents found: Empty list with warning

See Also:

  • cami source list - View configured sources
  • cami scan - Check deployed versions

cami deploy

Purpose: Deploy selected agents to a project directory.

Usage:

bash
cami deploy --agents <names> --location <path> [--overwrite]
cami deploy -a <names> -l <path> [-o]

Parameters:

  • -a, --agents <names> - Comma-separated agent names (required)
  • -l, --location <path> - Target project path (required)
  • -o, --overwrite - Replace existing agents (default: false)
  • --output <format> - Output format: text or json (default: text)

Examples:

Basic deployment:

bash
cami deploy -a frontend,backend -l ~/projects/my-app

Output:

text
Deployment Results:
  ✓ frontend: Deployed successfully
  ✓ backend: Deployed successfully
Summary:
  Deployed: 2

With overwrite:

bash
cami deploy -a frontend -l ~/projects/my-app --overwrite

JSON output:

bash
cami deploy -a frontend,backend -l ~/projects/my-app --output json

Output:

json
{
  "success": true,
  "deployed": ["frontend", "backend"],
  "failed": [],
  "conflicts": [],
  "results": [
    {
      "agent": "frontend",
      "status": "success",
      "message": "Deployed successfully"
    },
    {
      "agent": "backend",
      "status": "success",
      "message": "Deployed successfully"
    }
  ]
}

Conflict Handling:

When agent already exists and overwrite=false:

text
Deployment Results:
  ⚠ frontend: File already exists (use --overwrite to replace)
Summary:
  Deployed: 0
  Conflicts: 1

Exit Codes:

  • 0: All agents deployed successfully
  • 1: One or more agents failed or conflicts

See Also:

  • cami list - See available agents
  • cami scan - Check deployed versions

cami scan

Purpose: Scan a project to discover deployed agents and check for updates.

Usage:

bash
cami scan --location <path>
cami scan -l <path>

Parameters:

  • -l, --location <path> - Project path to scan (required)

Example:

bash
cami scan -l ~/projects/my-app

Output:

text
Scanning /Users/you/projects/my-app
Found 3 deployed agents
✓ frontend: up-to-date (deployed: v2.0.1, available: v2.0.1)
⚠ backend: update-available (deployed: v1.5.0, available: v2.1.0)
○ designer: not-deployed

Status Indicators:

  • up-to-date: Deployed version matches source
  • update-available: Newer version in sources
  • not-deployed: Available but not deployed

Use Cases:

  • Before updating agents
  • Auditing unknown projects
  • Checking project state

See Also:

  • cami deploy - Deploy updates
  • cami source update - Pull latest source versions

cami update-docs

Purpose: Update project's CLAUDE.md with deployed agent documentation.

Usage:

bash
cami update-docs --location <path>
cami update-docs -l <path>

Parameters:

  • -l, --location <path> - Project path (required)

Example:

bash
cami update-docs -l ~/projects/my-app

Output:

text
Updated CLAUDE.md at /Users/you/projects/my-app
Documented 3 agents:
  • frontend (v2.0.1)
  • backend (v2.1.0)
  • designer (v1.1.0)

What Gets Updated:

CAMI inserts or updates a managed section in CLAUDE.md:

markdown
<!-- CAMI-MANAGED: DEPLOYED-AGENTS | Last Updated: 2025-11-24T10:30:00Z -->
## Deployed Agents
### frontend (v2.0.1)
Front-end specialist for React and modern web UIs.
### backend (v2.1.0)
Back-end specialist for Node.js API development.
<!-- /CAMI-MANAGED: DEPLOYED-AGENTS -->

Behavior:

  • Creates CLAUDE.md if doesn't exist
  • Preserves user content outside managed sections
  • Safe to run multiple times (idempotent)

See Also:

  • cami deploy - Deploy before documenting
  • cami scan - Verify deployed agents

Source Management

cami source add

Purpose: Clone a Git repository of agents and register it as a source.

Usage:

bash
cami source add <git-url> [options]

Parameters:

  • <git-url> - Git repository URL (required)
  • -n, --name <name> - Source name (derived from URL if omitted)
  • -p, --priority <number> - Priority (default: 50)

Examples:

Basic add:

bash
cami source add git@github.com:company/agents.git

Output:

text
Cloning agents to ~/cami-workspace/sources/agents...
✓ Cloned agents to ~/cami-workspace/sources/agents
✓ Added source with priority 50
✓ Found 12 agents

With custom name and priority:

bash
cami source add git@github.com:company/agents.git --name company-agents --priority 10

Clone Location:

  • Default: ~/cami-workspace/sources/<name>/
  • With CAMI_DIR: $CAMI_DIR/sources/<name>/

Priority: Lower numbers = higher precedence. Personal agents typically use low numbers (10), official agents use higher numbers (100).

Config Update:

Adds entry to ~/cami-workspace/config.yaml:

yaml
agent_sources:
  - name: company-agents
    type: local
    path: /Users/you/cami-workspace/sources/company-agents
    priority: 10
    git:
      enabled: true
      remote: git@github.com:company/agents.git

See Also:

  • cami source list - View configured sources
  • cami source update - Pull latest changes

cami source list

Purpose: View all configured agent sources.

Usage:

bash
cami source list

Output Example:

text
Agent Sources:
  official-agents (priority 50)
    Path: /Users/you/cami-workspace/sources/official-agents
    Agents: 15
    Git: git@github.com:lando/official-agents.git
  team-agents (priority 30)
    Path: /Users/you/cami-workspace/sources/team-agents
    Agents: 8
    Git: git@github.com:company/team-agents.git
  my-agents (priority 10)
    Path: /Users/you/cami-workspace/sources/my-agents
    Agents: 2

Details:

  • Shows all configured sources
  • Displays priority (for deduplication)
  • Counts agents in each source
  • Shows Git remote if configured

Empty State:

text
No agent sources configured.
Add a source with: cami source add <git-url>

See Also:

  • cami source add - Add new sources
  • cami list - View all available agents (deduplicated)

cami source update

Purpose: Pull latest changes from Git for agent sources.

Usage:

bash
cami source update [name]

Parameters:

  • [name] - Optional: specific source name (updates all if omitted)

Examples:

Update all sources:

bash
cami source update

Output:

text
Updating official-agents...
  ✓ Updated
Updating team-agents...
  ✓ Up to date
Updating my-agents...
Updated: official-agents
Skipped (no git remote): my-agents

Update specific source:

bash
cami source update team-agents

Output:

text
Updating team-agents...
  ✓ Updated
Updated: team-agents

Behavior:

  • Runs git pull in each source directory
  • Skips sources without Git configuration
  • Continues on error (updates what it can)

After Updating:

  • cami list shows new versions
  • cami deploy uses updated content
  • cami scan detects available updates

See Also:

  • cami source status - Check for uncommitted changes first
  • cami scan - Find projects needing updates

cami source status

Purpose: Show Git working tree status for agent sources.

Usage:

bash
cami source status

Output Example:

text
Agent Source Status:
  official-agents
    Git: ✓ clean
  team-agents
    Git: ⚠ 3 uncommitted changes
      M frontend.md
      M backend.md
      ?? new-agent.md
  my-agents
    Git: not enabled

Status Indicators:

  • clean: No uncommitted changes
  • N uncommitted changes: Modified/added files
  • not enabled: No Git configuration

Use Case:

Before updating sources:

bash
cami source status        # Check for changes
# Review uncommitted work
cami source update        # Pull latest

See Also:

  • cami source update - Pull latest changes

cami source remove

Purpose: Remove an agent source from configuration.

Usage:

bash
cami source remove <name>

Parameters:

  • <name> - Source name to remove (required)

Example:

bash
cami source remove old-agents

Output:

text
✓ Removed source "old-agents" from configuration
Note: Directory ~/cami-workspace/sources/old-agents still exists.
Remove it manually with: rm -rf ~/cami-workspace/sources/old-agents

Important:

  • Only removes from config (doesn't delete files)
  • To delete files: rm -rf ~/cami-workspace/sources/<name>
  • Reversible: just cami source add again

See Also:

  • cami source list - View configured sources

Location Management

cami locations

Purpose: List all configured deployment locations.

Usage:

bash
cami locations [--output <format>]

Parameters:

  • --output <format> - Output format: text or json (default: text)

Example:

bash
cami locations

Output:

text
Configured Deployment Locations (3):
NAME            PATH
----            ----
my-app          /Users/you/projects/my-app
api-backend     /Users/you/projects/api-backend
landing-page    /Users/you/projects/landing-page

JSON Output:

bash
cami locations --output json
json
{
  "locations": [
    {
      "name": "my-app",
      "path": "/Users/you/projects/my-app"
    },
    {
      "name": "api-backend",
      "path": "/Users/you/projects/api-backend"
    }
  ],
  "count": 2
}

Empty State:

text
No deployment locations configured.
To add a location:
  cami location add --name <name> --path <path>

See Also:

  • cami location add - Register locations
  • cami location remove - Unregister locations

cami location add

Purpose: Register a project directory as a deployment location.

Usage:

bash
cami location add --name <name> --path <path>
cami location add -n <name> -p <path>

Parameters:

  • -n, --name <name> - Friendly location name (required)
  • -p, --path <path> - Absolute project path (required)

Examples:

Add location:

bash
cami location add -n my-app -p ~/projects/my-app

Output:

text
Successfully added location 'my-app' -> /Users/you/projects/my-app

With absolute path:

bash
cami location add -n api-backend -p /Users/you/projects/api-backend

Validation:

  • Name must be unique
  • Path must exist
  • Path must be a directory
  • Path must be absolute (or ~ is expanded)

Error Conditions:

bash
# Duplicate name
cami location add -n my-app -p ~/projects/other
# Error: location with name "my-app" already exists
# Path doesn't exist
cami location add -n test -p ~/nonexistent
# Error: path does not exist: /Users/you/nonexistent

See Also:

  • cami locations - View saved locations
  • cami location remove - Unregister locations

cami location remove

Purpose: Unregister a deployment location.

Usage:

bash
cami location remove --name <name>
cami location remove -n <name>

Parameters:

  • -n, --name <name> - Location name to remove (required)

Example:

bash
cami location remove -n my-app

Output:

text
Successfully removed location 'my-app'

Important:

  • Only removes from config (doesn't delete project)
  • No impact on deployed agents
  • Reversible: just cami location add again

See Also:

  • cami locations - View locations
  • cami location add - Re-register locations

Global Options

--help

Purpose: Show help information for CAMI or specific commands.

Usage:

bash
cami --help              # Global help
cami <command> --help    # Command-specific help

Examples:

bash
cami --help                # Show all commands
cami deploy --help         # Deployment options
cami source --help         # Source management commands
cami source add --help     # Specific subcommand help

--version

Purpose: Display CAMI version information.

Usage:

bash
cami --version
cami -v

Output:

text
CAMI v0.3.0
Claude Agent Management Interface

Scripting and Automation

JSON Output Mode

Many commands support --output json for scripting:

bash
# Get deployment results as JSON
result=$(cami deploy -a frontend -l ~/projects/my-app --output json)
echo "$result" | jq '.deployed[]'
# Get locations as JSON
locations=$(cami locations --output json)
echo "$locations" | jq '.locations[].name'

Exit Codes

CAMI uses standard exit codes for scripting:

bash
# Success
cami deploy -a frontend -l ~/projects/my-app
echo $?  # 0
# Failure (agent not found)
cami deploy -a nonexistent -l ~/projects/my-app
echo $?  # 1
# Check exit code
if cami deploy -a frontend -l ~/projects/my-app; then
  echo "Deployment succeeded"
else
  echo "Deployment failed"
fi

Scripting Examples

Deploy agents to multiple projects:

bash
#!/bin/bash
projects=(
  "~/projects/app-1"
  "~/projects/app-2"
  "~/projects/app-3"
)
for project in "${projects[@]}"; do
  echo "Deploying to $project..."
  cami deploy -a frontend,backend -l "$project" --overwrite
done

Check for updates across projects:

bash
#!/bin/bash
# Get all configured locations
locations=$(cami locations --output json | jq -r '.locations[].path')
for location in $locations; do
  echo "Checking $location..."
  cami scan -l "$location"
  echo ""
done

Update sources and deploy to projects:

bash
#!/bin/bash
set -e  # Exit on error
# Update all sources
echo "Updating agent sources..."
cami source update
# Deploy to configured projects
echo "Deploying to projects..."
cami deploy -a frontend,backend -l ~/projects/app-1 --overwrite
cami deploy -a frontend,backend -l ~/projects/app-2 --overwrite
# Update documentation
echo "Updating documentation..."
cami update-docs -l ~/projects/app-1
cami update-docs -l ~/projects/app-2
echo "Deployment complete!"

CI/CD Integration

GitHub Actions Example

yaml
name: Deploy CAMI Agents
on:
  push:
    branches: [main]
    paths:
      - '.claude/agents/**'
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install CAMI
        run: |
          curl -sSL https://install.cami.run | bash
          echo "$HOME/.cami/bin" >> $GITHUB_PATH
      - name: Deploy agents
        run: |
          cami deploy -a frontend,backend -l . --overwrite
          cami update-docs -l .
      - name: Commit changes
        run: |
          git config user.name "CAMI Bot"
          git config user.email "cami@example.com"
          git add CLAUDE.md
          git commit -m "Update agent documentation" || true
          git push

Pre-commit Hook

bash
#!/bin/bash
# .git/hooks/pre-commit
# Check if agent sources have uncommitted changes
if ! cami source status | grep -q "✓ clean"; then
  echo "Error: Agent sources have uncommitted changes"
  echo "Commit or stash changes in ~/cami-workspace/sources/ first"
  exit 1
fi
# Ensure CLAUDE.md is up to date
if [[ -f CLAUDE.md ]]; then
  cami update-docs -l .
  git add CLAUDE.md
fi

Comparison: CLI vs MCP Tools

OperationCLI CommandMCP Tool (via Claude)Best For
List agentscami list"What agents are available?"CLI: Scripts / MCP: Interactive
Deploy agentscami deploy -a X,Y -l PATH"Deploy X and Y to my-app"CLI: Automation / MCP: Ad-hoc
Add sourcecami source add URL"Add source from URL"CLI: Setup scripts / MCP: First-time
Update sourcescami source update"Update all sources"CLI: Cron jobs / MCP: Manual
Scan projectcami scan -l PATH"What agents are deployed here?"CLI: Audits / MCP: Discovery

When to Use CLI:

  • Scripting and automation
  • CI/CD pipelines
  • Batch operations
  • Cron jobs
  • Non-interactive environments

When to Use MCP (Claude):

  • Interactive agent management
  • Natural language workflows
  • Complex multi-step operations
  • Learning and exploration
  • Context-aware decisions

Environment Variables

CAMI_DIR

Purpose: Override default CAMI workspace location.

Default: ~/cami-workspace

Usage:

bash
export CAMI_DIR=~/my-custom-cami-workspace
cami source add git@github.com:company/agents.git
# Clones to ~/my-custom-cami-workspace/sources/agents

Affects:

  • Source clone location
  • Config file location ($CAMI_DIR/config.yaml)
  • Central manifest location
  • Backup locations

Configuration Files

Config Location

Default: ~/cami-workspace/config.yaml

With CAMI_DIR: $CAMI_DIR/config.yaml

Manual Config Editing

While CLI commands update config automatically, you can edit manually:

bash
# Open config in editor
$EDITOR ~/cami-workspace/config.yaml
# Validate config (implicit on next command)
cami source list

See Also:

Troubleshooting

Command Not Found

bash
$ cami --version
bash: cami: command not found

Solution:

bash
# Check if CAMI is installed
which cami
# If not installed, install via:
# - Binary release
# - Build from source: cd ~/cami && make install
# - Check PATH includes installation directory

Permission Denied

bash
$ cami source add git@github.com:company/agents.git
Error: failed to create config directory: permission denied

Solution:

bash
# Ensure you have write access to home directory
mkdir -p ~/cami-workspace
chmod 755 ~/cami-workspace
# Or use custom CAMI_DIR
export CAMI_DIR=/path/with/permissions

Git Authentication

bash
$ cami source add git@github.com:company/agents.git
Error: failed to clone repository: Permission denied (publickey)

Solution:

bash
# Ensure SSH key is configured
ssh -T git@github.com
# Or use HTTPS with credentials
cami source add https://github.com/company/agents.git

No Sources Configured

bash
$ cami list
Error: no agent sources configured

Solution:

bash
# Add an agent source first
cami source add git@github.com:lando/agents.git
# Then list agents
cami list

Related Documentation

Last Updated: 2025-11-24