GitHub - tanmayjoddar/apidrift-cli

                 _     _        _  __  _
  __ _ _ __ (_) __| |_ __(_)/ _|| |_
 / _` | '_ \| |/ _` | '__| | |_ | __|
| (_| | |_) | | (_| | |  | |  _|| |_
 \__,_| .__/|_|\__,_|_|  |_|_|   \__|
      |_|

Catch API schema drift before your users do.

Contributing

Contributions are welcome.

Please read CONTRIBUTING.md before opening issues or pull requests.

If you find this project useful, please ⭐ star the repo — it helps a lot.

The Problem

Your API changed. Nobody noticed. A field was renamed. A type flipped from string to number. A key got removed. Your mobile app crashes. Your integrations break. And you find out at 3am.

[3:14 AM] PagerDuty: checkout is broken in prod
[3:19 AM] Root cause: userId changed string → number in last deploy
[3:21 AM] No test caught it. No alert fired. It was live for 6 hours.

apidrift catches this before it reaches production.

What It Does

apidrift snapshots the shape of your live API responses — not the data, just the structure — and diffs them across versions, environments, or deploys.

# One line. No config. No setup.
apidrift diff https://staging.api.com/users/1 https://prod.api.com/users/1

apidrift diff: staging → prod

✗ GET /users/:id
  ┌──────────┬────────────┬──────────┬──────────┐
  │ Field    │ Change     │ From     │ To       │
  ├──────────┼────────────┼──────────┼──────────┤
  │ userId   │ ● breaking │ "string" │ "number" │
  ├──────────┼────────────┼──────────┼──────────┤
  │ discount │ ● breaking │ "string" │(removed) │
  └──────────┴────────────┴──────────┴──────────┘

Summary: 2 breaking, 0 additive
✗ Breaking changes detected

Install

npm install -g apidrift-cli

Works with any project, any API, any language. No config required to get started.

Commands

`apidrift diff` — The Star Feature

Diff two live URLs instantly. No snapshots, no config.

apidrift diff https://staging.api.com/orders https://prod.api.com/orders

Or diff two saved snapshots by tag:

apidrift diff v1.2 v1.3

Force-compare even if the endpoints differ:

apidrift diff https://api.com/users/1 https://api.com/posts/1 --force

`apidrift init` — Set Up Your Project

cd your-project/
apidrift init

Walks you through setup interactively and creates apidrift.config.json:

{
  "environments": {
    "staging": {
      "baseUrl": "https://staging.yourapi.com",
      "headers": { "Authorization": "Bearer ${STAGING_TOKEN}" }
    },
    "prod": {
      "baseUrl": "https://api.yourapi.com",
      "headers": { "Authorization": "Bearer ${PROD_TOKEN}" }
    }
  },
  "discovery": {
    "openapi": "https://api.yourapi.com/openapi.json"
  },
  "endpoints": []
}

After init, create a .env file (or set env vars) so ${STAGING_TOKEN} / ${PROD_TOKEN} resolve:

STAGING_TOKEN=your_token_here
PROD_TOKEN=your_token_here

Add .env to .gitignore.
If your Authorization header resolves empty (e.g. token missing), apidrift prints a warning before making requests.

`apidrift snapshot` — Save A Schema

Snapshot all your configured endpoints for an environment:

apidrift snapshot --tag v1.0 --env staging

Or snapshot a single URL directly:

apidrift snapshot https://api.yourapi.com/users/1 --tag prod-users

Snapshot only specific methods:

apidrift snapshot --tag v1.0 --env staging --methods GET,POST

Add a delay between requests (polite to APIs):

apidrift snapshot --tag v1.0 --env staging --delay 200

Preview what would be snapshotted without making requests:

apidrift snapshot --tag v1.0 --env staging --dry-run

`apidrift check` — Live Environment Comparison

Hit two environments right now and diff them on the fly:

apidrift check --envA staging --envB prod

Check specific methods only:

apidrift check --envA staging --envB prod --methods GET,POST

Add a delay between checks:

apidrift check --envA staging --envB prod --delay 300

With dry-run to preview which endpoints would be checked:

apidrift check --envA staging --envB prod --dry-run

`apidrift list` — See All Snapshots

apidrift list

Saved snapshots:

  → v1.0
  → v1.1
  → prod-users

`apidrift record` — Snapshot From Traffic

Feed real traffic into apidrift from a HAR file:

apidrift record --har traffic.har --tag nightly

Or pipe it from stdin:

cat traffic.json | apidrift record --stdin --tag ci-run-42

Full Workflow Example

# 1. Set up once
apidrift init

# 2. Snapshot before deploy
apidrift snapshot --tag v1.2 --env staging

# 3. Deploy your changes

# 4. Snapshot after deploy
apidrift snapshot --tag v1.3 --env staging

# 5. See exactly what changed
apidrift diff v1.2 v1.3

CI/CD Integration

apidrift exits with code 1 on breaking changes — a native CI gate.

# .github/workflows/api-check.yml
name: API Contract Check

on: [push]

jobs:
  drift:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - run: npm install -g apidrift-cli
      - run: apidrift check --envA staging --envB prod
        env:
          STAGING_TOKEN: ${{ secrets.STAGING_TOKEN }}
          PROD_TOKEN: ${{ secrets.PROD_TOKEN }}

Breaking change detected → pipeline fails → deploy blocked. Zero extra config.

How It Works

  Your Live API                 What apidrift stores
  ────────────────              ────────────────────
  {                             {
    userId: 123,      ──►         userId: "number",
    name: "John",                 name:   "string",
    tags: ["admin"]               tags:   ["string"]
  }                             }

        snapshot A                     snapshot B
             │                              │
             └──────────┬───────────────────┘
                        ▼
                  differ engine
                        │
             ┌──────────┴──────────┐
             │  breaking           │  additive
             │  type changed       │  new field
             │  field removed      │  (non-breaking)
             └─────────────────────┘

apidrift never stores your actual data — only the shape (field names + types). Safe to use with production APIs.

Change Classification

Change	What It Means	Severity
Field removed	A field consumers depend on is gone	🔴 Breaking
Type changed	`string → number` silently breaks clients	🔴 Breaking
Field added	New undocumented field appeared	🟡 Additive
No change	Schemas match exactly	🟢 Clean

Security

Sensitive fields (token, password, secret, api_key, etc.) are automatically redacted before schema inference
JWT tokens and credit card patterns in values are also redacted
Nothing sensitive is ever written to disk

Snapshot Storage

Snapshots are stored globally at ~/.apidrift/snapshots/ — accessible from any project on your machine.

All Commands Reference

`apidrift init`

Create a starter apidrift.config.json in current directory.

apidrift init [options]

Options:
  -h, --help  display help for command

`apidrift snapshot`

Snapshot all endpoints for an environment or a single URL.

apidrift snapshot [options] [url]

Arguments:
  url                  The URL to snapshot

Options:
  --tag <tag>          Version tag e.g. v1.0
  --env <env>          Environment name e.g. staging
  --methods <methods>  Comma-separated HTTP methods to allow during
                       discovery/fetch (default: GET)
  --dry-run            Print endpoints that would be called (no requests)
  --delay <ms>         Delay in ms between endpoint requests (default: "0")
  -h, --help           display help for command

`apidrift diff`

Diff two snapshots by tag or two URLs.

apidrift diff [options] <from> <to>

Arguments:
  from        Base snapshot tag or URL
  to          Target snapshot tag or URL

Options:
  --force     Force comparison of different endpoints
  -h, --help  display help for command

`apidrift check`

Live diff two environments right now.

apidrift check [options]

Options:
  --envA <envA>        First environment
  --envB <envB>        Second environment
  --methods <methods>  Comma-separated HTTP methods to allow during
                       discovery/fetch (default: GET)
  --dry-run            Print endpoints that would be called (no requests)
  --delay <ms>         Delay in ms between endpoint checks (default: "0")
  -h, --help           display help for command

`apidrift list`

List all saved snapshots.

apidrift list [options]

Options:
  -h, --help  display help for command

`apidrift record`

Create a snapshot from recorded traffic (stdin or HAR).

apidrift record [options]

Options:
  --tag <tag>   Version tag e.g. nightly
  --stdin       Read input from stdin (supports HAR JSON or JSON lines)
  --har <file>  Read a HAR file from disk
  -h, --help    display help for command

Tech Stack

Layer	Package
CLI	commander
HTTP	axios
Terminal UI	chalk + cli-table3 + ora
Schema engine	custom (zero dependencies)
Diff engine	custom recursive differ

License

MIT License — see LICENSE. Built by Tanmay Joddar

Name		Name	Last commit message	Last commit date
Latest commit History 59 Commits
.github		.github
bin		bin
src		src
tests/core		tests/core
.env.example		.env.example
.gitignore		.gitignore
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
apidrift.config.json		apidrift.config.json
package-lock.json		package-lock.json
package.json		package.json

Navigation Menu

Repository files navigation

Contributing

The Problem

What It Does

Install

Commands

`apidrift diff` — The Star Feature

`apidrift init` — Set Up Your Project

`apidrift snapshot` — Save A Schema

`apidrift check` — Live Environment Comparison

`apidrift list` — See All Snapshots

`apidrift record` — Snapshot From Traffic

Full Workflow Example

CI/CD Integration

How It Works

Change Classification

Security

Snapshot Storage

All Commands Reference

`apidrift init`

`apidrift snapshot`

`apidrift diff`

`apidrift check`

`apidrift list`

`apidrift record`

Tech Stack

License

About

Releases

Packages

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

Contributing

The Problem

What It Does

Install

Commands

apidrift diff — The Star Feature

apidrift init — Set Up Your Project

apidrift snapshot — Save A Schema

apidrift check — Live Environment Comparison

apidrift list — See All Snapshots

apidrift record — Snapshot From Traffic

Full Workflow Example

CI/CD Integration

How It Works

Change Classification

Security

Snapshot Storage

All Commands Reference

apidrift init

apidrift snapshot

apidrift diff

apidrift check

apidrift list

apidrift record

Tech Stack

License

About

Resources

Code of conduct

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`apidrift diff` — The Star Feature

`apidrift init` — Set Up Your Project

`apidrift snapshot` — Save A Schema

`apidrift check` — Live Environment Comparison

`apidrift list` — See All Snapshots

`apidrift record` — Snapshot From Traffic

`apidrift init`

`apidrift snapshot`

`apidrift diff`

`apidrift check`

`apidrift list`

`apidrift record`