CLI Reference

The dots CLI's workspace families are a one-to-one front-end onto the platform's routes — the same data, RBAC, Chat, and platform surface the web app and connected agents use. Its machine-local families operate outside that API. The CLI registers 63 command families and 543 commands in all; run dots <family> --help for any family's subcommands.

Every workspace read prints the row envelope described in Row Envelope Format, and every API-backed command maps to a route in the REST API Overview.

Global Options

Every command accepts the root flags:

• -V, --version — Print the CLI build, engine version, and bundled schema head.
• --api-url <url> — API base URL (overrides the stored + env value).
• --company <slug> — Active company slug — run the operation in this company among your memberships (sends x-dots-company). Also set via DOTS_COMPANY.
• --format <format> — Output format: md | json | yaml | table | csv | plain. Default md (YAML front matter + Markdown body); json/yaml are full-fidelity.
• --body-format <format> — How a row body renders: markdown (default) serializes the stored body to Markdown; raw emits the stored string verbatim. Inert for --format md.
• --fields <list> — Comma-separated allowlist of fields to project onto each record.
• --depth <n> — Relationship expansion for row output — one hop only: 0 (none, default) or 1. Traverse further with dots edges list.
• --token-budget <n> — Advisory output cap (estimated tokens); truncates at a record boundary.
• --level <level> — Disclosure level for md output: scan (identity), summary (identity + bounded fields), or full (widest Markdown record). rows list/search, universal search, edges list, and memory/tasks/projects/conversations/superpowers/dotabases list default to summary; every other read defaults to full. --fields disables tiering; pass --level full to restore the widest Markdown record.
• --manual — Expand the default md DBOM trailer to the full Dotabase Operating Manual (purpose, judgment, schema digest).
• --no-agent-mode — Opt out of the agent marker (suppress the DBOM side-channel). Also opted out via DOTS_AGENT=0 or DOTS_AGENT=false.
• --agent-mode — Send the agent marker so responses carry the Dotabase Operating Manual (DBOM) side-channel. Sent by default; this flag is the explicit-on form.
• --verbose — Emit diagnostics (codes, status, stack) to stderr.
• --quiet — Suppress notices; print only data and bare error messages.

Reading Collections

A survey read — a list or a search over a knowledge-bearing family — answers at summary: identity plus the bounded fields, which are the DIIICE classification, the edge count, and every property whose value space is closed, such as a select or a date. A narrowed read prints a footer naming the tier it used; at full the render is byte-identical to the pre-ladder output.

--level scan narrows a survey read to the identity fields for that record family. Row reads keep the human id, title, and icon. dotabases list keeps the Dotabase name, slug, human id, and icon. edges list keeps the edge type, direction, target human id, and target title. --level full restores the widest record, and a row's body renders at full alone; --fields bypasses the ladder for an exact allowlist. A read that names one record answers at full already, so the pattern is scan-then-select: survey the collection cheaply, then pull the one record you chose in full.

Row selection and disclosure are separate axes: filters such as --status, --tag, and --title-contains on a row list choose which rows come back, and --level chooses how much of each. A row query returns at most 500 rows in one page, so read a larger collection a page at a time — raise --limit to that cap and step through the rest with --offset.

Command Families

