Driftless CLI

Semantic context layer for humans and coding agents.

Driftless starts with topics — durable engineering memory for decisions, gotchas, invariants, and runbooks. Topics are language-agnostic: attach them to files and workflows with explicit paths and glob anchors.

npm install -g @driftless-sh/cli

Quick Start

driftless login --key <api-key>       # Generate one at app.driftless.icu → Settings → API keys

driftless context add onboarding-context \
  --kind reference \
  --what "Shared context map for this repo or workflow." \
  --how "Captures what humans and agents need to know before working here."

driftless context update onboarding-context \
  --gotcha "Guard is global — use @Public() for explicit public routes" \
  --decision "RS256 keys so services verify without shared secret"

driftless context get onboarding-context        # Retrieve a known topic
driftless context get --files "src/path.ts"     # Retrieve topics for files you're about to touch
driftless context get --diff                    # Retrieve topics for local changes before finishing

driftless branches                     # Which branches' pushes count as drift
driftless install-skill                # Write AGENTS.md for Claude Code / Cursor

Dashboard: app.driftless.icu | API: api.driftless.icu/api/v1

Where to get your API key

1. Go to app.driftless.icu → Sign in
2. Navigate to Settings → API keys
3. Click Generate key
4. Copy the key and run: driftless login --key drift_xxx

Or set the env var: export DRIFTLESS_API_KEY=drift_xxx

Commands

driftless login

Authenticate with Driftless Cloud. Generates an API key at app.driftless.icu → Settings → API keys.

driftless login --key drift_xxx

Auth is stored in ~/.driftless/config.json. You can also set DRIFTLESS_API_KEY as an env var instead.

Default API URL: https://api.driftless.icu/api/v1 — no need to specify it unless you're running a self-hosted instance.

driftless context

Manage context topics — the team's shared codebase memory. Each topic captures what a piece of the system is, how it works, where it lives, and why decisions were made.

Output format

All commands output human-readable text by default. Use --json for machine output (agents, CI).

driftless context list                   # Human-readable
driftless context list --json            # For agents
driftless context get auth-boundaries    # Full topic view
driftless context get auth-boundaries --json

Subcommands

| Command | Description | |---------|-------------| | context list | List all context topics | | context get <slug> | Get topic with anchors, relations, and history | | context add <slug> | Create new topic | | context update <slug> | Update topic fields | | context delete <slug> | Delete a topic | | context search <query> | Full-text search across topics | | context sync <slug> | Sync a doc to a topic | | context get --files | Match topics by file path before editing | | context get --diff | Match topics touched by local changes before finishing | | context share <slug> | Public read-only link to a topic |

Governance

A topic is authoritative only if approved. Lifecycle: draft → proposed → reviewed → archived (reviewed is the authoritative state — the read response carries governance.authoritative). Agents propose; humans approve.

| Command | Description | |---------|-------------| | context propose <slug> | Submit a draft for review | | context approve <slug> | Make a topic authoritative (needs a human identity) | | context reject <slug> | Send a proposed topic back to draft | | context archive <slug> | Retire a topic | | context pr <slug> | List topic-PRs (proposed changes) for a topic | | context pr <slug> --open --summary "..." <content flags> | Open a topic-PR (a reviewable content change) | | context pr <slug> --merge <id> | Apply + approve a topic-PR (human) | | context pr <slug> --reject <id> | Close a topic-PR without applying (human) |

Dry run

All write commands support --dry-run to preview changes without writing to Cloud:

driftless context get --files "src/auth/**" --dry-run
driftless context update auth --what "..." --dry-run
driftless context sync auth --doc docs/auth.md --dry-run

Creating topics

A topic can attach to code in two ways:

• --pattern — glob that resolves dynamically (e.g. src/sdk/**). A topic can hold multiple patterns (it can span modules); the dashboard's Link action appends globs without overwriting.
• --where — explicit file path

# Pattern-based (dynamic resolution)
driftless context add "sdk" \
  --pattern "src/sdk/**" \
  --what "Public SDK for Roulettes" \
  --how "HTTP client with auth and retry logic" \
  --decisions "Uses native fetch to avoid axios dependency" \
  --gotchas "Doesn't work with Node < 18" \
  --ownership "@team"

# File-based (explicit)
driftless context add "b2b-guard" \
  --where "src/shared/guards/business-access.guard.ts" \
  --what "Guard that protects B2B endpoints" \
  --how "Verifies org_id in the token"

Appending multiple gotchas at once

--gotcha can be passed multiple times in one call — all values are appended:

driftless context update auth \
  --gotcha "Reset token on org switch" \
  --gotcha "Test tokens never include production claims" \
  --gotcha "Clerk JWTs expire after 1h"

Fields

| Field | Description | |-------|-------------| | --what | What this piece is | | --how | How it works | | --pattern | Glob pattern for dynamic resolution | | --where | Explicit file path (alternative to pattern) | | --decisions | Why it was built this way | | --gotchas | Known traps and edge cases | | --ownership | Who maintains it |

Examples

# List all topics
driftless context list

# Get topic with anchors and relations
driftless context get sdk

# Search topics
driftless context search "auth"
driftless context search "business guard"

# Update a topic
driftless context update sdk --what "SDK v2 with streaming"

# Append a gotcha
driftless context update sdk --gotchas "Reset token on org switch"

# Sync a doc
driftless context sync auth --doc docs/auth.md --files "src/auth/**"

# Delete a topic
driftless context delete old-feature

driftless branches

View or set which branches' pushes count as drift. The repo's default branch (from GitHub) is always tracked automatically — zero config. Add extra branches only if your real integration branch isn't the GitHub default (e.g. you ship from release).

driftless branches                 # show tracked branches
driftless branches add release     # also detect drift from pushes to `release`
driftless branches rm staging

A push to a non-tracked branch is still recorded for audit but does not mark topics stale — so a throwaway feature branch never creates false drift.

driftless context doctor

Audits the context layer itself — answers "can I trust context get?".

driftless context doctor
driftless context doctor --json

Flags: stale (code changed, context not updated), orphaned (repo deleted — hidden from agents), draft (suggested, never confirmed), docs_pending, repo_leak. Exits non-zero on orphaned/repo_leak.

driftless install-skill

Install AGENTS.md into the current repository. This file instructs AI agents to:

1. Retrieve context before coding: driftless context get <feature>
2. Check file coverage before changing code: driftless context get --files "src/path.ts"
3. Add discovered context: driftless context add "name" --what "..."

cd my-repo
driftless install-skill

driftless doctor

Check environment health before using Driftless.

driftless doctor

Verifies: API key, API reachable, git remote, workspace, repo link, AGENTS.md, GitHub App, and topic anchor health.

driftless help

Show help for all commands or a specific command.

driftless help              # All commands
driftless help context      # Context subcommands

# --help also works on any command without hitting the API
driftless context --help

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | DRIFTLESS_API_KEY | API key for authentication | — | | DRIFTLESS_API_URL | API server URL (override only for self-hosting) | https://api.driftless.icu/api/v1 |

Auth Priority

1. DRIFTLESS_API_KEY env var
2. ~/.driftless/config.json (set by driftless login)

Agent Integration

Claude Code

driftless install-skill

This creates AGENTS.md with instructions for Claude Code to use Driftless before and after every task.

Custom Agents

# Retrieve context for the files you're about to touch
driftless context get <slug>
driftless context get --files "src/auth/**"

# After discovering new context
driftless context update <slug> --gotcha "..." --decisions "..."

Use --json flag for machine-readable output that agents can parse.

Architecture

The CLI is bundled with esbuild into a single distributable binary. It calls Driftless Cloud for workspace, topic, relation, PR activity, and sync data. It does not parse your code or upload source files.

driftless context
  ├── CRUD topics via REST API
  ├── Full-text search (Postgres tsvector)
  ├── Typed topic relations
  └── Pattern resolution (glob/path anchors → matching topics)

License

MIT