🗺️ DriftMap CLI

API drift detection tool with auto-discovery and baseline generation

DriftMap CLI automatically detects API drift by comparing your live API responses against your OpenAPI specification or auto-discovered baseline.

Installation

npm install -g driftmap

Quick Start

Auto-Discovery Mode (No Spec Required)

driftmap check --url http://localhost:5000

This will:

1. Auto-discover your API endpoints
2. Generate a baseline OpenAPI spec
3. Store it locally for future drift detection

With Existing OpenAPI Spec

driftmap check --spec openapi.yaml --url http://localhost:5000

Features

• Auto-Discovery: Generate OpenAPI spec from live API responses
• Multi-Sample Collection: Collects multiple samples for statistical reliability
• Smart Field Detection: Identifies stable fields, enums, and dynamic fields
• Confidence Tracking: Baseline confidence scores based on sample size
• Drift Detection: Detects type mismatches, undocumented fields, nullability violations
• CI/CD Ready: Exit code 1 when drift is detected
• Local Storage: Baselines stored in .driftmap/ directory

Commands

# Basic scan with auto-discovery
driftmap check --url http://localhost:5000

# Scan with existing spec
driftmap check --spec openapi.yaml --url http://localhost:5000

# With authentication
driftmap check --url http://localhost:5000 --auth-type bearer --auth-token <token>

# JSON output
driftmap check --url http://localhost:5000 --output json

# Show help
driftmap check --help

Options

| Option | Description | Default | |---|---|---| | --spec, -s | Path to OpenAPI spec file | Auto-discovery | | --url, -u | API base URL | http://localhost:4000 | | --auth-type | Authentication type | None | | --auth-token | Authentication token | None | | --output | Output format (table/json) | table | | --sync | Sync results to cloud | false | | --backend | Backend API URL for sync | None | | --api-key | API key for cloud sync | None |

Exit Codes

• 0: No breaking changes detected
• 1: Drift detected (for CI/CD pipelines)

Example Output

▶ Starting scan...
  URL:   http://localhost:5000
  Mode:  Auto-discovery (no OpenAPI spec provided)

▶ Auto-discovering API endpoints...
✓ Created baseline spec at /home/user/.driftmap/baseline-xxx.yaml
  ⚠  First scan - baseline confidence will be low initially

Scan Summary
  ──────────────────────────────────────────────────
  Total Endpoints    1
  Scanned Endpoints  1
  Failed Endpoints   0
  Drift Score        0/100
                     Perfect match with baseline

  ──────────────────────────────────────────────────
  INFO        0  WARNING    0  ERROR       0  CRITICAL    0


Endpoint Findings
  ──────────────────────────────────────────────────
GET  /             200 OK  No drift
  ✓ No drift findings



✓ No breaking changes detected
⚠  Baseline confidence is low (only 3 samples)

How It Works

First Scan (Baseline Creation)

1. Discovers API endpoints
2. Collects 3 samples per endpoint
3. Generates OpenAPI spec with:
   • Field types and examples
   • Enum values with confidence scores
   • Stability labels (stable/enum_candidate/unstable/dynamic)
   • Dynamic field detection (timestamps, UUIDs)
4. Stores baseline in .driftmap/ directory

Subsequent Scans (Drift Detection)

1. Compares live API responses against baseline
2. Detects:
   • Type mismatches
   • Undocumented fields
   • Nullability violations
   • Enum value changes
3. Uses confidence scores to determine severity (low confidence = warning)
4. Returns exit code 1 if breaking changes detected

Baseline Metadata

Generated baselines include:

x-driftmap:
  createdAt: 2026-04-18T18:36:06.136Z
  source: auto-discovery
  sampleSize: 3
  confidence: low
  baseUrl: http://localhost:5000
  baselineVersion: 1

Field-level metadata:

status:
  type: string
  example: healthy
  x-drift-stability: stable
  x-drift-variability: 0.3333333333333333
  x-drift-variability-label: medium
  enum:
    - healthy
  x-drift-confidence: low

CI/CD Integration

# .github/workflows/drift-check.yml
name: API Drift Check

on: [push, pull_request]

jobs:
  drift:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - run: npm install -g driftmap
      - run: driftmap check --url https://staging.yourapi.com

License

MIT © Rushikesh

Built by Rushikesh — DriftMap: Stop API Drift Before It Stops You.

GitHub · npm