dots rows, dots edges, and dots pages

The dots rows, dots edges, and dots pages 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.

The survey reads on this page — rows list, rows search, edges list — answer at summary by default: identity plus the bounded fields, under a footer naming the tier. --level scan narrows a survey read to the identity fields for that record family. Row reads keep the human id, title, 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.

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.

dots rows

dots rows [options] [command]

List, create, import, update, archive, restore, delete, search, and inspect version history of rows in a Dotabase.

dots rows list

dots rows list [options] <dotabase>

List rows in a Dotabase.

Arguments:

• <dotabase> — Dotabase id, slug, or canonical human-id whose rows should be listed.

Options:

• --limit <n> — Maximum records to return.
• --offset <n> — Records to skip before returning the page.
• --cursor <cursor> — Opaque pagination cursor from a prior page (meta.nextCursor).
• --sort <token> — Order the rows: comma-separated tokens, each <field>, <field>.asc, or <field>.desc (bare defaults to asc), e.g. --sort updated.desc,created. <field> is an audit column (created, updated, created_at, updated_at) or a key the Dotabase's schema declares; an unresolvable field falls back to the default order.
• --status <value> — Filter to a workflow status value (the Dotabase's status property; repeatable, values OR together).
• --tags, --tag <value> — Filter to a tag on the Dotabase's tags facet (exact category:value match, e.g. sub-phase:30.2; repeatable, values OR together).
• --title-contains <text> — Filter to rows whose title contains this substring (LIKE match; combines with --status / --tag as an AND). LIKE metacharacters are passed through unescaped.
• --where <pair> — Filter rows server-side as key=value (repeatable). Repeats of the same key OR together; different keys AND, and the channel ANDs with --status / --tag / --title-contains. status, tag/tags, title-contains, and title address the system slots; any other key must be a property declared by the Dotabase schema.
• --where-file <path> — Path to a JSON file mapping filter keys to a value or an array of values ({ "external_id": ["a", "b"] }), merged with the --where pairs under the same semantics — the bulk channel for value sets that outgrow the command line.
• --metadata-identity <spec> — Filter to rows whose machine metadata at a dotted path equals any listed value, as path=value[,value...] (e.g. learn.extraction_identity=abc,def). Reads the metadata bag, not declared properties; ANDs with every other filter. Repeatable values OR; pass one path per invocation. Value files: use --metadata-identity-file for sets that outgrow the command line.
• --metadata-identity-file <path> — Path to a JSON file of {"path": "learn.extraction_identity", "values": ["a", "b"]} for metadata-identity value sets that outgrow the command line. Mutually exclusive with --metadata-identity.
• --archived — List archived rows instead of live ones (lifecycle scope).
• --verified — Show only human-verified rows.
• --unverified — Show only unverified rows.
• --no-body — Omit the row body field from list output.
• --count — Print the number of records this list returns instead of the records themselves.

dots rows count

dots rows count [options] <dotabase>

Count rows in a Dotabase (a genuine filtered count(*)), honoring the --where / --status / --tag / --title-contains filters.

Arguments:

• <dotabase> — Dotabase id, slug, or canonical human-id whose rows should be counted.

Options:

• --status <value> — Filter to a workflow status value (the Dotabase's status property; repeatable, values OR together).
• --tags, --tag <value> — Filter to a tag on the Dotabase's tags facet (exact category:value match, e.g. sub-phase:30.2; repeatable, values OR together).
• --title-contains <text> — Filter to rows whose title contains this substring (LIKE match; combines with --status / --tag as an AND). LIKE metacharacters are passed through unescaped.
• --where <pair> — Filter rows server-side as key=value (repeatable). Repeats of the same key OR together; different keys AND, and the channel ANDs with --status / --tag / --title-contains. status, tag/tags, title-contains, and title address the system slots; any other key must be a property declared by the Dotabase schema.
• --where-file <path> — Path to a JSON file mapping filter keys to a value or an array of values ({ "external_id": ["a", "b"] }), merged with the --where pairs under the same semantics — the bulk channel for value sets that outgrow the command line.

dots rows resolve

dots rows resolve [options] <dotabase> <title>

Resolve a human-friendly title to a row's canonical human id, e.g. dots rows resolve tasks "Ship the launch". Prefers an exact title match, then a unique prefix, then a unique substring; an ambiguous title lists the candidates.

Arguments:

• <dotabase> — Dotabase id, slug, or canonical human-id containing the row.
• <title> — A title (or title fragment) to resolve to a single row human id.

Options:

• --id-only — Print only the canonical human id, newline-terminated, with no formatter envelope or DBOM.

dots rows search

dots rows search [options] <dotabase> <query>

Keyword, semantic, or hybrid search over a Dotabase's rows.

Arguments:

• <dotabase> — Dotabase id, slug, or canonical human-id to search.
• <query> — Search query text.

Options:

• --limit <n> — Maximum results to return.
• --sort <token> — Sort token (e.g. updated_at).
• --cursor <cursor> — Pagination cursor from a prior page.
• --mode <mode> — Retrieval mode: keyword (default, BM25) | semantic (vector) | hybrid (RRF fusion). semantic/hybrid need an embedding-enabled Dotabase.
• --verified — Show only human-verified rows.
• --unverified — Show only unverified rows.

dots rows get-many

dots rows get-many [options] <dotabase> [ids...]

Read up to 500 body-free rows by UUID, human id, or exact title in one request.

Arguments:

• <dotabase> — Dotabase id, slug, or canonical human-id containing the rows.
• [ids] — Row UUIDs, human ids, or exact titles, repeated or comma-separated (omit to read --from-file or stdin).

Options:

• --from-file <path> — JSON file containing row UUIDs, human ids, or exact titles; duplicate titles are reported as ambiguous (when no positional refs or file are given, reads stdin).
• --include-body — Include row bodies. Body-bearing responses are byte-budgeted server-side; rows that did not fit come back under truncated for re-request.

dots rows get

dots rows get [options] <dotabase> [humanId]

Read a single row (a DOT) by its human id from a Dotabase, e.g. dots rows get deferrals DEFERRAL-12.

Arguments:

• <dotabase> — Dotabase id, slug, or canonical human-id containing the row.
• [humanId] — Row human id to read, e.g. TASK-12 or DEFERRAL-7. Omit it to address the row by a human id, UUID, or app row URL passed as the single positional.

Options:

• --body-only — Print only the row body (Markdown by default; --body-format raw for the stored string), with no envelope or other fields.
• --body-out <file> — Write the row body to <file> (Markdown by default; --body-format raw for the stored string); print the rest of the row without the body field.
• --sections <refs> — Expand only these body sections by ordinal ref from rows outline (comma-separated, e.g. 2,4.1); each ref returns its whole subtree.
• --no-record-access — Read without updating the row's access_count or last_accessed_at metadata.

dots rows outline

dots rows outline [options] <dotabase> [humanId]

Read a row body's H1-H3 outline with per-section word counts, then expand chosen sections via rows get --sections.

Arguments:

• <dotabase> — Dotabase id, slug, or canonical human-id containing the row.
• [humanId] — Row human id whose body outline should be read. Omit it to address the row by a human id, UUID, or app row URL passed as the single positional.

dots rows versions

dots rows versions [options] <dotabase> [humanId]

List a row's version-history snapshots (newest first) by human id, or compare two of them with --diff. Snapshot bodies honor the global --body-format (markdown by default, the stored string under raw).

Arguments:

• <dotabase> — Dotabase id, slug, or canonical human-id containing the row.
• [humanId] — Row human id whose version history should be listed. Omit it to address the row by a human id, UUID, or app row URL passed as the single positional.

Options:

• --limit <n> — Maximum versions to return.
• --offset <n> — Versions to skip before returning.
• --diff <versions...> — Compare two versions as readable text: --diff <vA> <vB> diffs vA against vB; --diff <vA> diffs vA against the row's current live state. Ignores --limit/--offset.

dots rows create

dots rows create [options] <dotabase>

Create a row in a Dotabase.

Arguments:

• <dotabase> — Dotabase id, slug, or canonical human-id to create the row in.

Options:

• --set <pair> — Set a custom property as key=value (repeatable). Each value is wrapped as a text envelope.
• --title <title> — Row title.
• --body <text> — Row body text.
• --body-file <path> — Path to a file whose full UTF-8 content becomes the row body (for bodies too large to pass inline).
• --json <json> — Inline JSON object of property envelopes ({ key: { type, value } }).
• --from-file <path> — Path to a JSON file of property envelopes.
• --tag, --tags <list> — Comma-separated tags to set on the row.
• --diiice-type <type> — DIIICE type, overriding the auto-classifier.
• --diiice-subtype <subtype> — DIIICE subtype, overriding the auto-classifier.
• --source-type <type> — Provenance: manual | import | extraction | graduation | api (defaults to api).
• --idempotency-key <key> — Retry key for this create. Re-running the same command with the same key returns the row the first run created instead of a duplicate; reusing it with changed content is refused as a conflict. Safe to reuse across commands — each derives its own key from yours.

dots rows upsert

dots rows upsert [options] <dotabase> <title>

Create a row, or update the one that already carries this exact title. The title is the upsert key and matches case-insensitively but EXACTLY — a prefix or substring never counts, so an upsert can neither rewrite an unrelated row nor mint a silent duplicate. Two rows carrying the same title is a usage error naming both.

Arguments:

• <dotabase> — Dotabase id, slug, or canonical human-id to upsert the row in.
• <title> — The row title that is both the match key and, on a create, the new row's title.

Options:

• --idempotency-key <key> — Retry key for this create. Re-running the same command with the same key returns the row the first run created instead of a duplicate; reusing it with changed content is refused as a conflict. Safe to reuse across commands — each derives its own key from yours.
• --set <pair> — Set a custom property as key=value (repeatable). Each value is wrapped as a text envelope.
• --body <text> — Row body text, replacing the stored body on the update arm.
• --json <json> — Inline JSON object of property envelopes ({ key: { type, value } }).
• --from-file <path> — Path to a JSON file of property envelopes.
• --tag, --tags <list> — Comma-separated tags to set on the row.
• --diiice-type <type> — DIIICE type, overriding the auto-classifier.
• --diiice-subtype <subtype> — DIIICE subtype, overriding the auto-classifier.
• --body-file <path> — Path to a file whose full UTF-8 content is used instead of --body (for text too large to pass inline). Mutually exclusive with --body.

dots rows bulk-create

dots rows bulk-create [options] <dotabase>

Create many rows in a Dotabase from a JSON array (the agent enrichment write-surface). Reads a JSON file with --from-file, or stdin otherwise. Each element is a row-create body ({ title?, body?, properties?, tags?, diiice_type?, ... }); large batches are split into capped requests, and a per-row failure is reported without stranding the rest.

Arguments:

• <dotabase> — Dotabase id, slug, or canonical human-id to create the rows in.

Options:

• --from-file <path> — Path to a JSON file of row-create bodies (a bare array, or { rows: [...] }). Reads stdin when omitted.
• --idempotency-key <key> — Retry key for this create. Re-running the same command with the same key returns the row the first run created instead of a duplicate; reusing it with changed content is refused as a conflict. Safe to reuse across commands — each derives its own key from yours.
• --dry-run — Validate every row against the real create-time write path and insert nothing; reports which rows would fail. Exits non-zero if any would.

dots rows bulk-update

dots rows bulk-update [options] <dotabase>

Update many rows in one Dotabase through the capped bulk-update route. Two input shapes: --where selects rows SERVER-SIDE and --set/--title/--body/--tags apply ONE change-set to all of them; or --from-file (stdin when omitted) carries a JSON array of per-row entries ({ id | humanId, title?, body?, properties?, tags?, expectedUpdatedAt? }), which are GROUPED by identical change-set so a heterogeneous backfill costs one request per distinct change-set per 100 rows — not one per row.

Arguments:

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

Options:

• --where <pair> — Select rows server-side as key=value (repeatable). Repeats of the same key OR together; different keys AND. status, tag/tags, title-contains, and title address the system slots; any other key must be a property declared by the Dotabase schema.
• --set <pair> — Set a property as key=value (repeatable), typed from the Dotabase schema. Applies to every selected row.
• --title <title> — Title to set on every selected row.
• --body <text> — Body to set on every selected row.
• --body-file <path> — Path to a file whose full UTF-8 content becomes the body of every selected row.
• --tag, --tags <list> — Comma-separated tags to set (whole-list replace) on every selected row.
• --from-file <path> — Path to a JSON file of per-row update entries (a bare array, or { rows: [...] }). Reads stdin when omitted.
• --dry-run — Resolve the selection and print the batches that WOULD be sent; issues no write.

dots rows import

dots rows import [options] <dotabase>

Import rows from a CSV file through the server-side CSV import route.

Arguments:

• <dotabase> — Dotabase id, slug, or canonical human-id to import rows into.

Options:

• --file <path> — Path to the CSV file to import.
• --title-column <name> — CSV header whose cell becomes each row title.
• --body-column <name> — CSV header whose cell becomes each row body.
• --column <csv=property> — Map a CSV header to a Dotabase property key as csvHeader=propertyKey (repeatable).
• --defer-enrichment — Import immediately and enrich embedding, classification, AI fill, and tag inference in the background.
• --no-wait — Return the durable execution receipt immediately; reconnect with rows import-status.

dots rows import-status

dots rows import-status [options] <dotabase> <executionId>

Read a durable row-import execution, including progress and checkpoint state.

Arguments:

• <dotabase> — Dotabase id, slug, or canonical human-id targeted by the import.
• <executionId> — Durable execution id returned by rows import --no-wait.

dots rows import-cancel

dots rows import-cancel [options] <dotabase> <executionId>

Request cancellation of a durable row-import execution.

Arguments:

• <dotabase> — Dotabase id, slug, or canonical human-id targeted by the import.
• <executionId> — Durable execution id returned by rows import --no-wait.

dots rows update

dots rows update [options] <dotabase> [humanId]

Update a row's title, body, icon, or properties by human id.

Arguments:

• <dotabase> — Dotabase id, slug, or canonical human-id containing the row.
• [humanId] — Row human id to update. Omit it to address the row by a human id, UUID, or app row URL passed as the single positional.

Options:

• --set <pair> — Set a property as key=value (repeatable). Each value is wrapped as a text envelope.
• --json <json> — Inline JSON object of property envelopes.
• --from-file <path> — Path to a JSON file of property envelopes ({ key: { type, value } }) — the injection-safe channel for free-text values a shell string cannot carry.
• --title <title> — Row title.
• --body <text> — Row body text.
• --body-file <path> — Path to a file whose full UTF-8 content becomes the row body (for bodies too large to pass inline).
• --body-append <line> — Append this line as a new paragraph to the row's body (atomic; never rewrites the existing body). Mutually exclusive with --body-replace-section.
• --body-append-file <path> — Path to a file whose full UTF-8 content is used instead of --body-append (for text too large to pass inline). Mutually exclusive with --body-append.
• --body-replace-section <heading> — Replace the body section under this exact heading; the new section content (including its heading) comes from --body / --body-file. Mutually exclusive with --body-append.
• --status <value> — Workflow status value for the Dotabase's status property.
• --tag, --tags <list> — Comma-separated tags that REPLACE the row's whole tag list. To add or drop tags without touching the rest, use --add-tags / --remove-tags.
• --add-tags <list> — Comma-separated tags to add (union) — preserves the row's existing tags. Mutually exclusive with --tags.
• --remove-tags <list> — Comma-separated tags to remove — preserves the row's other tags. Mutually exclusive with --tags.
• --diiice-type <type> — DIIICE type, overriding the classifier value.
• --diiice-subtype <subtype> — DIIICE subtype, overriding the classifier value.
• --source-type <type> — Provenance: manual | import | extraction | graduation | api.
• --icon <value> — Row icon (emoji or named icon).
• --icon-color <value> — Row icon color.
• --metadata <json> — Inline JSON object merged per-top-level-key into the row's machine metadata bag, e.g. '{"enrichment":{"summary":"..."}}'.
• --metadata-file <path> — Path to a JSON object merged per-top-level-key into the row's machine metadata bag.
• --force — Overwrite the stored body even when it holds rich content (media, mentions, tables) that Markdown cannot represent and the write would discard.
• --version-boundary <mode> — Cut a version-history version for this edit even inside an open coalescing window (only value: force). Applies to the FIRST write this command makes; any follow-on write in the same invocation folds into that version.
• --expect-updated-at <timestamp> — Apply this edit only if the row is still at this revision — the updated_at from the read this edit is based on (e.g. dots rows get <dotabase> <id> --fields updated_at). A row changed by someone else since then is refused as a conflict instead of overwritten. Omitted, the write is unconditional.

dots rows append-body

dots rows append-body [options] <dotabase> [humanId] [text]

Append a paragraph to a row's body by human id — a safe append that never overwrites the existing body, unlike rows update --body. A Markdown body stays Markdown; a TipTap-doc (web-editor) body stays a doc. e.g. dots rows append-body tasks TASK-12 "Resolved on main" --bold-prefix "Resolved:".

Arguments:

• <dotabase> — Dotabase id, slug, or canonical human-id containing the row.
• [humanId] — Row human id whose body to append to. Omit it to address the row by a human id, UUID, or app row URL passed as the single positional.
• [text] — Paragraph text to append.

Options:

• --bold-prefix <label> — Optional bold label rendered before the text, e.g. "Resolved:".
• --text-file <path> — Path to a file whose full UTF-8 content is used instead of <text> (for text too large to pass inline). Mutually exclusive with <text>.

dots rows archive

dots rows archive [options] <dotabase> [humanId]

Archive a row by human id.

Arguments:

• <dotabase> — Dotabase id, slug, or canonical human-id containing the row.
• [humanId] — Row human id to archive; omit when using --id.

Options:

• --id <uuid> — Archive by row UUID instead of human id.
• --yes — Confirm the destructive action (required; it cannot be undone).
• --dry-run — Resolve and report what would change; writes nothing.

dots rows purge-many

dots rows purge-many [options]

Permanently delete row UUIDs in capped bulk requests (maintenance surface).

Options:

• --from-file <path> — JSON array of row UUIDs; stdin when omitted.
• --yes — Confirm the destructive action (required; it cannot be undone).
• --dry-run — Resolve and report what would change; writes nothing.

dots rows restore

dots rows restore [options] <dotabase> [humanId]

Restore an archived row by human id.

Arguments:

• <dotabase> — Dotabase id, slug, or canonical human-id containing the row.
• [humanId] — Row human id to restore; omit when using --id.

Options:

• --id <uuid> — Restore by row UUID instead of human id.

dots rows delete

dots rows delete [options] <dotabase> [humanId]

Archive a row by human id; pass --purge for an irreversible hard delete.

Arguments:

• <dotabase> — Dotabase id, slug, or canonical human-id containing the row.
• [humanId] — Row human id to archive or purge; omit when using --id.

Options:

• --id <uuid> — Archive or purge by row UUID instead of human id.
• --purge — Irreversibly hard-delete the row instead of archiving it.
• --yes — Confirm the destructive action (required; it cannot be undone).
• --dry-run — Resolve and report what would change; writes nothing.

dots rows reinforce

dots rows reinforce [options] <dotabase> [humanId]

Reinforce a memory by human id (applies an FSRS review grade).

Arguments:

• <dotabase> — Dotabase id, slug, or canonical human-id containing the row.
• [humanId] — Row human id to reinforce. Omit it to address the row by a human id, UUID, or app row URL passed as the single positional.

Options:

• --grade <1-4> — FSRS review grade 1-4 (1=Again, 2=Hard, 3=Good, 4=Easy). Defaults to Easy (4) when omitted.
• --source <source> — Reinforcement source (explicit | user_reference). Defaults to explicit when omitted.

dots rows consolidate

dots rows consolidate [options] <dotabase> [humanId]

Consolidate duplicate rows into a primary row by human id (folds each --duplicates row into the primary).

Arguments:

• <dotabase> — Dotabase id, slug, or canonical human-id containing the primary row.
• [humanId] — Human id of the primary row the duplicates fold into. Omit it to address the row by a human id, UUID, or app row URL passed as the single positional.

Options:

• --duplicates <humanId> — Duplicate row human id to fold into the primary; repeatable, 1-50 required.
• --yes — Confirm the destructive action (required; it cannot be undone).
• --dry-run — Resolve and report what would change; writes nothing.

dots rows verify

dots rows verify [options] <dotabase> [humanId]

Mark a row human-verified (by human id).

Arguments:

• <dotabase> — Dotabase id, slug, or canonical human-id containing the row.
• [humanId] — Row human id to mark verified. Omit it to address the row by a human id, UUID, or app row URL passed as the single positional.

dots rows unverify

dots rows unverify [options] <dotabase> [humanId]

Clear a row's human-verified mark (by human id).

Arguments:

• <dotabase> — Dotabase id, slug, or canonical human-id containing the row.
• [humanId] — Row human id to mark unverified. Omit it to address the row by a human id, UUID, or app row URL passed as the single positional.

dots rows pin

dots rows pin [options] <dotabase> [humanId]

Pin a row so it surfaces first in its Dotabase, e.g. dots rows pin tasks TASK-12. Pinning an already-pinned row succeeds and changes nothing.

Arguments:

• <dotabase> — Dotabase id, slug, or canonical human-id containing the row.
• [humanId] — Row human id to pin. Omit it to address the row by a human id, UUID, or app row URL passed as the single positional.

dots rows unpin

dots rows unpin [options] <dotabase> [humanId]

Clear a row's pin, e.g. dots rows unpin tasks TASK-12. Unpinning an unpinned row succeeds and changes nothing.

Arguments:

• <dotabase> — Dotabase id, slug, or canonical human-id containing the row.
• [humanId] — Row human id to unpin. Omit it to address the row by a human id, UUID, or app row URL passed as the single positional.

dots rows duplicate

dots rows duplicate [options] <dotabase> [humanId]

Copy a row into a new row of the same Dotabase, e.g. dots rows duplicate tasks TASK-12. The copy is a live row with its own freshly-minted human id; an archived original copies too, and the copy is live.

Arguments:

• <dotabase> — Dotabase id, slug, or canonical human-id containing the row.
• [humanId] — Row human id to duplicate. Omit it to address the row by a human id, UUID, or app row URL passed as the single positional.

dots rows move

dots rows move [options] <dotabase> [humanId]

Move rows to another Dotabase. Each moved row is reissued a human id in its new home and its property values are remapped onto the destination schema, so a value whose key the destination does not declare is dropped — run --dry-run first to see the mapped and unmapped keys per row.

Arguments:

• <dotabase> — Dotabase id, slug, or canonical human-id the rows are moving out of.
• [humanId] — Row human id to move. Omit it to address the row by a human id, UUID, or app row URL passed as the single positional, or pass --from-file to move a set.

Options:

• --to <dotabase> — Destination Dotabase id, slug, or canonical human-id. Required.
• --from-file <path> — JSON file containing an array of row human ids or UUIDs to move (stdin when the flag is given no path). Resolved inside <dotabase>; cannot be combined with the row positional.
• --yes — Confirm the destructive action (required; it cannot be undone).
• --dry-run — Ask the server for the per-row remap preview — the destination, the property keys that map, and the keys that do not — persisting nothing.

dots rows activity

dots rows activity [options] <dotabase> [humanId]

List one row's activity events, newest first — creations, status and tag changes, edge writes, embedding and title changes. The Dotabase-wide feed is dots dotabases activity.

Arguments:

• <dotabase> — Dotabase id, slug, or canonical human-id containing the row.
• [humanId] — Row human id whose activity should be listed. Omit it to address the row by a human id, UUID, or app row URL passed as the single positional.

Options:

• --limit <n> — Maximum events to return, applied to this row's events after the Dotabase feed is narrowed to it.
• --offset <n> — Records to skip before returning the page.
• --count — Print the number of records this list returns instead of the records themselves.

dots edges

dots edges [options] [command]

Create, read, count, and delete knowledge-graph edges between rows, within a Dotabase or spanning two.

dots edges types

dots edges types [options]

List the active company's built-in and workspace-scoped edge types without creating probe edges.

Options:

• --category <category> — Keep only one category: semantic | structural | provenance | contextual | temporal.
• --source-kind <kind> — Keep edge types valid for this source entity kind.
• --target-kind <kind> — Keep edge types valid for this target entity kind.

dots edges create

dots edges create [options] <dotabase> <sourceHumanId> <targetHumanId> <edgeType>

Create one edge between two rows by their human ids. Source resolves in <dotabase>; with --target-dotabase the target resolves in that Dotabase (the cross-Dotabase form). Both Dotabases must belong to your company.

Arguments:

• <dotabase> — Dotabase id, slug, or canonical human-id the source row (and, absent --target-dotabase, the target row) lives in.
• <sourceHumanId> — Source row human id (the edge's tail).
• <targetHumanId> — Target row human id (the edge's head).
• <edgeType> — Edge type label, e.g. implements | documents | references.

Options:

• --target-dotabase <ref> — Resolve the target human id in this Dotabase (id, slug, or canonical human-id) instead (the cross-Dotabase form).
• --if-absent — Treat an already-drawn pair as success instead of a conflict: the edge is created if missing, and an existing one is left untouched and reported as already present. Makes a re-draw safe to retry. Omitted, a duplicate pair fails.
• --reasoning <text> — Optional free-text rationale persisted on the edge.
• --reasoning-file <path> — Path to a file whose full UTF-8 content is used instead of --reasoning (for text too large to pass inline). Mutually exclusive with --reasoning.

dots edges delete

dots edges delete [options] <edgeId>

Permanently delete one knowledge-graph edge by its id.

Arguments:

• <edgeId> — Edge UUID to delete.

Options:

• --yes — Confirm the destructive action (required; it cannot be undone).
• --dry-run — Resolve and report what would change; writes nothing.

dots edges update

dots edges update [options] <edgeId>

Update an edge's mutable fields in place while preserving its id, endpoints, method, and provenance.

Arguments:

• <edgeId> — Edge UUID to update.

Options:

• --confidence <n> — Replacement confidence from 0 through 1.
• --weight <n> — Replacement traversal weight from 0 through 1.
• --metadata <json> — Replacement metadata object as JSON.
• --reasoning <text> — Replacement free-text rationale persisted on the edge.
• --reasoning-file <path> — Path to a file whose full UTF-8 content is used instead of --reasoning (for text too large to pass inline). Mutually exclusive with --reasoning.
• --yes — Confirm the destructive action (required; it cannot be undone).
• --dry-run — Resolve and report what would change; writes nothing.

dots edges list

dots edges list [options] <dotabase> <humanId>

List a row's knowledge-graph edges, optionally filtered by type and direction. Direction is relative to <humanId>: out = the row is the edge source, in = the row is the target; default returns every incident edge.

Arguments:

• <dotabase> — Dotabase id, slug, or canonical human-id the row lives in.
• <humanId> — Row human id whose incident edges to list (e.g. DOC-12).

Options:

• --type <edgeType> — Keep only edges of this exact type, e.g. references.
• --direction <in|out> — Keep only edges in this direction relative to the row: in | out.
• --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 edges get

dots edges get [options] <edgeId>

Read one knowledge-graph edge by its id with absolute source and target identity, reasoning, confidence, method, and the raw metadata bag.

Arguments:

• <edgeId> — Edge UUID to read.

dots edges census

dots edges census [options] <dotabase>

Count a Dotabase's ACTIVE incident edges (either endpoint homed there), read from the edges table itself — so system-trust spine edges, which never bump the denormalized per-row edge_count, are counted too.

Arguments:

• <dotabase> — Dotabase id, slug, or canonical human-id whose incident edges to count.

Options:

• --type <verb> — Count only this exact edge type.
• --group-by <field> — Return exact per-type counts; the only accepted value is type.

dots edges bulk

dots edges bulk [options]

Create many edges from a JSON array. Reads a JSON file with --from-file, or stdin otherwise. Each element is a bulk-edge body ({ dotabaseId, edgeType, sourceIds, targetIds, targetDotabaseId?, reasoning? }) keyed on row UUIDs (the connect-picker shape); each request creates the cartesian product of its sourceIds x targetIds. A per-batch failure is reported without stranding the rest.

Options:

• --from-file <path> — Path to a JSON file of bulk-edge bodies (a bare array, or { edges: [...] }). Reads stdin when omitted.

dots edges bulk-pairs

dots edges bulk-pairs [options] <dotabase>

Create exactly the edges you list — one JSON element per edge, each with its own sourceId, targetId, edgeType, and optional targetDotabaseId / reasoning / metadata. Unlike bulk (a cartesian sourceIds x targetIds product under one verb), a sparse campaign across a heterogeneous corpus rides this shape directly. Pairs are sent in chunks of at most 500 per request; an existing pair is a no-op that preserves the stored edge and its metadata, counted as skipped.

Arguments:

• <dotabase> — Dotabase id, slug, or canonical human-id the source rows live in (each pair's target resolves there too unless it carries targetDotabaseId).

Options:

• --from-file <path> — Path to a JSON file of exact pairs (a bare array, or { pairs: [...] }). Reads stdin when omitted.

dots edges graduate

dots edges graduate [options] <lessonHumanId> <guardHumanId>

Record the graduated_to provenance edge from a Lessons row to a Guardrails row (system-trust; the public edge seam rejects graduated_*). Idempotent per (lesson, guard) pair.

Arguments:

• <lessonHumanId> — Lessons row human id (e.g. LESSON-12) — the graduating lesson.
• <guardHumanId> — Guardrails row human id (e.g. GUARD-3) — the rule it graduated into.

dots pages

dots pages [options] [command]

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 pages list

dots pages list [options]

List the workspace's standalone pages (id, slug, title, spaceId) — the page-to-Space membership the sidebar renders.

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 pages outline

dots pages outline [options] <page>

Read a page body's H1-H3 outline with per-section word counts, then expand chosen sections via pages sections.

Arguments:

• <page> — Page id (UUID) or slug whose body outline should be read.

dots pages sections

dots pages sections [options] <page> <refs>

Expand chosen page-body sections by ordinal ref from pages outline; each ref returns its whole subtree.

Arguments:

• <page> — Page id (UUID) or slug whose body sections should be read.
• <refs> — Comma-separated ordinal refs to expand, e.g. 2,4.1.

dots pages create

dots pages create [options] <name>

Create a standalone page in a Space. The slug is derived from the name server-side. e.g. dots pages create "Team Guide" --space general.

Arguments:

• <name> — Title of the new page.

Options:

• --space <ref> — Space the page belongs to, by id (UUID) or slug. Required.
• --parent <page> — Parent page (id or slug) to nest the new page under; omit for a top-level page.
• --icon <token> — Icon token for the page.
• --icon-color <token> — Icon color token for the page.

dots pages update

dots pages update [options] <page>

Update a page's title, slug, icon, or icon color. Body edits go through pages append / pages replace-section.

Arguments:

• <page> — Page id (UUID) or slug to update.

Options:

• --title <title> — New page title.
• --slug <slug> — New page slug (the addressable handle).
• --icon <token> — New icon token; pass none to clear it.
• --icon-color <token> — New icon color token; pass none to clear it.

dots pages move

dots pages move [options] <page>

Move a page in the sidebar — into another Space, under another parent, or to another position among its siblings.

Arguments:

• <page> — Page id (UUID) or slug to move.

Options:

• --space <ref> — Destination Space, by id (UUID) or slug.
• --parent <page> — New parent page (id or slug); pass none to make the page top-level.
• --position <n> — New 0-based position among its siblings.

dots pages duplicate

dots pages duplicate [options] <page>

Duplicate a page, body and all, beside the original.

Arguments:

• <page> — Page id (UUID) or slug to duplicate.

dots pages delete

dots pages delete [options] <page>

Delete a page and its body. No action reverses it.

Arguments:

• <page> — Page id (UUID) or slug to delete.

Options:

• --yes — Confirm the destructive action (required; it cannot be undone).
• --dry-run — Resolve and report what would change; writes nothing.

dots pages append

dots pages append [options] <page>

Append Markdown to the end of a page's body. Composed client-side over the whole-document replace and sent under the page's compare-and-set token, so a page edited since the read is refused rather than overwritten. Every existing node is preserved byte-for-byte.

Arguments:

• <page> — Page id (UUID) or slug whose body should be appended to.

Options:

• --body <text> — Markdown to append as new blocks at the end of the body.
• --body-file <path> — Path to a file whose full UTF-8 content is used instead of --body (for text too large to pass inline). Mutually exclusive with --body.

dots pages replace-section

dots pages replace-section [options] <page> <ref>

Replace one page-body section — its heading through its whole subtree — with new Markdown, addressed by the ordinal ref pages outline returns. Composed client-side over the whole-document replace and sent under the page's compare-and-set token; every node outside the replaced section is preserved.

Arguments:

• <page> — Page id (UUID) or slug whose section should be replaced.
• <ref> — Ordinal ref of the section to replace, e.g. 2 or 4.1 (from pages outline).

Options:

• --body <text> — Markdown replacing the whole section, including its new heading.
• --body-file <path> — Path to a file whose full UTF-8 content is used instead of --body (for text too large to pass inline). Mutually exclusive with --body.

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.