Context Commands

List & Search

Command	Flags	Description	Example
`context list`	`--stale`, `--suggested`, `--status`, `--repo`, `--tag <name>`, `--docs`, `--auto`, `--manual`, `--limit <n>`, `--all`, `--json`	List topics with filters. Defaults to the 40 most relevant (drifted first); prints `Showing N of M`. Use `--all` / `--limit N` for more (`--json` is uncapped). `--suggested` = not-yet-Knowledge (Notes + Up for review: `draft` + `proposed`). `--tag` is repeatable (OR semantics), so you can list a whole category.	`driftless context list --tag billing`
`context get <topic>`	`--json`	Full topic detail	`driftless context get b2b-guard`
`context get --files`	`--files "a,b"`, `--json`	Match topics to files	`driftless context get --files "src/auth/guard.ts"`
`context get --diff`	`--json`, `--mark`	Topics for current changes	`driftless context get --diff`
`context get --diff --mark`	`--mark`	…and flag the matched topics drifted from local git	`driftless context get --diff --mark`
`context search`	query, `--tag <name>`, `--json`, `--include-notes`	Relevance-ranked full-text search (top 50; name/title matches rank highest). Supports `"quoted phrases"`, `OR`, `-negation`. Narrow with more terms rather than paging. `--tag` (repeatable, OR) scopes the search to a category. Knowledge + topics up for review; Notes excluded unless `--include-notes`.	`driftless context search "refunds" --tag billing`

Tags: the category registry

Tags are workspace-level categories topics anchor to. Names normalize on every surface (lowercase, whitespace→dashes), so Billing and billing are the same tag. Attaching a tag that was never pre-created auto-registers it. The registry is curation, never a gate.

Command	Flags	Description	Example
`tags`	`--limit <n>`, `--offset <n>`, `--json`	List the registry with per-tag topic counts (paginated, most-used first)	`driftless tags`
`tags add <name>`	`--description "..."`	Pre-create a tag (idempotent: re-adding merges the description)	`driftless tags add billing --description "Billing rules"`
`tags rename <old> <new>`	none	Rename everywhere, rewriting every topic carrying the tag (owner/admin)	`driftless tags rename billing facturacion`
`tags rm <name>`	none	Delete from the registry and detach from every topic (owner/admin)	`driftless tags rm legacy`

Create & Update

Command	Flags	Description	Example
`context add`	`--what`, `--how`, `--content`, `--pattern`, `--tags`, `--rel`, `--where`, `--decisions`, `--gotchas`, `--ownership`, `--status`, `--file`, `--dry-run`	Create topic	`driftless context add "payment-flow" --content "# Payment Flow\n\n## What\nStripe checkout" --pattern "src/billing/**"`
`context update`	`--what`, `--how`, `--content`, `--gotcha`, `--decision`, `--invariant`, `--check`, `--enforce`, `--add-pattern`, `--remove-pattern`, `--tags`, `--status`, `--where`, `--decisions`, `--gotchas`, `--ownership`, `--pattern`, `--rel`, `--dry-run`, `--json`	Modify topic	`driftless context update payment-flow --gotcha "Idempotency keys required" --add-pattern "src/webhooks/stripe/**"`
`context delete`	`--dry-run`, `--json`	Delete topic	`driftless context delete payment-flow --dry-run`
`context merge`	`--into`, `--dry-run`, `--json`	Fold a duplicate into its survivor (archives source; prose never merged)	`driftless context merge payment-flow-2 --into payment-flow --dry-run`
`context move`	`--to <workspace>`, `--dry-run`, `--json`	Re-home a topic to another workspace you belong to	`driftless context move payment-flow --to acme-platform`

Pattern validation

Every --pattern and --add-pattern is validated against your local checkout before the API call:

Result	Meaning
`✓ pattern "src/auth/**" matches 12 files`	Healthy anchor
`⚠ over-broad anchor`	Matches over 100 files; consider splitting the topic
`✗ pattern matches 0 files`	Blocked; fix the glob or use `--where` for an explicit path

