dots mcp, dots repo, and dots graph

The dots mcp, dots repo, and dots graph families, command by command. Every signature, argument, and option below is read from the CLI's own command tree, so this page cannot drift from dots --help. Every other family is listed in CLI Reference.

dots mcp

dots mcp [options] [command]

Launch the Dots stdio MCP server so an external MCP host (Claude Desktop, Claude Code, Cursor) connects to your vault — point your host's MCP config at { "command": "dots", "args": ["mcp"] }. Serves the complete built-in tool catalog, including vault and code-graph reads; row, edge, bulk, saved-view, and dashboard writes; Superpower tools; and the batch meta-tool — all scope-filtered to the connecting credential. A long-running, blocking command: it reads JSON-RPC on stdin until EOF and writes the protocol on stdout. Resolves the API base URL, credential, and active company from the usual precedence.

Options:

• --read-only — Advertise only read-classed tools. Every write-classed built-in or plugin tool — including irreversible purge_row, bulk row and edge writes, and saved-view and dashboard mutations — is not registered; the batch meta-tool refuses write members. Use when connecting an untrusted or read-only host.
• --defer-tools — Defer the tool catalog: advertise the core tools plus discover_tools at connect and hold the rest back until an agent activates them by family. Set it only on a host that refreshes its tool list when the server signals a change (Claude Code does) — MCP exposes no capability the server can read that from, so this is an explicit opt-in and the default injects the complete granted catalog. Deferral narrows what is LISTED, never what is granted: every tool the credential can satisfy stays reachable through discover_tools.
• --plugin <dir> — Load defineMcpTool entry points from a plugin directory and register them as runtime MCP tools (repeatable).

dots mcp tools

dots mcp tools [options]

List the built-in MCP tool catalog dots mcp serves, without starting a server. One record per tool: its family, whether it is injected up front (core) or held back until discover_tools activates its family (deferred), and the permission atom a connecting credential must hold for the tool to be advertised at all (ungated when the tool gates on none). Use it to answer what an MCP host will see before connecting one, and to check whether a capability is missing or merely deferred. Add --describe for each tool's agent-facing description.

Options:

• --limit <n> — Maximum records to return.
• --offset <n> — Records to skip before returning the page.
• --count — Print the number of records this list returns instead of the records themselves.
• --family <id> — List only the tools in this family — the same family ids discover_tools takes (repeatable; an unknown id is a usage error naming the live ones).
• --describe — Include each tool's agent-facing description, the text an MCP host shows the model. Off by default: the catalog is a few hundred tools and the descriptions are paragraphs.

dots repo

dots repo [options] [command]

Ingest a local repository checkout into the code knowledge graph.

dots repo ingest

dots repo ingest [options] <path>

Ingest a local repo checkout into the code knowledge graph — extracts files, symbols, and structural edges (contains/defines/imports/calls/inherits). Against the local daemon it runs in the background and returns immediately; against a cloud/hosted API it parses the checkout locally, uploads the resolved graph as ordered size-capped compressed parts, and enqueues a durable, checkpointed apply job that it polls to completion, printing the part count and written counts. The apply also ledgers the Git Commits rows for the commits the shipment carried metadata for; anything past that bound is filled by dots git ingest-commits. A re-ingest with no changes is a no-op.

Arguments:

• <path> — Path to the local repository checkout to ingest (resolved to an absolute path).

Options:

• --embed-symbols — Embed this repo's code symbols (per-repo opt-in). Symbols are not embedded by default; this makes them semantically searchable without enabling embeddings for every repo's symbols. Requires an embedding provider on the target runtime; provider absence is reported explicitly.
• --enrich — Infer cross-context edges between this repo's code and your docs/plans via a metered server-side LLM job (per-repo opt-in) — the org/enterprise path, and the one that bills API tokens. In a coding agent, prefer the /repo-graph skill's enrich pass instead: it judges the same candidate shortlist in-session until dry and narrates Code Areas besides, at no marginal token cost on the subscription already running the session. On the hosted path this flag runs as a durable follow-on job enqueued after the graph applies (not polled here). Bounded + cost-capped; requires an LLM provider. Combinable with --embed-symbols.
• --no-wait — Return after the hosted apply job is durably queued instead of polling it at all. The printed job id can be inspected later; the job runs on regardless.
• --wait-terminal — Keep waiting after the graph is published, until the hosted apply job reaches a terminal status. By default the wait ends the moment the apply publishes — the graph is readable then, and what follows is the job's own bookkeeping (commit ledger, candidate GC, follow-on enqueues). Use this when you need the terminal record itself: the server's full timing breakdown, the follow-on degradations, and a final completed/failed verdict.
• --wait-timeout <seconds> — Stop waiting on the hosted apply job after this many seconds and hand it off with its job id. The job is not cancelled — it runs on durably, and the command still exits 0. Without this the wait runs to publication (or, with --wait-terminal, to a terminal status). DOTS_REPO_APPLY_WAIT_MS sets the same ceiling in whole milliseconds for a caller that spawns this CLI under its own wall budget.
• --telemetry — Report the full measurement surface beside the outcome: the server's per-phase apply timings, the client's own legs (classification, extraction, compression, upload, enqueue, poll) with the admission split, the shipment's part count and compressed size, and the whole structural-integrity census. Off by default — a routine ingest reports what it shipped and what the apply wrote, not how long each of its stages took.

