---
title: ak-docs CLI
description: Complete command reference for indexing, querying, gates, doctor, memory, and MCP.
---

# ak-docs CLI

Command-line interface for **`@agentskit/doc-bridge`**. The package publishes two executables: `ak-docs` is the product CLI and `ak-verify` is the verification-harness wrapper.

## Naming

| What | Name |
|------|------|
| npm package | `@agentskit/doc-bridge` |
| CLI binary | `ak-docs` |
| Verification binary | `ak-verify` |
| Primary config filename | `doc-bridge.config.ts` |
| GitHub repo | `AgentsKit-io/doc-bridge` |

Install the package, run `ak-docs` — not `doc-bridge` on the shell.

The primary filename is shown for readability. Discovery also accepts
`doc-bridge.config.mts`, `.js`, `.mjs`, `.json`, and the `docBridge` field in
`package.json`; see the [configuration contract](./config-v1.md#discovery-order)
for the authoritative order.

## Why a separate binary

| Choice | Rationale |
|--------|-----------|
| **`ak-docs`**, not `agentskit docs` | Dedicated tool; no need for full `@agentskit/cli` |
| **`ak-docs`**, not an OS subcommand | OS CLIs imply sidecar / runs / pipelines |
| **`@agentskit/doc-bridge` package** | Part of AgentsKit npm scope; engine + first consumer alignment |
| **`ak-docs` bin name** | Short, memorable CLI; avoids colliding with package import path |

## Install

```bash
npm install @agentskit/doc-bridge
# or
pnpm add -D @agentskit/doc-bridge
```

```json
{
  "name": "@agentskit/doc-bridge",
  "bin": {
    "ak-docs": "./bin/ak-docs.js",
    "ak-verify": "./bin/ak-verify.js"
  }
}
```

## Commands (v1)

### Layer 0 — no API key

| Command | Description |
|---------|-------------|
| `ak-docs init` | Scaffold `doc-bridge.config.json` + agent INDEX stub |
| `ak-docs init --scaffold-workspaces` | Also create draft `docs/for-agents/packages/*.md` from discovered pnpm workspaces; never overwrites existing docs |
| `ak-docs bootstrap agent-docs` | Create draft `docs/for-agents/human/*.md` from configured human-doc adapters; never overwrites existing docs |
| `ak-docs validate-config` | Zod-validate config file |
| `ak-docs demo [--fixture example\|monorepo] [--text]` | Bundled 60s wow path: handoff, gate red→green, MCP snippet |
| `ak-docs doctor [--text] [--badge] [--write-badge]` | Coverage score, gaps, gates, shields.io badge |
| `ak-docs index` | Build `DocBridgeIndex` + optional `llms.txt` |
| `ak-docs index --watch` | Debounced rebuild on agent/human doc changes |
| `ak-docs query <target> [--agent] [--text]` | Resolve package/area/module/document/intent/change → handoff JSON or text |
| `ak-docs search <term> [--agent] [--explain] [--mode=<mode>] [--context-budget=<tokens>] [--text]` | Ranked search over the retrieval projection; `--explain` names every scoring component and the matched terms, and agent mode bounds the context it returns to a task-specific budget |
| `ak-docs ask <question>` | Human-readable local consult mode: search + best match + next handoff commands; no LLM |
| `ak-docs ask` | Interactive local REPL in a TTY; commands: `search <term>`, `read <id-or-path>`, `open <id-or-path>`, `resolve <id>`, `gate [id]`, `exit` |
| `ak-docs retrieve <query>` | Hybrid local/federated retriever chunks; deterministic local first |
| `ak-docs init --demo` / default | Scaffold demo ownership (`example`) + `AGENTS.md` snippet so `query --agent` works immediately |
| `ak-docs init --no-demo` | Config + empty INDEX only |
| `ak-docs memory ingest` | Normalize local memory files (`.agent-memory/**/*.md`, `.cursor/rules/*.mdc`) into `MemoryCandidate[]` |
| `ak-docs memory classify` | Deterministically route candidates to agent/human/playbook/discard |
| `ak-docs memory promote` | Build draft-only promotion body with safety scan; never auto-merges |
| `ak-docs memory promote --pr --dry-run [--force]` | Write a local draft and print the `git`/`gh` commands; does not execute them |
| `ak-docs memory promote --pr [--force]` | Write the draft, commit/push it, and open a GitHub draft PR via `gh` |
| `ak-docs registry topology` | Print the `doc-curator` topology for AgentsKit/Registry composition |
| `ak-docs suggest [--documentation] --json` | Run the configured Registry agent module or CLI and persist its typed proposal; optionally include the bounded documentation-audit context |
| `ak-docs enrich [--json\|--text]` | Run the enrichment stage: context packs to the configured Registry roles, deterministic validators, the overlay at `.doc-bridge/enrich/overlay.json`. Zero agent calls over an unchanged repository |
| `ak-docs enrich list \| approve <proposalId> --by <name> \| reject <proposalId> --by <name> [--reason <text>]` | Review pending enrichment proposals; a decision is recorded through the ecosystem approval gate under `.doc-bridge/approvals/`, bound to the proposal id and the target content hash |
| `ak-docs check --enrich` | `check` with the `enrich` stage between `reconcile` and `evaluate`; a failed enrichment is reported in `enrichment` and never changes the check result |
| `ak-docs enrich --retrieval-delta [--json\|--text]` | `enrich`, then the golden suite with and without the accepted overlay on the same snapshot. Exits 1 when the overlay lowers hit@3 |
| `ak-docs bench retrieval <suite.json> --overlay [--json\|--text]` | The overlay on disk measured against a suite: both indexes projected from one snapshot, no index on disk required. Exits 1 on a hit@3 regression |
| `ak-docs study expectations <task-suite.json> --expectations <local.json> [--index <index.json>] [--repository <id>]` | Check a study round's mechanical retrieval expectations through the benchmark. Exits 1 when a reference does not resolve or a case misses |
| `ak-docs playbook draft` | Build a draft Playbook feedback payload from local memory candidates |
| `ak-docs playbook pattern [--text]` | Export published Doc Bridge Playbook pattern (OKF markdown / JSON) |
| `ak-docs list <kind> [--text]` | List packages, apps, intents, … |
| `ak-docs gate run [gate-id]` | Run resolved configured documentation gates; an optional id narrows the run to one gate |
| `ak-docs conformance run documentation-standard-v1 [--text\|--json]` | Run the stable ecosystem documentation profile with evidence and remediation |
| `ak-docs audit documentation [--text\|--json]` | Measure documentation quality and compare documentation claims with the observed project graph |
| `ak-docs parity [--claims <file>] [--json\|--text]` | Check the public claim registry against what the repository can prove: stale, missing, contradictory and not-analyzed claims, each with an owner, an exact source and a remediation. Exits 1 on a blocking finding |
| `ak-docs render <llms.txt\|area\|ownership\|change-digest\|overlay-review> [--data <artifact>] [--output <path>] [--print-template] [--json]` | Render the canonical artifacts as Markdown from bundled or project templates (`render.templates`); deterministic, no agent. See [Render v1](./render-v1.md) |
| `ak-docs bench retrieval <suite.json> [--index <file>] [--baseline <file>] [--limit <n>] [--text\|--json]` | Measure retrieval quality against a golden query suite: hit@1, hit@3, mean reciprocal rank, context bytes and approximate tokens. Exits non-zero on a hit@3 regression against the baseline. No model, no network |
| `ak-docs bench retrieval <suite.json> --baseline <file> --update-baseline --by <name> [--reason <text>]` | Record the measured figures as the approved baseline. A normal run never writes one |
| `ak-docs mcp` | Start MCP server (stdio default) |
| `ak-docs mcp install --cursor \| --claude` | Write MCP server config for Cursor or Claude Desktop |

### Layer 1 — optional AgentsKit peers (`intelligence.enabled`)

| Command | Description |
|---------|-------------|
| `ak-docs rag ingest` | Ingest agent corpus into `@agentskit/rag` + file vector store |
| `ak-docs rag search <query>` | Semantic search over ingested vectors |
| `ak-docs chat` | Interactive terminal chat (`@agentskit/ink` + retriever + adapter) |
| `ak-docs ask <question> --chat` | One-shot grounded answer (`handoffFirst` when possible) |

Peers: `@agentskit/rag`, `@agentskit/ink`, `@agentskit/adapters`, `@agentskit/memory`, `react`.

## Global flags

| Flag | Description |
|------|-------------|
| `--config <path>` | Config file (default: auto-discover) |
| `--json` / `--text` | Output format for non-agent commands (default: formatted json); `--agent` emits compact machine-readable JSON, while `--text` remains human-readable |
| `--chat` | Request planned intelligence-backed ask mode; errors clearly until `intelligence.adapter` and RAG/chat support are configured |
| `--help` | Command help |

## Examples

```bash
ak-docs index
ak-docs query ownership auth --agent
ak-docs query ownership auth --text
ak-docs search "sidecar transport" --agent --mode=discovery --context-budget=256
ak-docs list packages --text
ak-docs gate run
ak-docs mcp
```

## MCP server config (Cursor)

```json
{
  "mcpServers": {
    "ak-docs": {
      "command": "ak-docs",
      "args": ["mcp"]
    }
  }
}
```

## Programmatic API

```ts
import { buildIndex, query, defineConfig } from '@agentskit/doc-bridge'

export default defineConfig({ schemaVersion: 1, corpus: { agent: { root: 'docs' } } })
```

CLI is a thin wrapper over the same exports.

`MCP_TOOLS` exports the static tool descriptors used by `tools/list`.

## Private Dogfood Alias

```bash
pnpm docs:internal:query …   # private dogfood wrapper → ak-docs query …
```

`ak-docs` is the primary product CLI. `ak-verify` is the portable verification-harness entry point used to prove repository work against a declared contract.

## See also

- [config-v1.md](./config-v1.md)
- [POSITIONING.md](../POSITIONING.md)