BotDocs CLI Quickstart

BotDocs is a registry of agent skills — the shared library teams use to keep their AI agents in sync. The botdocs CLI is the interface to that registry: ingest existing skills, search, install across agents, sync, publish, and manage teams from the terminal.

Bootstrap

Install via npm or pnpm (Node.js 20+):

npm install -g @botdocs/cli
# or
pnpm add -g @botdocs/cli

Authenticate by opening your browser:

botdocs login          # browser-redirect flow: opens /cli-auth, polls for the grant
botdocs whoami         # confirms you're signed in

For headless environments (CI, restricted shells), mint a token at /settings/tokens and pass it directly:

botdocs login --token bd_xxx

All commands accept --json for machine-readable output. Override the registry with BOTDOCS_API_URL (defaults to https://botdocs.ai).

Skill anatomy

A skill is a markdown file (or a directory of them) under a ref like @user/slug. The canonical layout lives in the published bundle and is what gets installed:

• claude/SKILL.md — Anthropic skill format with name: / description: YAML frontmatter. Always the entry point for the Claude family.
• claude/<adjacent-files> — scripts, templates, reference markdown bundled next to SKILL.md (post-#86 multi-file skills).
• claude-code/commands/<slug>.md — Claude Code slash command (flat).
• claude-code/agents/<slug>/AGENT.md — Claude Code subagent (nested, multi-file).
• cursor/rules/<slug>.mdc, windsurf/rules/<slug>.md, copilot/instructions/<slug>.instructions.md — flat per-ecosystem files.
• codex/<slug>/SKILL.md, antigravity/skills/<slug>/SKILL.md, opencode/<slug>/SKILL.md — nested SKILL.md ecosystems.
• chatgpt/<slug>.md, gemini/instructions/<slug>.md — manual-paste ecosystems (no canonical on-disk location).

install routes each canonical file to the right destination on the user's machine — ~/.claude/skills/, .cursor/rules/, .github/instructions/, .windsurf/rules/, etc. — across all 10 supported install ecosystems. ingest adds Claude Code subagents as an 11th discovery target.

Common workflows

Ingest existing skills

If you already have skills on disk (Claude ~/.claude/skills/, Cursor .cursor/rules/, slash commands, etc.) the fastest way to get them into BotDocs is ingest:

botdocs ingest                 # interactive sweep: discover everything, pick which to upload
botdocs ingest --auto          # non-interactive: upload everything discovery finds
botdocs ingest <path>          # ingest a specific directory
botdocs ingest ~/.claude/commands --from-tool=claude-code
                               # treat the path as a single ecosystem

Each ingested item is uploaded as a draft tagged ingest:<id>. You review at /ingest/<id> (or the /<ref> detail page), then flip it live with the publish toggle in your library — or from the CLI with botdocs publish @you/<slug>.

Search the registry

botdocs search "<topic>"            # human output
botdocs search "<topic>" --json     # for scripting

Install a team's shared skills

botdocs install @teamco/eng-skills

Files land in each agent's native location: ~/.claude/skills/teamco/..., .cursor/rules/, .github/instructions/, .windsurf/rules/, ~/.codex/skills/, ~/.config/opencode/skills/, ~/.gemini/antigravity/skills/, and so on. The CLI auto-detects which destinations apply based on what's in the bundle. ChatGPT and Gemini CLI files surface as manual-paste output (those ecosystems have no on-disk skill directory).

To install into a different ecosystem than the source (deterministic copy, no LLM):

botdocs install @teamco/eng-skills --to=cursor,windsurf
botdocs install @teamco/eng-skills --to=all

Stay current

botdocs sync                   # check for updates, apply clean ones
botdocs sync --dry-run         # preview without writing
botdocs sync @teamco/skill     # sync just one ref
botdocs check-updates          # one-line "N updates available" check (1h cached)

sync walks the lockfile (~/.botdocs/lockfile.json), applies clean updates, and double-confirms before overwriting any file you've edited locally. Files that would be overwritten are backed up to .botdocs-backup/ first; pass --no-backup to opt out (e.g. in CI). If you regret an overwrite, botdocs undo restores the most recent backup run — it's reversible, so running undo twice swaps back.

Update notifications

To get a one-line "updates available" notice on new terminals:

botdocs install-instructions --shell-hook         # install
botdocs install-instructions --remove-shell-hook  # uninstall

install-instructions (with no flags) writes an AGENTS.md block to the current project so any agent reading project context learns how to drive the CLI. Pass --print to send the block to stdout instead.

Publish your own skill

The draft → review → publish flow:

botdocs init my-skill              # scaffold index.md + botdocs.json
botdocs init my-skill --canonical  # scaffold canonical layout (claude-code source + ecosystems)
# edit the source, fill in description in botdocs.json
botdocs validate my-skill/         # warns + errors before publish
botdocs publish my-skill/          # uploads as a draft, server stores the bundle
botdocs publish @you/my-skill      # flip an existing draft live (publishes it)

validate must pass (no errors; warnings are OK) before publish lands. category in botdocs.json must be one of: KNOWLEDGE_MANAGEMENT, DEV_WORKFLOW, AUTOMATION, AGENT_CONFIG, PROJECT_SCAFFOLD, OTHER.

To hide a published skill again (without losing version history):

botdocs unpublish @you/my-skill    # back to draft; URL 404s for everyone but you
botdocs delete @you/my-skill       # drafts hard-delete; published soft-delete

Multi-ecosystem authoring (BYOK)

If you've set BOTDOCS_ANTHROPIC_KEY or BOTDOCS_OPENAI_KEY, you can generate per-ecosystem drafts from a single canonical source — inference runs locally with your key, BotDocs servers never see file contents:

botdocs init my-skill --canonical
botdocs compile my-skill/                       # generates claude/, cursor/, etc.
botdocs edit @you/my-skill --ecosystem cursor   # LLM-assisted revision → pushes a draft

Teams

Teams are shared skill libraries for an org. Pinned skills install automatically on every botdocs sync for every team member.

botdocs team list                                 # which teams am I in?
botdocs team create teamco --name "Team Co"       # ADMIN only on the new team
botdocs team show teamco                          # members + pinned skills
botdocs team add teamco <username> --role write   # invite an existing BotDocs user
botdocs team remove teamco <username>             # remove a member
botdocs team push teamco @user/skill              # pin a skill (WRITE+)
botdocs team push teamco @user/skill --version 3  # pin to a specific version
botdocs team unpush teamco @user/skill            # unpin
botdocs sync                                      # pulls personal + team-pinned skills

Skills stay user-owned; teams pin skills (no copy, no fork). To invite someone who isn't on BotDocs yet, use the team page's invite-by-email flow at /teams/<slug> — it sends them a signed invite link.

Backups & undo

Every command that would overwrite a file (install, sync) writes a backup run first. Browse and roll back from the CLI:

botdocs backups list           # backup runs sorted newest-first
botdocs backups list <ts>      # files in one run
botdocs backups diff <ts> <relpath>  # show what changed in a backup
botdocs backups restore <ts>   # restore one specific run
botdocs backups clear          # delete all backup runs
botdocs undo                   # restore the most recent backup (reversible)
botdocs undo --dry-run         # preview

Reference

Command	Purpose
init [name]	Scaffold a new BotDoc directory (use --canonical for the multi-ecosystem layout).
validate <source>	Pre-publish structural check on a directory or file.
search <query>	Search the registry.
publish <source>	Publish a BotDoc — local path uploads; @user/slug marks an existing draft live.
unpublish <ref>	Hide a published BotDoc (sets the draft flag back).
delete <ref>	Delete a BotDoc — drafts hard-delete; published soft-delete (hidden, history preserved).
login	Authenticate via browser-redirect; or pass --token bd_xxx for CI.
whoami	Show the current authenticated user.
install-instructions [target]	Write AGENTS.md (default) or install a shell hook for update notifications.
install <ref>	Install a skill or bundle; routes files to each agent's native location.
list	List installed skills and bundles (--outdated to filter).
uninstall <ref>	Remove an installed skill or bundle.
sync [ref]	Apply available updates; double-confirms on local edits.
check-updates	One-line update check (1-hour cached).
ingest [path]	Sweep the system (or a directory) and upload detected skills as drafts.
compile <path>	Generate per-ecosystem drafts from a canonical source (BYOK, local-only).
edit <ref>	LLM-assisted revision of a published skill's ecosystem file (BYOK; pushes a draft).
team	Manage teams: list, create, show, add, remove, push, unpush.
backups	Manage backup runs: list, restore, diff, clear.
undo	Restore files from the most recent backup run (reversible).

Run botdocs <command> --help for full flags.