dots repo code-area-signature

dots repo code-area-signature [options] <area> <digest>

Stamp the rule-derived membership signature for one Code Area. This internal operation is reserved for the post-push membership reconciler.

Arguments:

• <area> — Code Area human id (AREA-N).
• <digest> — Lowercase 64-hex membership digest.

dots repo shadow-rebuild

dots repo shadow-rebuild [options] <path>

Rebuild a local repository checkout's code knowledge graph from scratch without deleting anything — retires the sync-checkpoint manifest so the next ingest re-derives the whole graph, while every Repo File, Code Symbol, and Git Repository row keeps its id and every edge survives. Scoped to the repo derived from the checkout and to the active company (--company); the repo source_key is derived locally. With no flags it prints the non-mutating rebuild census. --stage records a validated candidate and prints its generation id and publisher token; --publish lands that candidate.

Arguments:

• <path> — Path to the local repository checkout whose code graph to rebuild (resolved to an absolute path; the repo source_key is derived from it).

Options:

• --stage — Stage and validate a rebuild candidate. Nothing reader-visible moves; the printed generation id and publisher token are what --publish needs.
• --publish <generationId> — Publish the staged candidate with this generation id. Requires --publisher-token from the same staging run.
• --publisher-token <token> — The publisher token the staging run minted. A superseded token is refused, so a stale claimant cannot land a rebuild.

dots repo verb-candidates

dots repo verb-candidates [options] <path>

Reconcile deterministic local code↔code candidate revisions into a durable campaign, then serve its next unresolved page.

Arguments:

• <path> — Path to the local repository checkout to analyze.

Options:

• --verb <verb> — Semantic verb: delegates_to | orchestrates | guards | alternative_to | configures | serializes_for | caches_for | error_path_of.
• --contract-name <name> — Judging contract name recorded with the durable campaign.
• --contract-version <version> — Positive integer judging contract version.
• --scope <prefix> — Optional repository-relative source prefix.
• --cursor <token> — Campaign cursor from a persisted judgment receipt.
• --limit <n> — Candidate revisions per page (default 100, maximum 100).

dots repo verb-judgments

dots repo verb-judgments [options] <path>

Persist a complete served page of campaign dispositions and return the campaign cursor that is now safe to checkpoint.

Arguments:

• <path> — Path to the local repository checkout the campaign describes.

Options:

• --verb <verb> — Semantic verb: delegates_to | orchestrates | guards | alternative_to | configures | serializes_for | caches_for | error_path_of.
• --contract-name <name> — Judging contract name recorded with the durable campaign.
• --contract-version <version> — Positive integer judging contract version.
• --from-file <path> — JSON file containing the served candidates and their dispositions.
• --scope <prefix> — Optional repository-relative source prefix.

dots repo verb-campaign-import

dots repo verb-campaign-import [options] <path>

Recover a durable verb campaign from a canonical bundle or a directory of JSON artifacts recognized by shape.

Arguments:

• <path> — Path to the local repository checkout used to verify current graph identities.

Options:

• --verb <verb> — Semantic verb: delegates_to | orchestrates | guards | alternative_to | configures | serializes_for | caches_for | error_path_of.
• --contract-name <name> — Judging contract name recorded with the durable campaign.
• --contract-version <version> — Positive integer judging contract version.
• --from-file <bundle> — Canonical recovery bundle JSON.
• --from-directory <artifact-root> — Artifact directory recursively inspected by JSON shape, independent of filenames.
• --receipt-file <path> — Required path for the exact import or dry-run accounting receipt.
• --bundle-out <path> — Optional path for the canonical immutable recovery bundle.
• --scope <prefix> — Optional repository-relative source prefix.
• --dry-run — Validate and account without any network mutation.

