@driftdev/cli

Command-line interface for documentation coverage analysis and drift detection. Ships as the drift binary.

Who This CLI Is For

• Maintainers of TypeScript libraries, SDKs, and CLI packages.
• Teams that want docs quality enforced in CI.
• Engineers building automation around machine-readable docs diagnostics.

Why Use It

• Catch stale JSDoc, examples, and markdown references before release.
• Enforce quality thresholds with standard exit codes.
• Produce structured output that agents and tooling can act on directly.

Install

bun add -g @driftdev/cli

Quick Start

# Full scan: coverage + lint + prose drift + health
drift scan

# Check documentation coverage
drift coverage

# Find JSDoc accuracy issues
drift lint

# Validate @example blocks
drift examples

Entry auto-detects from package.json (types, exports, main, module, bin) for TypeScript packages with an exported API surface.

Commands

Composed

| Command | Description | |---------|-------------| | drift scan [entry] | Coverage + lint + prose drift + health in one pass | | drift health [entry] | Documentation health score (default command) | | drift ci | CI checks on changed packages with PR comments |

Analysis

| Command | Description | |---------|-------------| | drift coverage [entry] | Documentation coverage score | | drift lint [entry] | Cross-reference JSDoc vs code signatures | | drift examples [entry] | Validate @example blocks (presence, typecheck, run) |

Extraction

| Command | Description | |---------|-------------| | drift extract [entry] | Extract full API spec as JSON | | drift list [entry] | List all exports with kinds | | drift get <name> [entry] | Inspect single export detail + types |

Spec Operations

| Command | Description | |---------|-------------| | drift validate <spec> | Validate a spec file | | drift filter <spec> | Filter exports by kind, search, tag |

Comparison

| Command | Description | |---------|-------------| | drift diff <old> <new> | What changed between two specs | | drift breaking <old> <new> | Detect breaking changes | | drift semver <old> <new> | Recommend semver bump | | drift changelog <old> <new> | Generate changelog |

Setup & Plumbing

| Command | Description | |---------|-------------| | drift init | Create configuration file | | drift config | Manage config (list, get, set) | | drift context | Generate agent context file | | drift report | Documentation trends from history | | drift release | Pre-release documentation audit | | drift cache | Cache management (clear, status) |

Discovery

# Machine-readable list of all commands + flags
drift --tools

Global Options

--json          Force JSON output (default when piped)
--human         Force human-readable output (default in terminal)
--config <path> Path to drift config file
--cwd <dir>     Run as if started in <dir>
--no-cache      Bypass spec cache

scan

Run coverage + lint + prose drift + health in one pass.

drift scan                    # single package
drift scan --min 80           # fail if health below 80%
drift scan --all              # all workspace packages
drift scan --all --private    # include private packages

lint

Cross-reference JSDoc against code signatures. Detects 15 drift types across 4 categories (structural, semantic, example, prose). Prose detection scans markdown files for broken import references.

drift lint                    # single package
drift lint --all              # all workspace packages
drift lint --json             # JSON output with filePath/line

coverage

Documentation coverage score.

drift coverage                # single package
drift coverage --min 80       # fail if below 80%
drift coverage --all          # all workspace packages

health

Weighted health score: completeness (coverage) + accuracy (lint).

drift health                  # default command (bare `drift`)
drift health --min 80
drift health --all

examples

Validate @example blocks.

drift examples                # presence check
drift examples --typecheck    # type-check examples
drift examples --run          # execute examples
drift examples --min 50       # fail if example coverage below 50%

ci

CI checks with GitHub integration: PR comments, step summaries, history tracking.

drift ci                      # check changed packages
drift ci --all                # check all packages
drift ci --private            # include private packages

Generates ~/.drift/projects/<slug>/context.md — machine-readable project state for agents.

Configuration

drift.config.json

{
  "entry": "src/index.ts",
  "coverage": {
    "min": 80,
    "ratchet": true
  },
  "lint": true,
  "docs": {
    "include": ["README.md", "docs/**/*.md"],
    "exclude": ["node_modules/**"]
  }
}

See Configuration docs for all keys and drift config commands.

Output Format

All commands return structured JSON when piped or with --json:

{
  "ok": true,
  "data": { "score": 88, "documented": 243, "total": 275 },
  "meta": { "command": "coverage", "duration": 1234, "version": "0.38.0" }
}

Human-readable output in terminal by default, or with --human.

Monorepo Support

All analysis commands support --all for workspace batch mode:

drift scan --all              # scan all packages
drift coverage --all          # coverage per package
drift lint --all              # lint per package

Auto-detects workspace globs from package.json.

License

MIT