agentspec-cli

The official CLI for AgentSpec — install, manage, and switch between AI agent configurations (configs, skills, rules, and specs) from the command line.

Installation

# Install globally
npm install -g agentspec-cli

# Or run without installing
npx agentspec-cli install <id>

Requirements: Node.js 18 or later.

Quick Start

# Browse and install a Claude Code config
agentspec list configs --framework ClaudeCode
agentspec install my-claude-config

# Install a skill for Codex
agentspec install my-skill --framework Codex

# Activate a full spec (installs all configs + skills + rules at once)
agentspec use my-team-spec

# Check what's installed
agentspec status

# Update everything to the latest version
agentspec update --all

Commands

agentspec install <id>

Install a config, skill, rule, or spec by ID or slug.

agentspec install <id|slug> [options]

| Option | Description | | -------------------- | --------------------------------------------- | | --type <type> | Skip auto-detect: config\|skill\|rule\|spec | | --framework <name> | Target framework for skills (skips prompt) | | --file-type <type> | Target file type for rules (skips prompt) | | --global | Install globally as a symlink | | --project | Install to current project as a file copy | | --dry-run | Preview without writing any files |

Scope behavior:

• Project (--project): Writes a real file copy to your project directory. The file can be edited and committed to git. After agentspec update, re-install to refresh the copy.
• Global (--global): Creates a symlink from the standard tool location (e.g. ~/.claude/settings.json) to ~/.agentspec/store/<slug>/content. Updating the store automatically updates the symlinked file everywhere.
• If the content type does not support global installation, defaults to --project.
• If neither flag is set, you are prompted interactively.

Examples:

# Install a config (prompts for scope)
agentspec install my-claude-config

# Install globally without prompt
agentspec install my-claude-config --global

# Install a skill for a specific framework
agentspec install code-review-skill --framework ClaudeCode --project

# Install a rule as a specific file type
agentspec install no-todos-rule --file-type claude-md

# Preview what would happen
agentspec install my-team-spec --dry-run

agentspec uninstall <id>

Remove an installed config, skill, or rule.

agentspec uninstall <id|slug> [options]

| Option | Description | | ----------- | --------------------------- | | --global | Uninstall from global scope | | --project | Uninstall from this project |

For global installs: removes the symlink and restores the original file from backup (if one was saved).

For project installs: prompts whether to keep the file (just stop tracking) or delete it from disk.

agentspec uninstall my-claude-config
agentspec uninstall my-claude-config --global

agentspec update [slug]

Update installed items to their latest version from agentspec.sh.

agentspec update [slug] [options]

| Option | Description | | ----------- | ------------------------------------------------------------ | | --all | Update all items in the store | | --check | Only check for updates, do not apply | | --force | Overwrite even if the local store copy was manually modified | | --dry-run | Preview without writing anything |

Update detection uses SHA-256 content hashes. If your local store copy was manually edited, the update is skipped unless --force is passed.

Note: Global installs (symlinks) automatically reflect store updates. Project installs (file copies) need to be re-installed after an update.

# Check if any updates are available
agentspec update --check

# Update a single item
agentspec update my-claude-config

# Update everything, overwriting local edits
agentspec update --all --force

agentspec use <spec>

Activate a spec — installs all its configs, skills, and rules in one shot.

agentspec use <spec-id|spec-slug> [options]

| Option | Description | | ----------- | ------------------------------------ | | --global | Activate globally | | --project | Activate for this project only | | --none | Deactivate the currently active spec | | --dry-run | Preview without writing files |

Activating a new spec automatically deactivates the previously active one first. All items installed by the spec are tracked — agentspec use --none cleanly removes them all.

# Activate a spec for this project
agentspec use my-team-spec --project

# Activate globally
agentspec use my-team-spec --global

# Deactivate the current spec
agentspec use --none

agentspec status

Show currently installed items and the active spec.

agentspec status [options]

| Option | Description | | ---------- | --------------------------------------------------------- | | --global | Show global installation state | | --store | List all items in the local store (~/.agentspec/store/) |

# Show what's installed in the current project
agentspec status

# Show globally installed items
agentspec status --global

# List everything in the local store
agentspec status --store

agentspec search <query>

Search for configs, skills, rules, specs, and plugins on agentspec.sh.

agentspec search <query> [options]

| Option | Description | | --------------- | ------------------------------------------------------------------------- | | --type <type> | Filter by type: all\|config\|skill\|rule\|spec\|plugin (default: all) | | --limit <n> | Max results (default: 10, max: 50) |

agentspec search "code review"
agentspec search "strict typescript" --type config
agentspec search "refactoring" --type skill --limit 5

agentspec list <type>