dots repo verb-campaign-export

dots repo verb-campaign-export [options] <path>

Export a durable verb campaign ledger to an immutable JSON bundle.

Arguments:

• <path> — Path to the local repository checkout the campaign describes.

Options:

• --campaign-id <uuid> — Durable campaign UUID.
• --out <path> — Destination path for the exported campaign ledger.

dots repo candidates

dots repo candidates [options] <path>

List the code↔doc pairs an enrichment pass would judge, for one local repository checkout — each pair's code endpoint, doc endpoint, embedding similarity, pagerank tier, and whether an accepted-verb edge already joins them. Read-only: it judges nothing and writes no edge. Scoped to the repo derived from the checkout and to the active company (--company); the repo source_key is derived locally. Page through with --cursor until nextCursor is null, feeding each page's judged pairKeys back through --exclude-file so the next page refills rather than shrinks.

Arguments:

• <path> — Path to the local repository checkout whose enrichment candidates to list (resolved to an absolute path; the repo source_key is derived from it).

Options:

• --exclude-file <path> — Path to a file of pair keys to leave out of this page — one pairKey per line; blank lines and lines starting with # are ignored. Exclusion is applied before the page cap, so an until-dry sweep that writes each judged page's pairKeys here keeps getting full pages.
• --cursor <cursor> — Resume the scan after a previous page — the opaque nextCursor that page printed. Omit it for the first page.
• --limit <count> — Candidates per page. A page never splits one doc anchor's shortlist, so the server permits that one indivisible group to exceed a lower limit; only a null nextCursor means the scan found nothing further.

dots repo guided-ingest

dots repo guided-ingest [options] <path>

The consent-gated onboarding wrapper over repo ingest (the Setup Assistant's one guided repo ingest). Surfaces the resolved checkout path, refuses to ingest without --consent (bound to that path), then runs the ingest while streaming structured progress events (resolved -> ingest-start -> rows -> edges -> finalize -> done; the default-branch alignment guard's refusal surfaces as a terminal refused event) to stderr; the summary lands on stdout. Additional repos beyond the guided one use plain dots repo ingest.

Arguments:

• <path> — Path to the local repository checkout to guide-ingest (resolved to an absolute path).

Options:

• --consent — The explicit consent signal — confirm ingesting the resolved checkout path. Without it the wrapper performs no ingest and exits with a consent-required message.
• --embed-symbols — Embed this repo's code symbols (per-repo opt-in). Symbols are not embedded by default; this makes them semantically searchable without enabling embeddings for every repo's symbols. Requires an embedding provider on the target runtime; provider absence is reported explicitly.
• --enrich — Infer cross-context edges between this repo's code and your docs/plans via a metered server-side LLM job (per-repo opt-in) — the org/enterprise path, and the one that bills API tokens. In a coding agent, prefer the /repo-graph skill's enrich pass instead: it judges the same candidate shortlist in-session until dry and narrates Code Areas besides, at no marginal token cost on the subscription already running the session. On the hosted path this flag runs as a durable follow-on job enqueued after the graph applies (not polled here). Bounded + cost-capped; requires an LLM provider. Combinable with --embed-symbols.

dots graph

dots graph [options] [command]

Query the code knowledge graph — the callers, callees, blast radius, call path, commit-range diff, provenance, and neighborhood of a code symbol, plus the ingest state of the repositories it was built from (the read verbs behind the ingested repo graph).

dots graph neighborhoods

dots graph neighborhoods [options]

Resolve and hydrate up to 500 code-symbol neighborhoods in one request; bad or ambiguous refs are reported per item.

Options:

• --from-file <path> — JSON file containing a symbol-ref array, or { symbols: [...] }.

dots graph callers

dots graph callers [options] <symbol>

List the code symbols that call the given symbol (the reverse call edges), scoped to the active company's ingested repo graph. Returns the queried symbol plus each caller node with its edge confidence.

Arguments:

• <symbol> — The code symbol to find callers of — its human_id or external_id (e.g. a function or method reference).

Options:

• --limit <n> — Cap the number of caller nodes returned (positive integer, maximum 500; larger values are rejected).

dots graph callees

dots graph callees [options] <symbol>

List the code symbols the given symbol calls (the forward call edges), scoped to the active company's ingested repo graph. Returns the queried symbol plus each callee node with its edge confidence.

