Docs / CLI

The CLI — bcontext, alias bx

The token-cheap agent surface. An MCP server injects its tool schema into model context on every turn; a shell command costs ~0 standing tokens. When your agent has a shell (Claude Code, Cursor, CI), prefer the CLI — keep MCP for hosted, shell-less clients.

Install & authenticate

npm

# one-off (no install)
npx @bcontext/cli whoami

# or install globally
npm i -g @bcontext/cli
bcontext login --token bctx_live_…       # stores ~/.config/bcontext/config.json (0600)
bcontext use my-workspace

environment

# CI / agent sandboxes: configure via env instead of login
export BCONTEXT_TOKEN="bctx_live_…"
export BCONTEXT_URL="https://bcontext.es"    # or your self-hosted origin
export BCONTEXT_WORKSPACE="my-workspace"

Precedence: flags > env > config file. Tokens are workspace-scoped PATs — same auth, scopes, rate limits and audit trail as MCP and REST.

Read commands

bx ask is the first call: a synthesized answer where every claim carries an inline [N] citation, with the numbered sources (as /n/<id>#<block> refs) printed to stderr so the answer pipes cleanly.

read

bx ask "what blocks the release and why?"   # cited answer; Sources on stderr
bx search "auth migration" --kind decision,adr
bx get <node-id>                             # node + links + dependencies + attachments
bx tree
bx unblocked --kind task                     # ready work (no undone blockers)
bx changes --since 2026-07-06T10:00:00Z      # incremental re-sync

Write commands

write

bx create --kind decision --title "Postgres over ClickHouse"   # H2 skeleton pre-filled
echo "## Notes" | bx create --kind doc --title "Notes" --md -
bx update <id> --status done --if-updated-at <updated_at>       # 409 on conflict
bx toggle <node-id> 2 --block action-items                      # atomic checkbox flip
bx link <task-id> <blocker-id> --relation blocked_by
bx attach <node-id> screenshot.png

Creating a decision, adr, meeting or bug without a body pre-fills its standard H2 skeleton; tasks and bugs default to todo so status sweeps can see them.

Optimistic concurrency

Workspaces are multi-writer — humans and agents edit concurrently. Read the node, hold its updated_at, and pass it back with --if-updated-at. If another session wrote in between, you get a 409 with the recovery recipe instead of silently overwriting their work:

conflict

$ bx update 8af7… --md - --if-updated-at 2026-07-06T10:00:00Z
{ "error": true, "message": "409 conflict: node 8af7… was modified by another
  session (updated_at is now 2026-07-06T10:04:11Z, you expected …).
  Re-fetch with get_node, reapply your change on top, and retry." }

Escape hatch

Every MCP tool — present or future — is reachable without a dedicated subcommand:

bx mcp

bx mcp tools/list                                # discover the full catalog
bx mcp list_changes '{"node_id":"<id>"}'         # any MCP tool, no subcommand needed