agent-toolkit-cli

The official CLI for agent-toolkit — install skills, agents, loops, and MCP configs across every major AI coding assistant.

Monorepo · Docs · Installation · CLI surfaces · Changelog

What is this package?

agent-toolkit-cli on npm is the Node adapter for the agent-toolkit monorepo (ADR-025). It is a thin launcher — no JavaScript business logic. The real CLI is the native V binary from GitHub Releases.

Same product name as PyPI. Same binary. Different install channel.

npm install -g agent-toolkit-cli
agent-toolkit install
agent-toolkit doctor

How the binary arrives

npm cannot ship one ELF for every OS the way pip ships platform-tagged wheels. Instead:

| Package | Role | |---------|------| | agent-toolkit-cli (this package) | Meta-package: bin/agent-toolkit → thin Node launcher | | agent-toolkit-cli-linux-x64 | glibc ELF (optionalDependency) | | agent-toolkit-cli-linux-arm64 | glibc ELF (optionalDependency) | | agent-toolkit-cli-darwin-arm64 | macOS arm64 Mach-O | | agent-toolkit-cli-darwin-x64 | macOS x86_64 Mach-O | | agent-toolkit-cli-win32-x64 | Windows PE |

On install, npm pulls the matching platform package via optionalDependencies. The launcher resolves that binary and spawns it with forwarded argv, stdio, signals, and exit code.

Platform notes

• Linux packages require glibc (ADR-019). Alpine/musl is not a MUST npm tag.
• Node ≥ 18
• Dev override: AGENT_TOOLKIT_BIN=/path/to/agent-toolkit

Quick start

# Global install (recommended for shells)
npm install -g agent-toolkit-cli
agent-toolkit install    # auto-detects Claude, Cursor, OpenCode, Windsurf, Pi, Copilot
agent-toolkit doctor

# Or project-local
npx agent-toolkit-cli doctor

Other installers

# PyPI (same CLI name, platform wheels)
uvx --from agent-toolkit-cli agent-toolkit install
uv tool install agent-toolkit-cli

# System packages (release notify → dedicated taps)
brew tap ulises-jeremias/homebrew-tap && brew install agent-toolkit
yay -S agent-toolkit-bin   # Arch Linux (AUR) — GitHub Release V binary; not the Python AUR package
docker pull ghcr.io/ulises-jeremias/agent-toolkit

# Direct binary
# https://github.com/ulises-jeremias/agent-toolkit/releases/latest

Full walkthrough: docs/INSTALLATION.md

Desktop GUI

Agent Toolkit Desktop is a standalone Electron app over the same V backend. It opens with a semantic pixel-art workspace and includes project interiors, People, Library, Operations, and real PTY terminals. Download the installer for your platform from GitHub Releases; a CLI or source checkout is not required to use Desktop. See the Desktop product guide and packaging notes.

Key concepts

Supported tools

| Tool | What install deploys | |------|------------------------| | Claude Code | Plugin manifest, skill references, settings | | Cursor | Marketplace plugins + .mdc rules (IDE + Agent CLI) | | OpenCode | System prompt overlays, agent configs | | GitHub Copilot | copilot-instructions.md with domain selection | | Windsurf | Rules and memory files via Cascade (~/.codeium/windsurf/) | | Pi Agent | Skills and loop templates in Pi's native format | | Muse Code | Agent Skills under ~/.config/muse/skills/ |

agent-toolkit install --tools claude-code,cursor
agent-toolkit install --dry-run
agent-toolkit install --force

Command reference

Everyday consumer commands vs advanced workstation / harness commands. Details: docs/CLI_SURFACES.md

Consumer

| Command | Purpose | |---------|---------| | install | Install profiles for detected or selected AI tools | | update | Refresh installed profiles from latest toolkit data | | uninstall | Remove toolkit-owned files using install receipts | | doctor | Check toolkit data and tool availability | | diff | Show changes vs currently installed plugin bundles | | skills | Sync, list, and validate skills | | mcp | MCP provider setup, health, doctor, uninstall | | plugin | Plugin bundle sync and check |

agent-toolkit skills list
agent-toolkit skills sync --tools claude-code,cursor
agent-toolkit mcp setup github
agent-toolkit doctor --fix

Advanced

Still on the same binary — start here when running an agentic-harness-style workspace:

| Command | Purpose | |---------|---------| | loop | Loop engineering: init, run, status, audit, cost, schedule, sync | | workspace | Workspace scaffolding: init, context, personas, packs | | memory | Knowledge base: add, search, inject, review, todo | | project | Project index: clone, list, add, remove, scan | | devcompanion | Background job queue (dc alias) | | insights | Local usage analytics (OpenCode, Cursor, Claude) | | inventory | List skills, agents, and products | | matrix | Platform capability matrix | | build / release | Compile / release artifacts (maintainer) |

Upgrade & uninstall

npm update -g agent-toolkit-cli
agent-toolkit update          # refresh deployed profiles
agent-toolkit uninstall       # remove toolkit-owned files via receipts

npm uninstall -g agent-toolkit-cli

→ docs/UNINSTALL.md

Ecosystem

agent-toolkit is the capability distribution layer (L1.5) in a personal DX stack:

| Layer | Repo | Role | |-------|------|------| | L1 | agentic-workstation | Machine provisioning — chezmoi, shell, packages, LLM policy | | L1.5 | agent-toolkit (this CLI) | Skills, loops, profiles, MCP | | L3 | agentic-harness | AI workspace scaffold — memory, personas, multi-repo orchestration |

Documentation

| Guide | Description | |-------|-------------| | README (monorepo) | Full product overview, skills, agents, packs | | INSTALLATION.md | Install paths per tool | | CLI_SURFACES.md | Consumer vs advanced commands | | ADR-025 | npm topology (meta + optionalDeps) | | TRUST.md | Trust boundaries and supply chain | | Wiki | Extended reference |

Publish uses GitHub Actions OIDC trusted publishing (.github/workflows/publish-npm.yml) — no long-lived NPM_TOKEN.

Canonical sources live in the agent-toolkit monorepo. This package is the installable npm distribution of that source of truth.

Requirements

• Node.js 18+
• Matching platform optionalDependency (installed automatically on supported OS/arch)
• At least one supported AI coding assistant (for install to deploy profiles)

Contributing

Issues and PRs welcome on the monorepo:

• Contributing guide
• Discord

git clone https://github.com/ulises-jeremias/agent-toolkit
cd agent-toolkit
node packages/npm/agent-toolkit-cli/bin/agent-toolkit.js --help
# Dev: AGENT_TOOLKIT_BIN=/path/to/native/agent-toolkit

MIT © ulises-jeremias · npm · PyPI · AUR · GitHub