> ## Documentation Index > Fetch the complete documentation index at: https://docs.driftless.icu/llms.txt > Use this file to discover all available pages before exploring further. # Context Commands > Create, read, update, and delete context topics from the CLI. ## List & Search | Command | Flags | Description | Example | | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | | `context list` | `--stale`, `--suggested`, `--status`, `--repo`, `--tag `, `--docs`, `--auto`, `--manual`, `--limit `, `--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 ` | `--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 `, `--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 `, `--offset `, `--json` | List the registry with per-tag topic counts (paginated, most-used first) | `driftless tags` | | `tags add ` | `--description "..."` | Pre-create a tag (idempotent: re-adding merges the description) | `driftless tags add billing --description "Billing rules"` | | `tags rename ` | none | Rename everywhere, rewriting every topic carrying the tag (owner/admin) | `driftless tags rename billing facturacion` | | `tags rm ` | 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 `, `--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](/concepts/governance). | Command | Description | Example | | ---------------------------------- | ---------------------------------------------------- | ---------------------------------------------------------------------------- | | `context propose ` | Put a Note up for review | `driftless context propose payment-flow` | | `context approve ` | Add it to knowledge (owner/admin; only when asked) | `driftless context approve payment-flow` | | `context reject ` | Send it back to a Note | `driftless context reject payment-flow` | | `context archive ` | Retire a topic | `driftless context archive payment-flow` | | `context pr ` | List Suggested edits | `driftless context pr payment-flow` | | `context pr --open` | Open a Suggested edit (`--summary` + content flags) | `driftless context pr payment-flow --open --summary "..." --content @new.md` | | `context pr --merge ` | Merge a Suggested edit (owner/admin) | `driftless context pr payment-flow --merge ` | | `context pr --reject ` | Close a Suggested edit without merging (owner/admin) | `driftless context pr payment-flow --reject ` | ## Share | Command | Description | Example | | ----------------------- | ---------------------------------------------- | -------------------------------------- | | `context share ` | 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](/concepts/workspaces#scoped-credentials). | Command | Description | Example | | ---------------------------------- | ----------------------------------------- | -------------------------------------------------------- | | `workspace list` | The workspaces you belong to (● = active) | `driftless workspace list` | | `workspace current` | The active workspace | `driftless workspace current` | | `workspace switch ` | Operate on another one (no re-login) | `driftless workspace switch acme-platform` | | `workspace add --key ` | Register a workspace by its API key | `driftless workspace add --key drift_…` | | `context move --to ` | 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](/concepts/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](/concepts/projects) | | **Areas** | `area list\|add\|rename\|rm`, plus `context add/update --area` | [Areas](/concepts/areas) | | **Notes & sharing** | `note add`, share via the API / dashboard inbox | [Notes & Sharing](/concepts/notes-sharing) | | **Members** | `member list\|invite\|role\|rm\|invites` | [Workspaces](/concepts/workspaces#invitations) | Run `driftless --help` for the full flag set.