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, 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

Tokens are minted at /settings/tokens and start with bd_ (you can also pass one via the BOTDOCS_TOKEN environment variable). New CLI tokens expire after 30 days by default (90-day maximum) — long-lived tokens aren't available on the free tier. When a token expires, mint a fresh one and re-run botdocs login --token.

Devices & sessions. Each machine registers as a device on login. A free account allows 4 connected devices, with 2 active at once (15-minute window); a new device past the cap is refused (device_cap_exceeded, 403) and a 3rd concurrent device gets a temporary session_limit_exceeded (429). Manage and revoke devices at Settings → Devices & access. For ephemeral CI fleets, export a shared BOTDOCS_DEVICE_ID across runners so they count as a single device and don't trip the caps.

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 every supported install ecosystem. ingest also discovers Claude Code subagents.

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

Ingested skills land in your library immediately — they're private to your account and there's no separate review/approval step (the CLI's confirmation links you to /library). Skills are CLI-discoverable by default; if you've hidden one, botdocs publish @you/<slug> makes it discoverable from your CLI again.

Re-ingesting a slug you already own surfaces a 409 conflict: --force replaces a colliding draft or soft-deleted skill, but never a published-live one (delete or unpublish that first). Per-skill caps apply: 64 KB per file, 512 KB per skill, 25 files per skill; binaries and symlinks are skipped.

Free-tier cap. A free account can own up to 10 skills (a bundle counts as one). Ingesting or creating beyond that returns skill_cap_exceeded and the whole ingest batch is rejected — delete a skill to free space.

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

Skills are private to your account by default. Publishing adds a skill to your library and makes it discoverable from your CLI — there is no public registry and no review gate. Scaffold a skill, then publish it:

botdocs init my-skill              # scaffold the canonical multi-ecosystem layout (default)
botdocs init my-skill --spec       # legacy single index.md + botdocs.json scaffold
# edit the source, fill in description in botdocs.json
botdocs validate my-skill/         # warns + errors before publish
botdocs publish my-skill/          # adds the skill to your library (private, CLI-discoverable)
botdocs publish @you/my-skill      # make an existing skill discoverable from your CLI

publish accepts --dry-run (preview the payload and size against the per-file/per-skill caps without uploading), --no-compile (skip ecosystem compilation), and --yes (skip the confirm prompt). Server caps are 64 KB per file and 512 KB per skill.

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    # hide it from the CLI (stays in your web library)
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 layout is the default
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

For Hermes agents (and other self-improving agents)

If your agent improves a skill it installed from BotDocs, push the improvement back as a reviewable proposal rather than overwriting the upstream skill. For a skill you don't own, nothing you push goes live on its own — the author reviews and accepts it.

1. Recover the skill's upstream ref. The CLI records every install in ~/.botdocs/installed.json — an installs array where each entry has a ref (@author/slug) and version. Cross-reference the skill directory you edited against that lockfile to recover its ref. (BotDocs skills also carry name:/description: frontmatter and a canonical SKILL.md layout.)

2. Make your revision on disk, then propose it back:

botdocs login                                   # required — the proposal is attributed to you
botdocs propose @author/slug ./path/to/skill \
  --message "What changed and why" \
  --agent-label hermes-v2

propose collects the local markdown/files at the path (a directory or a single .md/.mdc file), fetches the skill's current live file set to compute a basedFileHash, and POSTs an OPEN proposal. Respect these facts:

• It's a proposal, not a publish. For a skill you don't own, the change lands in the author's review queue; you cannot accept it yourself.
• A proposal replaces the entire file set — it is not a patch. Submit the whole skill directory, not just the one file you changed, or accepting it would make that single file the entire skill.
• At least one markdown file is required (.md/.mdc); the canonical layout satisfies this. Proposals apply to skills, not bundles.
• --agent-label is self-reported and untrusted — the server caps its length and shows it to the author as unverified; it never confers trust.
• --message is the changelog the author sees.
• basedFileHash is a drift guard computed over the live set, not your change. If the skill moves before the author accepts, accepting fails with a stale_base error and they re-review.

The author accepts from the Proposals tab or with botdocs proposals accept @author/slug --id <id>, which publishes a new version.

When edit differs. botdocs edit @author/slug --ecosystem <name> is the interactive, LLM-assisted single-file path (BYOK). It revises one ecosystem file, shows a diff, then branches on ownership: editing your own skill pushes a draft you publish from the web; editing someone else's routes through the same proposal queue (labeled cli-edit). Use propose for a finalized multi-file revision; use edit for an interactive single-file tweak.

Caps & errors. Auth is required (botdocs login). The server caps how many open proposals a skill can hold and how many you can push per day — when you hit a limit the CLI prints it in a 429; very large proposals return 413. To propose on a private skill you must already be able to read it (author, team-shared, or public), or it resolves as not-found.

Hooking into a self-improvement loop. When your agent finalizes a skill revision (Hermes' on-task skill-update step, or a periodic reflection/cron pass), shell out to botdocs propose @author/slug <path> --message "…" --agent-label <your-agent-id>. A scheduled job can diff installed skills against their upstream ref and open proposals automatically — every push stays a reviewable proposal, never a silent overwrite.

Reference

Command	Purpose
init [name]	Scaffold a new skill directory (canonical multi-ecosystem layout by default; pass --spec for the legacy single-file scaffold).
validate <source>	Pre-publish structural check on a directory or file.
publish <source>	Add a skill to your library — local path uploads (private); @user/slug makes an existing skill discoverable from the CLI.
unpublish <ref>	Hide a skill from the CLI (it stays in your web library).
delete <ref>	Delete a BotDoc — drafts hard-delete; published soft-delete (hidden, history preserved).
login	Authenticate via browser-redirect; --token bd_xxx for CI (tokens expire in 30 days).
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; own skill → draft, others' → proposal).
propose <ref> [path]	Queue a change to a skill for its author to review (instead of publishing directly).
proposals <ref>	List a skill's proposal queue; proposals accept <ref> --id X accepts one (author-only).
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.