Arguments:

• <symbol> — The code symbol to find callees of — its human_id or external_id (e.g. a function or method reference).

Options:

• --limit <n> — Cap the number of callee nodes returned (positive integer, maximum 500; larger values are rejected).

dots graph impact

dots graph impact [options] <symbol>

Compute the transitive blast radius of the given symbol — every incoming dependent reachable through calls or inherits edges within the hop bound — scoped to the active company's ingested repo graph. Each impacted node carries its hop distance and edge confidence. truncated:true is terminal for that response: increasing hops cannot recover dependents omitted by a saturated same-hop read or the node cap, and no cursor is available.

Arguments:

• <symbol> — The code symbol to compute the blast radius of — its human_id or external_id.

Options:

• --hops <n> — How many incoming dependency hops to traverse (positive integer, server default 2, maximum 5; larger values are rejected).

dots graph trace

dots graph trace [options] <from> <to>

Trace the shortest call path between two code symbols, scoped to the active company's ingested repo graph. Returns the ordered path steps, or an empty path when no route connects them. An empty path with truncated: true means the walk exhausted its node budget and the answer is undecided, not that no path exists — retry with a larger --limit.

Arguments:

• <from> — The starting code symbol — its human_id or external_id.
• <to> — The destination code symbol — its human_id or external_id.

Options:

• --hops <n> — How many hops the path may span (positive integer, maximum 12; larger values are rejected). Defaults to the company's traversal hop limit, 6.
• --limit <n> — Node budget — how many graph nodes the walk may visit before giving up (positive integer, server default 2500, maximum 10000; larger values are rejected).

dots graph diff

dots graph diff [options] <base> <head>

List the code symbols a base..head commit range changed, plus what depends on them, scoped to the active company's ingested repo graph. The range is base-exclusive and head-inclusive. Attribution is FILE-grained — commit rows carry no hunks, so every symbol defined in a changed file is reported as changed; the response's precision field states what that costs and attribution names how each symbol was reached. Retired (tombstoned) symbols come back separately, attributed by timestamp only. graphSkew is non-null when the graph was built at a different commit than head. Needs ingested commit rows (dots git ingest-commits <path>); with none it refuses with a typed error naming that remedy rather than returning an empty range. A range wider than the server's commit-walk cap is likewise refused with a typed error naming the cap. truncated:true is terminal for that response: increasing hops cannot recover dependents omitted by a saturated same-hop read or the node cap, and no cursor is available.

Arguments:

• <base> — The base commit the range starts after (exclusive) — a full 40-char SHA or a hex abbreviation of at least 4 characters, resolved against the ingested Git Commits rows.
• <head> — The head commit the range ends at (inclusive) — a full 40-char SHA or a hex abbreviation of at least 4 characters, resolved against the ingested Git Commits rows.

Options:

• --repo <slug> — Narrow SHA resolution to one repository — the Git Commits repository value (an owner/repo slug or a checkout basename), not a repo: external id. Needed when an abbreviation matches commits in more than one repository.
• --hops <n> — How many dependent hops to walk out from the changed symbols (positive integer, server default 2, maximum 5; larger values are rejected).

dots graph why

dots graph why [options] <symbol>

Explain why a code symbol exists, scoped to the active company's ingested repo graph — its defining file, the commits and conversations that produced it, and the plans, rows, and findings that reference it, one hop per provenance edge with both endpoints named by human id. Every response carries a narrative; a symbol that resolves but reaches nothing is a SUCCESS carrying a typed noProvenance reason and its remedy, never an empty answer. truncated: true means a cap stopped a fan-out and the hops are a prefix; unresolvedEndpoints counts incident edges whose far endpoint names no surviving row.

Arguments:

• <symbol> — The code symbol to explain — its human_id, its canonical external_id, or a friendly <path>#<name> reference.

Options:

• --limit <n> — Cap how many producing commits the walk carries forward, newest first (positive integer, server default 5, maximum 50; larger values are rejected).

dots graph context

dots graph context [options] <symbol>

Return the immediate graph neighborhood of the given symbol — its directly connected nodes across every edge kind — scoped to the active company's ingested repo graph. One page at a time: a truncated: true response carries a nextCursor to replay with --cursor.

Arguments:

• <symbol> — The code symbol to describe the neighborhood of — its human_id or external_id.

Options:

• --limit <n> — Cap the number of neighbors returned in one page (positive integer, maximum 500; larger values are rejected).
• --cursor <cursor> — Resume after a previous page — pass the nextCursor that page returned. An unreadable cursor restarts from the first page.

