Package Exports

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@botdocs/cli) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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

Command	Purpose
`init [name]`	Scaffold a new BotDoc directory with an `index.md` template.
`validate <source>`	Pre-publish structural check on a directory or file.
`clone <user/slug>`	Download every file in a BotDoc to a local directory.
`search <query>`	Search the public registry.
`publish <source>`	Publish from a file, directory, or zip archive.
`diff <user/slug>`	Preview remote changes before pulling.
`pull <user/slug>`	Update a previously-cloned BotDoc.
`endorse <user/slug>`	Rate a BotDoc after you've built from it (requires a prior clone).
`login`	Authenticate via the GitHub device-code flow.
`whoami`	Show the currently authenticated user.

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

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

Configuration

Variable	Default	Purpose
`BOTDOCS_API_URL`	`https://botdocs.ai`	Override the registry API endpoint (useful for local development).

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

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:

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

No manual tagging or version bumps required.

@botdocs/cli