doco-agent-cli

The Doco CLI and MCP server — one command to connect your AI agent to your knowledge base.

Doco is the document space where humans and AI agents write together: block-level stable addressing, optimistic concurrency, and a 29-tool MCP server. See doco.page for the product and the API reference for the OpenAPI 3.1 spec.

Quick start

# 1. Log in (browser device authorization, same mental model as the GitHub CLI)
npx -y --package doco-agent-cli doco login

# 2. Use it
npx -y --package doco-agent-cli doco whoami
npx -y --package doco-agent-cli doco docs ls
npx -y --package doco-agent-cli doco docs cat <docId> -f md
npx -y --package doco-agent-cli doco edit <docId>   # pulls Markdown into $EDITOR; saving writes back

Connect your agent (MCP)

claude mcp add doco -- npx -y --package doco-agent-cli doco mcp

Cursor: paste into MCP settings

{ "doco": { "command": "npx", "args": ["-y", "--package", "doco-agent-cli", "doco", "mcp"] } }

Codex / Gemini CLI / VS Code Copilot: same package and arguments in their MCP configuration.

MCP toolset (29 tools, deliberately restrained): doco_whoami / doco_list_knowledge_bases / doco_get_tree / doco_list_documents / doco_search / doco_search_v2 / doco_get_document / doco_outline / doco_read / doco_get_blocks / doco_patch_block / doco_insert_blocks / doco_delete_block / doco_batch_edit / doco_create_document / doco_upload_attachment / doco_changes / doco_traverse / doco_create_relation / doco_summary / doco_save_summary / doco_rebuild_summary / doco_update_document / doco_concepts / doco_edit_concepts / doco_refresh_concept_candidates / doco_translations / doco_translation_units / doco_review_translation_unit. Concepts and translations are grouped by action instead of exploding into per-CRUD tools. Enumerable, subscribable resources are also exposed: doco://kb/<id>, doco://doc/<id>.md, doco://doc/<id>/outline.json.

For headless MCP use, environment variables replace doco login: DOCO_TOKEN, DOCO_BASE_URL.

Commands

doco login [--base-url <url>] [--token <token>] [--scope read_write|read_only] [--no-browser]
doco logout
doco whoami
doco docs ls [--kb <id>] [--folder <id>] [--q <query>] [--locale <BCP47>] [--include-variants] [--limit <n>]
doco docs languages <docId>
doco docs cat <docId> [-f md|json|html] [--locale <BCP47>]
doco docs new --title <title> (--kb <id>|--folder <id>) [--body -]   # --body - reads Markdown from stdin
doco blocks ls <docId> [--recursive]
doco blocks patch <docId> <blockId> --node @node.json [--attrs '<json>'] [--content '<json>']
doco blocks insert <docId> --nodes @nodes.json [--after <blockId>|--before <blockId>|--parent <blockId>|--start|--end]
doco blocks delete <docId> <blockId>
doco changes <docId> [--after <cursor>] [--locale <BCP47>] [--limit <n>]
doco read <docId> [--view markdown|tiptap-json|plain-text|outline] [--locale <BCP47>] [--around <blockId>] [--max-tokens <n>] [--cursor <cursor>]
doco search --q <query> [--mode topk|exhaustive] [--locale <BCP47|all>] [--kb <id>] [--limit <n>] [--cursor <cursor>]
doco links ls <docId> [--direction outgoing|incoming|both] [--predicate <type>]
doco links add <docId> <sourceBlockId> --target <doco://doc/...> [--predicate <type>] [--anchor <text>]
doco links delete <relationId>
doco summary get <id> [--scope document|folder|knowledge-base] [--block <blockId>] [--q <question>]
doco summary set <id> --text <summary> [--scope document|folder|knowledge-base] [--block <blockId>] [--pinned]
doco summary rebuild <id> [--scope document|folder|knowledge-base] [--block <blockId>] [--generator deterministic|model]
doco summary job <jobId>
doco concepts ls [--kb <id>] [--q <query>] [--status <status>] [--limit <n>] [--cursor <cursor>]
doco concepts get <conceptId>
doco concepts create --kb <id> --name <name> [--description <text>] [--aliases <json|@file>]
doco concepts update <conceptId> [--name <name>] [--description <text>] [--aliases <json|@file>]
doco concepts sources <conceptId> --sources <json|@file>
doco concepts relate <conceptId> --relations <json|@file>
doco concepts merge <sourceConceptId> <targetConceptId>
doco concepts traverse <conceptId> [--direction outgoing|incoming|both] [--predicate <type>]
doco concepts candidates [--kb <id>] [--status pending|accepted|rejected] [--min-confidence <0..1>]
doco concepts extract --target <documentId>
doco concepts accept <candidateId> [--concept <conceptId>] [--name <name>]
doco concepts reject <candidateId> [--reason <reason>]
doco edit <docId> [--block <blockId>]
doco mcp
doco skill [install] [--target codex|claude]   # prints / installs the full Doco agent skill

markdown and tiptap-json views read the whole document unless --around, --max-tokens, or --cursor is given. Pass --max-tokens explicitly to bound context; truncation is reported on stderr together with a next_cursor.

Global --json prints machine-parseable JSON; human-readable output is the default.

Concurrency safety (optimistic concurrency, internalized)

Every write command runs the golden loop automatically:

1. Read the current version (ETag).
2. Send the write with If-Match.
3. On 409 Conflict → re-read the latest version → retry the same change (up to 3 rounds).

Concept updates, source/relation edits, merges, and candidate reviews also read the ETag and send If-Match automatically; concept creation, candidate extraction, and the edits above all generate an Idempotency-Key. Complex aliases / sources / relations arrays accept inline JSON or @data.json file input.

On conflict, doco edit reopens your editor with the latest content while your previous draft is saved as document.conflict-N.md for merging — blind overwrites never happen.

Configuration

Defaults to https://api.doco.page/api/v1; override with --base-url / DOCO_BASE_URL for local development or self-hosted instances. Config lives in ~/.config/doco/config.json (mode 0600):

{ "base_url": "https://api.doco.page/api/v1", "token": "doco_tok_…" }

Environment variables take precedence over the config file: DOCO_BASE_URL, DOCO_TOKEN, DOCO_CONFIG_DIR.

Agent skill

doco skill install --target codex    # installs to ~/.codex/skills/doco/
doco skill install --target claude   # installs to ~/.claude/skills/doco/

The package ships the operating protocol, UI metadata, an acceptance matrix, and isolation verification scripts. The agent works as discover → evidence → act → review → report, running the ETag/If-Match golden loop on every write.

Rate limits

120 requests/min per token, 30 writes/min, 10 writes/min per document; on 429, respect Retry-After.