Link & Health

Command	Flags	Description	Example
`context link`	`--dry-run`, `--json`	Cross-repo linkage	`driftless context link payment-flow`
`context doctor`	`--json`	Audit context health	`driftless context doctor`
`context relations`	`--json`	List typed relations	`driftless context relations payment-flow`
`context graph`	`--depth N`, `--json`	Topic relation graph	`driftless context graph payment-flow --depth 2`

context doctor audits the topic layer for zombie (patterns match zero files), orphaned (repo deleted), stale, and draft topics.

Governance

A topic becomes Knowledge only once it’s merged in. Lifecycle: draft → proposed → reviewed → archived. Agents propose; merging is an owner/admin act. An agent runs it only when an owner/admin explicitly asks. See Governance.

Command	Description	Example
`context propose <topic>`	Put a Note up for review	`driftless context propose payment-flow`
`context approve <topic>`	Add it to knowledge (owner/admin; only when asked)	`driftless context approve payment-flow`
`context reject <topic>`	Send it back to a Note	`driftless context reject payment-flow`
`context archive <topic>`	Retire a topic	`driftless context archive payment-flow`
`context pr <topic>`	List Suggested edits	`driftless context pr payment-flow`
`context pr <topic> --open`	Open a Suggested edit (`--summary` + content flags)	`driftless context pr payment-flow --open --summary "..." --content @new.md`
`context pr <topic> --merge <id>`	Merge a Suggested edit (owner/admin)	`driftless context pr payment-flow --merge <id>`
`context pr <topic> --reject <id>`	Close a Suggested edit without merging (owner/admin)	`driftless context pr payment-flow --reject <id>`

Command	Description	Example
`context share <topic>`	Public read-only link (`--revoke` to turn off)	`driftless context share payment-flow`

Workspaces

A workspace is the top-level container for context; you can belong to several and switch between them without re-authenticating. One driftless login registers every workspace you belong to under a single scoped key.

Command	Description	Example
`workspace list`	The workspaces you belong to (● = active)	`driftless workspace list`
`workspace current`	The active workspace	`driftless workspace current`
`workspace switch <slug>`	Operate on another one (no re-login)	`driftless workspace switch acme-platform`
`workspace add --key <drift_…>`	Register a workspace by its API key	`driftless workspace add --key drift_…`
`context move <topic> --to <slug>`	Re-home a topic to another workspace	`driftless context move payment-flow --to acme-platform`

context move resets the topic to a Note in its new workspace (Knowledge status doesn’t carry across workspaces) and requires owner/admin in the source plus membership in the target. See Workspaces.

Beyond context: the rest of the workspace

The whole workspace is headless, not just topics. The same CLI drives the work surfaces, and an agent runs the commands a human would:

Family	Commands	Docs
Collections & records	`collection list\|get\|records`, `collection record add\|update`	Collections
Areas	`area list\|add\|rename\|rm`, plus `context add/update --area`	Areas
Notes & sharing	`note add`, share via the API / dashboard inbox	Notes & Sharing
Members	`member list\|invite\|role\|rm\|invites`	Workspaces
Market data	`market capabilities\|suppliers\|opportunities\|awards\|risks\|permits`	Market Data

Run driftless <family> --help for the full flag set.

Get started

Connect

Concepts

Work & collaborate

Guides

Agents

MCP reference

CLI reference

API reference

Platform

Context Commands

List & Search

Tags: the category registry

Create & Update

Pattern validation

Link & Health

Governance

Workspaces

Beyond context: the rest of the workspace

​List & Search

​Tags: the category registry

​Create & Update

​Pattern validation

​Link & Health

​Governance

​Share

​Workspaces

​Beyond context: the rest of the workspace

List & Search

Tags: the category registry

Create & Update

Pattern validation

Link & Health

Governance

Share

Workspaces

Beyond context: the rest of the workspace