• dots access (30 subcommands) — Manage identity + authorization: principals, roles, grants, agents, credentials, approvals, invites, and the audit ledger.
• dots account (2 subcommands) — Your own human account — the identity behind this credential.
• dots agent (3 subcommands) — Agent task operations: claim, log progress, and complete tasks.
• dots auth (3 subcommands) — Authenticate the CLI against an API and inspect the current actor.
• dots automations (11 subcommands) — List, create, edit, run, and manage scheduled automations.
• dots batch (no subcommands) — Dispatch up to 50 dots verbs in ONE invocation. The operation list is a JSON array of { command, args } records — command is the path you would type after dots ("rows list"), args its positionals and flags as separate strings — read from --from-file or, with no flag, from stdin. Reads run with at most four in flight and a 30-second timeout per read; writes run in the order given, and a failed write halts later writes. Results remain aligned to the input order. The endpoint, credential, active company, and global flags resolve once for the whole batch. Each member still enforces its own gates.
• dots chat (9 subcommands) — Start a chat conversation and optionally send the first message.
• dots coding-agents (9 subcommands) — Sync this machine's local coding-agent conversations (Claude Code, Codex, Cursor) into your Dotabases.
• dots comments (5 subcommands) — Comment on rows and moderate published-page comments: write a comment as the authenticated principal, report one, read the moderation list, hide a comment, and review the reported-comment queue.
• dots companion (9 subcommands) — Run the Dots companion: a supervised local process that watches your bound folders and tails your consented coding-agent conversations, pushing both to your deployed API. See Run the Companion.
• dots connections (7 subcommands) — Manage importer connections (authorized external-account references).
• dots conversations (10 subcommands) — List, read, create, and drive chat conversations.
• dots dbom (3 subcommands) — Inspect and edit a Dotabase's Operating Manual (DBOM) — its purpose, judgment, and schema digest.
• dots dotabases (32 subcommands) — List, create, update, describe, delete, and seed Dotabases.
• dots edges (10 subcommands) — Create, read, count, and delete knowledge-graph edges between rows, within a Dotabase or spanning two.
• dots events (1 subcommand) — Live server-sent event streams.
• dots executor (2 subcommands) — Executor: run this machine as an executor — exchange a one-time registration token for its device-scoped credential, then lease and execute the chat turns parked for it. Every leg is outbound; nothing here listens on a port.
• dots files (4 subcommands) — Upload media files to a Dotabase file property or a page/row body, list stored objects, re-sign their URLs, and discard uncommitted uploads.
• dots git (4 subcommands) — Ingest git history — local commits (no credential) and PAT-fetched GitHub pull requests.
• dots graph (17 subcommands) — 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 home (5 subcommands) — Read the Home cockpit — the company's knowledge rollup, its weekly growth series, the unified activity feed, the actionable queue counts, and the continuity strip. The orientation reads: what this workspace holds, what changed, and what is waiting on you.
• dots human-md (3 subcommands) — Export / import HUMAN.md documents as .md files.
• dots init (no subcommands) — Provision a fresh database into a bootable Dots instance (one-shot, idempotent): migrate the schema and provision storage, then either mint the supplied owner + workspace or leave first-signup provisioning to the browser under DOTS_FIRST_SIGNUP_OWNER=1. Drives the buyer's own database from the environment, not the API.
• dots jobs (6 subcommands) — Run and inspect background jobs. Requires jobs.manage (Owner and Admin baselines).
• dots local (13 subcommands) — Manage the local Dots daemon (start, stop, restart, status, logs, reset, doctor, license, backup, restore, export-support-bundle).
• dots machines (4 subcommands) — Machines: the registry of machines chat turns can execute on, their reported presence and provider availability, and the one-time token a headless box registers with.
• dots marketplace (24 subcommands) — Browse, install, and publish marketplace listings, and manage the marketplace session.
• dots mcp (1 subcommand) — 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.
• dots memory (5 subcommands) — Save, recall, list, inspect, and reinforce memories in the Memory Bank.
• dots notifications (13 subcommands) — Read, manage, and configure the notification inbox.
• dots onboarding (4 subcommands) — Self-serve onboarding: issue new-workspace invites, relay agent-driven run events, and read or record Setup Assistant state.
• dots orient (no subcommands) — Answer where you are, in one read: the endpoint and the precedence rung that chose it, who this credential is, which company is active and what selected it, the workspace's foundational Dotabase slugs, what it holds, what is waiting on you, what to resume, the unread inbox count, the pending approval queue, and how fresh the code graph is. Run this first in an unfamiliar workspace. Each source is read independently — one the credential is not authorized for (the operator readiness report, the approval queue) is OMITTED from the record and named under unavailable with its status, so a narrow credential still gets everything else and exit code 0.
• dots pages (10 subcommands) — Read and author standalone pages — the sidebar set, a body outline, chosen sections, and the create / update / move / duplicate / delete lifecycle plus the two body composes.
• dots platform (27 subcommands) — Platform-operator administration (cross-tenant Admin plane): authenticate as an operator, manage the operator roster, read the fleet and instance telemetry, run platform jobs, and moderate the hosted marketplace.
• dots playbooks (6 subcommands) — Read, curate, scope, and import Power-Up Playbooks.
• dots plugin (10 subcommands) — Author, run, build, and package a Dots plugin (the SDK Distribute axis).
• dots projects (6 subcommands) — List, read, create, update, complete, and delete projects in the Projects Dotabase.
• dots providers (6 subcommands) — Model providers: the local-agent availability snapshot, each provider's model catalog, an on-demand re-probe, and this instance's bring-your-own-key custody.
• dots public (5 subcommands) — Read a published Dotabase over the anonymous publish-to-web plane — the manifest, a view's rows, one row, a row's neighbour graph, and free-text search. No credential is read or sent; name the instance with --api-url or API_BASE_URL.
• dots publications (3 subcommands) — Publish a Dotabase to the public web, list the company's publications, and take one offline.
• dots reactions (3 subcommands) — Vote on published rows: read a row's public up/down tally, cast or toggle this machine's own reaction, and retract it.
• dots repo (9 subcommands) — Ingest a local repository checkout into the code knowledge graph.
• dots resolve (no subcommands) — Resolve a bare human id (ART-3436), a row UUID, or a row URL copied from the app to the row it names. A human id resolves company-wide through the readable-set-filtered resolver; a URL supplies its own Dotabase; a bare UUID requires --dotabase because it carries no Dotabase context. Distinct from dots rows resolve, which searches a Dotabase by TITLE.
• dots roadmap (2 subcommands) — File and dedup feature requests: submit one into a Roadmap Dotabase as the authenticated principal, or preview the published requests a new one would duplicate.
• dots row-templates (7 subcommands) — Read and author a Dotabase's page templates — the authoritative body scaffold a new row is created from.
• dots rows (30 subcommands) — List, create, import, update, archive, restore, delete, search, and inspect version history of rows in a Dotabase.
• dots sandbox (2 subcommands) — Throwaway sandbox workspaces — provision one to prove behaviour in, destroy it after.
• dots scripts (2 subcommands) — Run stored Scripts and inspect executor capabilities.
• dots search (no subcommands) — Cross-Dotabase Universal Search over everything you can read (smart hybrid: keyword + semantic).
• dots settings (2 subcommands) — Read and write server-backed per-user settings (appearance, profile, integrations, personalization, marketplace, chat).
• dots spaces (5 subcommands) — Create, read, restyle, sort, and delete the workspace's Spaces (the sidebar groupings Dotabases and pages belong to).
• dots stage (1 subcommand) — Record durable artifacts and their provenance.
• dots superpowers (6 subcommands) — List, inspect, invoke, create, update, and delete Superpowers.
• dots sync (12 subcommands) — Bind importer source resources to target Dotabases and run/pause syncs.
• dots tags (5 subcommands) — Manage the company's custom tag categories — the per-company knowledge-classification facets rows can be tagged against.
• dots tasks (8 subcommands) — List, read, create, update, complete, and delete tasks in the Tasks Dotabase.
• dots transcribe (no subcommands) — Derive a transcript from a staged media attachment.
• dots usage (1 subcommand) — Read what this workspace has spent — token and cost aggregation over its conversations and automations.
• dots use (no subcommands) — Set, show, or clear the persisted default active company — the company the CLI operates in when --company / DOTS_COMPANY are absent.
• dots views (17 subcommands) — Manage a Dotabase's saved views — list / create / update / reorder / flag / duplicate / delete, set the default, edit per-view property config + column widths, and manage a dashboard view's widgets.
• dots wait (no subcommands) — Block until one condition occurs, print the occurrence, and exit — always under a deadline, never forever. Conditions: job <executionId> (poll a durable execution to a terminal status), notification (the next notification created for this actor), presence <dotabase-slug> <rowHumanId> (another active session on one row), onboarding-run (the next onboarding run event for this actor).
• dots workspace-templates (1 subcommand) — Provision workspace templates (the buyer estate).
• dots workspaces (9 subcommands) — Workspaces: provision additional companies owned by your login identity, read the active company's plan, manage its avatar, and keep the per-user directory registry.

Family Reference Pages

25 of these families have dedicated references across 11 pages:

• dots dotabases, dots row-templates, and dots spaces — every dots dotabases, dots row-templates, and dots spaces subcommand, with its arguments and options.
• dots rows, dots edges, and dots pages — every dots rows, dots edges, and dots pages subcommand, with its arguments and options.
• dots search and dots tags — every dots search and dots tags subcommand, with its arguments and options.
• dots connections and dots sync — every dots connections and dots sync subcommand, with its arguments and options.
• dots mcp, dots repo, and dots graph — every dots mcp, dots repo, and dots graph subcommand, with its arguments and options.
• dots workspaces, dots account, and dots providers — every dots workspaces, dots account, and dots providers subcommand, with its arguments and options.
• dots settings, dots files, and dots human-md — every dots settings, dots files, and dots human-md subcommand, with its arguments and options.
• dots marketplace and dots plugin — every dots marketplace and dots plugin subcommand, with its arguments and options.
• dots coding-agents and dots git — every dots coding-agents and dots git subcommand, with its arguments and options.
• dots events tail — the live-event streams, reconnect rules, and replay contract.
• dots sandbox — the disposable-workspace create and destroy lifecycle.

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.