agentspec CLI

Installation

# Install globally
npm install -g agentspec-cli

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

Requires node >= 18.

Quick Start

# Browse configs for Claude Code
agentspec list configs --framework ClaudeCode

# Install a config (prompts for scope: project or global)
agentspec install my-claude-config

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

# Activate a full spec (installs all items at once)
agentspec use my-team-spec

# Check what's installed in this project
agentspec status

# Update all installed items
agentspec update --all

Commands

agentspec install <id>

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

agentspec install <id|slug> [options]

# 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]

For global installs, removes the symlink and restores the original file from backup. For project installs, prompts to keep (stop tracking, leave file) or delete (remove 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. Uses SHA-256 content hashes to detect changes.

agentspec update [slug] [options]

# 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. Deactivating removes all items the spec installed.

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

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

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

# Deactivate the current spec (reverts all its files)
agentspec use --none

agentspec status

Show installed items and the active spec.

agentspec status [options]

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

# Show globally installed items
agentspec status --global

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

agentspec search <query>

Semantic search across configs, skills, rules, specs, and plugins.

agentspec search <query> [options]

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 with sorting and filtering.

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

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

# Latest Codex skills
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 — title, slug, author, vote count, install count, supported frameworks, install paths, and a content preview.

agentspec info <id|slug> [options]

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

Global Store

All content is cached 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, 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 scope. Global symlinks point at store/<slug>/content, so agentspec update changes are reflected automatically. Project copies must be re-installed after an update.

Frameworks & Install Paths

Configs

Skills

Rules (always project-scoped)

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.

Environment Variables