Skip to main content

Install

npm install -g @driftless-sh/cli

Authenticate

Run driftless login to open your browser to the Driftless dashboard, where you can copy your API key:
driftless login
For non-interactive environments (e.g., CI), pass the key directly:
driftless login --key drift_xxxxxxxxxxxxxxxxx

Install the agent skill

Install Driftless context instructions so coding agents automatically retrieve topics before editing:
driftless install-skill
This writes AGENTS.md and CLAUDE.md into your repo. Agents will see topic retrieval instructions every session.

Create your first topic

Driftless starts with topics: durable engineering memory anchored to the files and workflows where it matters.
# First topic = something REAL you already know, anchored to the module it governs:
driftless context add api-auth --title "Auth" \
  --what "Every API request is workspace-scoped by a global guard." \
  --pattern "src/auth/**"
Nothing concrete to record yet? Skip it. Work first and persist what you learn. A generic placeholder topic documents nothing and rots on day one. Enrich with structured context:
driftless context update api-auth \
  --gotcha "WorkspaceGuard is global, use @Public() only for explicit public routes" \
  --decision "RS256 keys so services verify without shared secret" \
  --invariant "All routes require auth unless explicitly marked @Public()" \
  --check "Verify role decorator matches the guard's expected metadata"
Connect topics with typed relations:
driftless context update api-auth --rel relates_to:api-architecture
driftless context get api-auth --json
Anchor to file paths for drift tracking:
driftless context update api-auth \
  --add-pattern "src/auth/guards/**"
The CLI validates each pattern against your local checkout at write time. A pattern that matches zero files is blocked; one that matches over 100 files gets an over-broad warning.
Set DRIFTLESS_API_KEY for non-interactive environments. Set DRIFTLESS_API_URL only when targeting staging or a local API.

Config File

The CLI stores its state in ~/.driftless/config.json:
{
  "api_key": "drift_xxxxxxxxxxxxxxxxx",
  "api_url": "https://api.driftless.icu/api/v1",
  "workspace_slug": "acme-corp",
  "workspace_id": "ws_abc123"
}

Command reference

CommandFlagsDescriptionExample
login--key <key>Authenticate with API keydriftless login --key drift_xxx
doctor--json8 health checksdriftless doctor
install-skillnoneInstall AGENTS.md + CLAUDE.mddriftless install-skill

Global flags

FlagDescription
--version / -vPrint version
--help / -hFull help
<cmd> --helpCommand-specific help
VariableDescription
DRIFTLESS_API_KEYAPI key (wins over config file)
DRIFTLESS_API_URLAPI server URL (default: https://api.driftless.icu/api/v1)