botdocs

The official CLI for BotDocs — clone, search, publish, and endorse concept specifications.

A BotDoc is a structured spec an AI agent can build from. This CLI is the fastest way to pull one onto your machine, ship one of your own, or report back after you've built something on top.

Install

# one-off
npx @botdocs/cli <command>

# global (preferred — gives you the `botdocs` command)
npm i -g @botdocs/cli
# or
pnpm add -g @botdocs/cli

After a global install the binary is just botdocs:

botdocs --help

Requires Node.js 20 or newer.

Quick start

# scaffold a new spec in ./my-spec/
botdocs init my-spec

# validate before publishing
botdocs validate my-spec/

# log in (GitHub device code, one time)
botdocs login

# publish from a directory
botdocs publish my-spec/

# clone someone else's spec
botdocs clone @alice/agent-router

# tell them how it went after you built from it
botdocs endorse @alice/agent-router --rating positive \
  --comment "Built a working POC in 40 minutes."

Commands

Every command accepts --json for machine-readable output.

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

Configuration

Auth is stored at ~/.botdocs/auth.json after botdocs login. Delete it to log out.

Teaching agents to use this CLI

Run once in any project to drop a managed AGENTS.md block that teaches Claude Code, Cursor, Codex, and Copilot how to invoke the CLI:

botdocs install-instructions

If AGENTS.md already exists with markers from a prior run, the block is refreshed in place. Use --print to dump the snippet to stdout instead of writing.

Library + update notifications

Enable the personalized Library page at https://botdocs.ai/library:

botdocs login --sync-library

After install/sync/uninstall, the CLI uploads a sanitized snapshot (refs + versions only — never file contents) so the web library can show what you have, what your team has, and what's new. Privacy-conscious users can leave the flag off; the CLI no-ops silently and the page shows an onboarding banner with the command.

Set up a shell hook so new terminals show pending update notices:

botdocs install-instructions --shell-hook

Detects your shell (zsh/bash/fish), writes a marker-delimited block to the rc file, and runs botdocs check-updates --quiet on shell open. Silent when there's nothing to report. Remove with --remove-shell-hook when you want it gone.

Or check manually anytime:

botdocs check-updates           # full list of pending updates
botdocs check-updates --quiet   # one-liner only when updates pending

check-updates caches the response for 1 hour so opening many terminals in quick succession doesn't hammer the API.

Multi-ecosystem authoring (BYOK)

Authors write a skill once in their preferred ecosystem (Claude Code, Cursor, etc.) and use their own LLM key to generate the other formats locally. The server never runs inference — your file content stays on your machine.

export BOTDOCS_ANTHROPIC_KEY=sk-ant-...    # or BOTDOCS_OPENAI_KEY=sk-...

botdocs init my-skill --canonical          # scaffolds claude-code source
                                            # + ecosystems list in botdocs.json
# edit claude-code/commands/my-skill.md

botdocs compile my-skill/                  # generates claude/SKILL.md,
                                            # cursor/rules/my-skill.mdc, etc.

botdocs publish my-skill/                  # auto-compiles if stale; --no-compile to skip

To revise a published file later via the LLM:

botdocs edit @you/my-skill --ecosystem cursor
# enter your change in plain English
# review the diff, accept to push as a draft
# visit botdocs.ai/@you/my-skill to publish

compile and edit both prefer BOTDOCS_ANTHROPIC_KEY (Claude Haiku) when set, otherwise fall back to BOTDOCS_OPENAI_KEY (GPT-4o mini). Use --key-env <NAME> to point at a different env var.

Skills + bundles

Skills are bundles of files that ship to specific destinations on disk (Claude skills, Cursor rules, Claude Code commands). A bundle is a curated playlist of skills for an org or team. Two key flows:

Install a team's bundle — files land in the right places automatically:

botdocs install @teamco/eng-skills

Stay current — walks the lockfile, applies clean updates, prompts on conflicts (skip or overwrite with double confirm):

botdocs sync

botdocs list shows what you have installed; botdocs uninstall <ref> removes it.

Authors who want to share their existing collection of skills run botdocs ingest <path> — the CLI walks the directory, detects each skill, and uploads them as drafts in your BotDocs account for review before publishing.

Endorsing

Endorsements are reserved for builders who actually used the spec — the server will reject an endorsement if it can't see a prior clone from the same account. If you hit that error the CLI will point you at:

botdocs clone @user/slug

…build something on top, then come back and run endorse.

Development

pnpm install
pnpm --filter @botdocs/cli build       # tsc -> dist/
pnpm --filter @botdocs/cli test        # vitest
pnpm --filter @botdocs/cli typecheck

Releasing

Versioning and publishing run on changesets:

1. After making changes, run pnpm changeset from the repo root. Pick @botdocs/cli, choose patch/minor/major, write a one-line summary.
2. Commit the generated .changeset/<slug>.md along with your code.
3. When your PR merges to master, a "Version Packages" PR is opened automatically with the bumped version and CHANGELOG entries.
4. Reviewing and merging that PR triggers npm publish from CI.

No manual tagging or version bumps required.

License

MIT © BotDocs contributors