Agency CLI

A production-ready CLI tool for managing AI agents from the Agency collection.

Installation

Via npx (no installation required)

npx agency-agents-cli@latest list

Via npm (global install)

npm install -g agency-agents-cli

Via Homebrew (macOS/Linux)

brew tap msitarzewski/agency-agents
brew install agency

From Source

git clone https://github.com/msitarzewski/agency-agents.git
cd agency-agents/agency-agents-cli
npm install
npm run build
npm link

Quick Start

# 1. Set your Anthropic API key (for team recommendations)
agency config set apiKey sk-ant-...

# 2. List all available agents
agency list

# 3. Search for specific agents
agency search "react performance"

# 4. Get detailed info about an agent
agency info security-engineer

# 5. Install agents to your AI tool
agency install all --tool claude-code

Commands

agency list

List all available AI agents with filtering options.

# List all agents
agency list

# Filter by division
agency list --division engineering

# Search within list
agency list --search "security"

# Output as JSON
agency list --json

agency info <agent-slug>

Display detailed information about a specific agent.

agency info security-engineer
agency info frontend-developer --raw
agency info backend-architect --json

agency install <agent-name-or-all>

Install agents to your local AI coding tool.

# Install all agents (interactive tool selection)
agency install all

# Install to specific tool
agency install all --tool claude-code
agency install all --tool cursor

# Install specific agent
agency install backend-architect --tool cursor

# Force overwrite existing
agency install security-engineer --force

Supported Tools:

• Claude Code (~/.claude/agents/)
• Cursor (~/.cursor/rules/)
• Windsurf (~/.windsurf/rules/)
• Zed (~/.config/zed/agents/)

agency search <query>

Fuzzy search across all agents by name, description, and specialty.

agency search "react performance"
agency search "security"
agency search "backend api" --limit 5

agency team <project-description>

Get AI-powered team recommendations using Claude API.

agency team "building a SaaS analytics dashboard for enterprise clients"
agency team "mobile app with React Native and Node.js backend" --num-agents 4

agency config

Manage CLI configuration.

# Set API key
agency config set apiKey sk-ant-...

# Set default tool
agency config set defaultTool claude-code

# View all config
agency config list

# Get specific value
agency config get apiKey

# Delete a value
agency config delete defaultTool

agency update

Check for new agents and updates.

agency update
agency update --force

agency workflow

Manage multi-agent workflows.

# List workflows
agency workflow list

# Show workflow details
agency workflow show nexus-spatial-discovery

# Install workflow agents
agency workflow install fullstack-development

Configuration

Configuration is stored at ~/.agency/config.json.

| Key | Description | Example | |-----|-------------|---------| | anthropicApiKey | API key for team recommendations | sk-ant-... | | defaultTool | Default installation target | claude-code | | installedAgents | List of installed agent slugs | ["security-engineer"] |

Environment Variables

| Variable | Description | |----------|-------------| | ANTHROPIC_API_KEY | Alternative to config for API key | | AGENCY_CACHE_DIR | Custom cache directory | | AGENCY_CONFIG_DIR | Custom config directory |

Shell Completion

Bash

# Copy completion script
sudo cp completions/agency /etc/bash_completion.d/
source /etc/bash_completion.d/agency

Zsh

cp completions/_agency /usr/local/share/zsh/site-functions/
echo 'fpath=(/usr/local/share/zsh/site-functions $fpath)' >> ~/.zshrc

Fish

cp completions/agency.fish ~/.config/fish/completions/

Cache

The CLI caches agent data for 1 hour at ~/.agency/cache/ to reduce API calls.

# Clear cache
rm -rf ~/.agency/cache

Development

# Install dependencies
npm install

# Build TypeScript
npm run build

# Watch mode
npm run dev

# Run CLI
npm run agency -- list

# Generate completions
npm run generate-completions

# Build standalone binary
npx pkg . --targets node18-linux-x64,node18-macos-x64,node18-win-x64

Troubleshooting

"Failed to fetch agents"

• Check your internet connection
• GitHub API may be rate-limited (60 requests/hour without auth)
• Try agency update --force to refresh cache

"API key not configured"

• Run agency config set apiKey sk-ant-...
• Or set ANTHROPIC_API_KEY environment variable

"Tool not found"

• Ensure the target tool is installed
• The CLI auto-detects tools in standard locations
• Use --path flag to specify custom location

License

MIT License - see LICENSE for details.

Contributing

Contributions are welcome! Please read our Contributing Guide first.

Links

• Agency Agents Repository
• Report Issues
• npm Package