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 (local-git drift source, no GitHub App needed) | 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), soBilling 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> |
Share
| 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. Onedriftless 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 |
|---|---|---|
| Projects & cards | project add|list|get|update, project card add|status|move|rm | Projects |
| 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 |
driftless <family> --help for the full flag set.