Driftless CLI

Semantic context layer for humans and coding agents.

Driftless starts with topics — durable engineering memory for decisions, gotchas, invariants, and runbooks. Add repo scanning when your team is ready for code anchors, impact analysis, and coverage tracking.

npm install -g @driftless-sh/cli

Quick Start

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

# Start with topics — no scan required
driftless context add onboarding-context \
  --kind domain-map \
  --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   # Load context before editing
driftless context load --files "src/**"    # Topics + coverage for files you're about to touch

# Optional: enrich with repo scan when your team is ready
# driftless init                         # Scan repo, upload baseline, install skill
# driftless init --suggest               # Also suggest context topics from detected patterns

driftless graph file <path>            # Deterministic blast radius (callers, deps, entrypoints)
driftless branches                     # Which branches' pushes count as drift
driftless install-skill                # Write AGENTS.md for Claude Code / Cursor

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

Where to get your API key

1. Go to 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 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 init

Optional repo enrichment — scans the codebase, uploads structural metadata (not raw source files) to Driftless Cloud, and installs the agent skill. Useful for component discovery, code anchors, graph coverage, impact analysis, and stale context detection. Driftless works without init; you can create and use topics immediately.

Run once per repo from the repo root when your team wants repo-aware features.

Flags

| Flag | Description | |------|-------------| | --suggest | Also suggest context topics from detected patterns. Off by default. | | --src <path> | Monorepo support — scan from a subpath while git root stays at cwd. Example: --src apps/api/src |

# Standard repo
driftless init

# Standard repo with suggested topics
driftless init --suggest

# Monorepo: NestJS app lives at apps/api/src
driftless init --src apps/api/src

# Monorepo with suggested topics
driftless init --src apps/api/src --suggest

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 resolved components + 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 load --files | Topics + graph + coverage + recommended_action for given files |

Dry run

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

driftless context load --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 track components 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 resolved components
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 graph

Deterministic code graph from the scanned components — no LLM. Run before editing a file to know its blast radius.

driftless graph file src/billing/billing.service.ts          # entrypoints, callers, deps, contracts
driftless graph impact --files "src/billing/billing.service.ts"  # what a change can break
driftless graph file <path> --json --depth 4

entrypoints[] carries each route's guards; empty guards and empty global_guards → treat as no auth detected — verify, not "public". --direction consumers|dependencies|both, --depth 1–6 (default 3).

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. Load context before coding: driftless context get <feature>
2. Check file coverage before changing code: driftless context load --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, baseline, AGENTS.md, GitHub App.

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 init --help
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

# Load context for the files you're about to touch
driftless context get <slug>
driftless context load --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. The @driftless/scanner lib (TypeScript Compiler API parser) is bundled inside the CLI at build time. This avoids publishing the scanner as a separate npm package and keeps workspace:* deps internal.

The scanner uses ts.createSourceFile() per file — no global Project, no LanguageService, no OOM risk. ~300ms, ~35MB for 260 files. Detects controllers, endpoints, guards, services, modules, DTOs with fields + validations, and builds a dependency graph from imports.

driftless init (optional repo enrichment)
  ├── Pass 1: Identity (package.json, tsconfig, folder structure)
  ├── Pass 2: AST extraction (TypeScript Compiler API → endpoints, guards, services, DTOs, relations)
  └── Pass 3: Upload to Cloud (baseline + components + relations)

driftless context
  ├── CRUD topics via REST API
  ├── Full-text search (Postgres tsvector)
  └── Pattern resolution (glob → resolved files)

License

MIT