agents-repo CLI

Official CLI for installing and managing agents-repo packages from the open registry for supported install targets: GitHub Copilot, Cursor, Claude Code, and OpenAI Codex.

Install / run

npx agents-repo@latest --help
npx agents-repo@latest init --targets cursor
npx agents-repo@latest init --targets github-copilot claude-code openai-codex

--target remains an alias for --targets on init. In a fresh project without detectable install markers, pass --targets using a canonical id (for example cursor, github-copilot, claude-code, or openai-codex); otherwise init may exit with code 3.

After install, commit agents-lock.json (and agents.json when it changes) so installs stay reproducible. See docs/commands/init.md and docs/commands/install.md.

Development

npm run build
node dist/bin/agents-repo.js <command>

Commands (init, add-target, install, update, remove, search, suggest-agents, list, ci, doctor, and targets) are available today. npm alias parity is summarized in docs/npm-cli-parity.md. See docs/commands/init.md, docs/commands/add-target.md, docs/commands/install.md, docs/commands/update.md, docs/commands/remove.md, docs/commands/search.md, docs/commands/suggest-agents.md, docs/commands/list.md, docs/commands/ci.md, docs/commands/doctor.md, and docs/commands/targets.md.

Stack

• Node.js 22.x and 24.x LTS (minimum 22.12.0); engines.node is >=22.12.0 <25.0.0 for npm—supported lines are 22.x and 24.x (docs/development.md)
• Recommended for cli development: .nvmrc 24.18.0
• npm 12.x (packageManager pinned to [email protected])
• TypeScript
• Vitest for unit tests
• ESLint, markdownlint, and YAML lint for quality gates

Getting Started

nvm use
corepack enable npm
corepack prepare [email protected] --activate
npm ci

Common Commands

| Command | Purpose | | --- | --- | | npm run env:check | Verify Node/npm versions | | npm run lint:all | Markdown, ESLint, and YAML lint | | npm run typecheck | TypeScript check | | npm run test | Sync script tests + Vitest | | npm run check:secrets | Scan tracked files for secret patterns | | npm run build | Compile src/bin/agents-repo.ts to dist/ | | npm run sync:ide-instructions | Regenerate IDE instruction mirrors | | npm run agents:install | Install registry workflow packages from agents.json | | npm run agents:update | Refresh installed packages within semver ranges | | npm run slides:check | Check Marp fingerprints, PDF headers, and Chrome rebuild |

Run the full PR baseline locally:

npm run env:check && npm run lint:all && npm run typecheck && npm test && npm run check:secrets

CLI Commands

| Command | Documentation | | --- | --- | | init | docs/commands/init.md | | add-target | docs/commands/add-target.md | | install / i / add / inst | docs/commands/install.md | | update / up / upgrade | docs/commands/update.md | | remove / rm / uninstall / unlink | docs/commands/remove.md | | search / find / s / se | docs/commands/search.md | | suggest-agents / suggest | docs/commands/suggest-agents.md | | list / ls | docs/commands/list.md | | ci | docs/commands/ci.md | | doctor | docs/commands/doctor.md | | targets | docs/commands/targets.md | | npm parity matrix | docs/npm-cli-parity.md |

IDE Agent Instructions

| Tool | Path | | --- | --- | | GitHub Copilot | .github/copilot-instructions.md | | Cursor | .cursor/rules/agents-cli.mdc | | Claude Code | CLAUDE.md | | OpenAI Codex | AGENTS.md |

Regenerate after editing copilot-instructions.md:

npm run sync:ide-instructions

Do not edit .cursor/rules/agents-cli.mdc, CLAUDE.md, or AGENTS.md directly.

Platform repository dogfooding

Organization platform repositories (registry, webapp, cli, registry-proxy, and .github) commit agents.json, agents-lock.json, and CLI-extracted package paths alongside generated project-guideline mirrors. See organization CONTRIBUTING — Registry workflow packages for the shared install and mirror workflow.

Contributing

See .github/CONTRIBUTING.md, docs/development.md, and docs/npm-publishing.md (npm releases and trusted publishing).

Docs and repository pages

For user guides and cross-repo documentation, see agents-repo.org/docs/. For this repository's overview on the public site, see agents-repo.org/repositories/cli/.

Presentation slides: docs/slides/README.md.

When you change a user-facing or contributor workflow in this repository, update the corresponding page(s) in agents-repo/webapp under src/content/docs/ in the same PR or an immediate follow-up.