Browse configs, skills, rules, or specs on agentspec.sh.

agentspec list <configs|skills|rules|specs> [options]

| Option | Description | | -------------------- | ------------------------------------------------ | | --sort <sort> | Sort: hot\|new\|top\|installs (default: hot) | | --framework <name> | Filter by framework | | --file-type <type> | Filter rules by file type | | --limit <n> | Number of results (default: 20, max: 100) | | --offset <n> | Pagination offset (default: 0) |

# List top Claude Code configs
agentspec list configs --framework ClaudeCode --sort top

# Latest skills for Codex
agentspec list skills --framework Codex --sort new

# Browse CLAUDE.md rules
agentspec list rules --file-type claude-md

# Next page
agentspec list specs --limit 20 --offset 20

agentspec info <id>

Show details for a config, skill, rule, spec, or plugin.

agentspec info <id|slug> [options]

| Option | Description | | --------------- | ----------------------------------------------------- | | --type <type> | Skip auto-detect: config\|skill\|rule\|spec\|plugin |

Displays title, slug, author, vote count, install count, description, supported frameworks/file types, install paths, and a content preview.

agentspec info my-claude-config
agentspec info abc123 --type skill

Global Store

The CLI stores all content in ~/.agentspec/ (override with $AGENTSPEC_HOME):

~/.agentspec/
├── global-state.json        # Active spec + globally installed items
├── store/
│   └── <slug>/
│       ├── content          # Raw file content
│       └── meta.json        # ID, type, title, framework, fetched date, content hash
├── backups/                 # Originals replaced by global symlinks
└── projects/
    └── <project-hash>/
        └── state.json       # Per-project active spec + installed items

Items are always saved to the store regardless of install scope. This means:

• Global symlinks automatically pick up agentspec update changes.
• Project copies need to be re-installed after an update.

Supported Frameworks & Install Paths

Configs

| Framework | Project path | Global path | | ------------ | ----------------------- | ---------------------------------- | | ClaudeCode | .claude/settings.json | ~/.claude/settings.json | | Codex | codex.toml | ~/.codex/codex.toml | | OpenCode | opencode.json | ~/.config/opencode/opencode.json |

Skills

| Framework | Project directory | Global directory | | ------------ | ------------------- | --------------------- | | ClaudeCode | .claude/skills/ | ~/.claude/skills/ | | Codex | .codex/skills/ | ~/.codex/skills/ | | OpenCode | .opencode/skills/ | ~/.opencode/skills/ | | Windsurf | .windsurf/skills/ | (no global) | | Universal | skills/ | (no global) |

Rules

Rules are always installed as project files (no global scope).

Design principle: rules are installed into per-agent directories (e.g. .claude/rules/, .cursor/rules/, .agents/). Your project's primary agent instruction file (CLAUDE.md, AGENTS.md, GEMINI.md, …) is NOT modified — rules coexist with your instructions via each agent's directory-based discovery mechanism. The only exception is gemini-md, because Gemini Code Assist does not yet support a rules directory.

| File Type | Install Path | Agent | | ---------------------- | --------------------------------------------- | --------------------- | | claude-md | .claude/rules/<slug>.md | Claude Code | | agents-md | .agents/<slug>.md | OpenCode / Codex | | cursorrules | .cursor/rules/<slug>.mdc | Cursor (legacy key) | | cursor-rules | .cursor/rules/<slug>.mdc | Cursor | | copilot-instructions | .github/instructions/<slug>.instructions.md | GitHub Copilot | | windsurfrules | .windsurf/rules/<slug>.md | Windsurf (legacy key) | | windsurf-rules | .windsurf/rules/<slug>.md | Windsurf | | clinerules | .clinerules/<slug>.md | Cline | | gemini-md | GEMINI.md | Gemini |

Environment Variables

| Variable | Default | Description | | ------------------- | -------------------------- | --------------------------------------------------- | | AGENTSPEC_HOME | ~/.agentspec | Override the global store location | | AGENTSPEC_API_URL | https://api.agentspec.sh | Override the API base URL (useful for self-hosting) |

Troubleshooting

Logs

Every command writes a structured log to ~/.agentspec/logs/cli.log (override the directory with $AGENTSPEC_HOME). The log captures:

• Command invocation (with args and options)
• Every HTTP call to the AgentSpec API (endpoint, status, latency)
• Install/uninstall results and errors with full stack traces

If a command fails silently or behaves unexpectedly, this is the first place to look:

tail -f ~/.agentspec/logs/cli.log

The log rotates automatically when it exceeds 5 MB — the previous generation is kept at ~/.agentspec/logs/cli.log.1. Safe to delete at any time.

License

MIT