dots graph detect-changes

dots graph detect-changes [options]

Report what the active company's code graph was built from: every ingested repository with its root path, remote URL, default branch, last-ingested commit SHA, and last update. Compare lastIngestSha against your checkout's HEAD to tell whether the graph is behind it. Takes no arguments; a company that has ingested nothing returns an empty list. Read-only — to refresh the graph, run dots repo ingest <path>.

dots graph row-neighborhood

dots graph row-neighborhood [options] <dotabase>

Read row-graph edges incident to one or more row UUIDs plus their cross-Dotabase neighbors. This is distinct from code-symbol graph neighborhoods.

Arguments:

• <dotabase> — Dotabase id, slug, or canonical human-id that scopes the seed rows.

Options:

• --row-id <uuid> — Seed row UUID; repeat for up to 500 rows.
• --limit <n> — Maximum records to return.
• --offset <n> — Records to skip before returning the page.
• --count — Print the number of records this list returns instead of the records themselves.

dots graph stats

dots graph stats [options]

Read company-wide row-graph node count, edge count, and density.

dots graph universe

dots graph universe [options]

Read the cross-Dotabase row graph around hubs, recent rows, or one entity reference.

Options:

• --seed <ref> — Seed token: hubs, recent, a row human-id, or a row UUID.
• --hops <n> — Positive traversal hop count (server-clamped).
• --kind <kind> — Entity kind to keep; repeat to send a token set.
• --diiice <type> — DIIICE type to keep; repeat to send a token set.
• --edge-category <category> — Edge category to keep; repeat to send a token set.
• --lens <lens> — Analytic lens: hubs | bridges | islands | clusters.
• --limit <n> — Maximum records to return.
• --offset <n> — Records to skip before returning the page.
• --count — Print the number of records this list returns instead of the records themselves.

dots graph dotabase

dots graph dotabase [options] <dotabase>

Read the complete row graph for one Dotabase, projected with pagination or count flags.

Arguments:

• <dotabase> — Dotabase id, slug, or canonical human-id.

Options:

• --limit <n> — Maximum records to return.
• --offset <n> — Records to skip before returning the page.
• --count — Print the number of records this list returns instead of the records themselves.

dots graph clusters

dots graph clusters [options] <dotabase>

Read one Dotabase's cluster rollup and inter-cluster flows.

Arguments:

• <dotabase> — Dotabase id, slug, or canonical human-id.

Options:

• --key <key> — Cluster axis: a built-in key or property:<slug>.
• --limit <n> — Maximum records to return.
• --offset <n> — Records to skip before returning the page.
• --count — Print the number of records this list returns instead of the records themselves.

dots graph cluster-members

dots graph cluster-members [options] <dotabase>

Read one Dotabase cluster's member nodes and internal edges.

Arguments:

• <dotabase> — Dotabase id, slug, or canonical human-id.

Options:

• --key <key> — Cluster axis: a built-in key or property:<slug>.
• --value <value> — Cluster value returned by graph clusters; use other for the remainder.
• --limit <n> — Maximum records to return.
• --offset <n> — Records to skip before returning the page.
• --count — Print the number of records this list returns instead of the records themselves.

dots graph cluster-keys

dots graph cluster-keys [options] <dotabase>

List the cluster axes a Dotabase can serve and their coverage.

Arguments:

• <dotabase> — Dotabase id, slug, or canonical human-id.

Options:

• --limit <n> — Maximum records to return.
• --offset <n> — Records to skip before returning the page.
• --count — Print the number of records this list returns instead of the records themselves.

dots graph region

dots graph region [options]

Read the highest-degree row nodes and active edges inside a 2D viewport.

Options:

• --min-x <n> — Viewport minimum X coordinate.
• --min-y <n> — Viewport minimum Y coordinate.
• --max-x <n> — Viewport maximum X coordinate.
• --max-y <n> — Viewport maximum Y coordinate.
• --zoom <n> — Optional finite zoom hint.
• --dotabase <ref> — Optionally scope the viewport to one Dotabase id, slug, or canonical human-id.
• --limit <n> — Maximum records to return.
• --offset <n> — Records to skip before returning the page.
• --count — Print the number of records this list returns instead of the records themselves.

generator: apps/docs/pipeline/generate-reference.ts — regenerate with pnpm --filter @dots/docs docs:generate:reference; a hand edit to this page fails the docs drift gate.