shiftgraph

The ShiftGraph CLI. Capture how the third-party APIs your code calls actually respond, then fail a build when one of them changes its contract underneath you.

The problem it addresses: a provider changes a response shape, keeps returning 200, and their status page stays green. Your integration breaks anyway, and your own dashboards say everything is fine. Background reading: shiftgraph.dev/learn.

Install

npm install -g shiftgraph

Node 22 or later. Zero dependencies.

Use

shiftgraph login                                   # device flow; approve in the browser
shiftgraph capture -o capture.ndjson -- npm test   # run anything; the SDK records
shiftgraph gate -f capture.ndjson --repo owner/name

capture runs your command with SHIFTGRAPH_CAPTURE_FILE set. The @shiftgraph/node recorder inside your process writes one value-free NDJSON event per outbound call: field names, types, and shape, with every value already reduced to a placeholder of the same type. The CLI never opens your payloads because they never exist in the first place.

gate submits that capture and prints the verdict.

| Exit | Meaning | | ---- | ------- | | 0 | pass. No breaking change against your baselines. | | 1 | warn. Changes found, warn-only mode or non-breaking severity. | | 2 | fail. A breaking change, or the command could not run. |

In CI

- run: npm install -g shiftgraph
- run: shiftgraph capture -o capture.ndjson -- npm test
- run: shiftgraph gate -f capture.ndjson --repo ${{ github.repository }} --head-sha ${{ github.sha }}
  env:
    SHIFTGRAPH_TOKEN: ${{ secrets.SHIFTGRAPH_TOKEN }}

A red check on the pull request beats a page at 2am.

Commands

login      sign in from this terminal (device flow)
           [--api url] [--scopes a,b,c]
whoami     show the stored identity (local state, no network call)
capture    shiftgraph capture -o out.ndjson -- <command...>
gate       shiftgraph gate -f capture.ndjson [--org s] [--project s] [--repo o/n]
           [--pr-number n] [--pr-url url] [--branch b] [--head-sha sha] [--json]
version    print the version of this CLI

--json makes gate print the run as a JSON document and nothing else, so it can be piped. Everything the CLI says about itself goes to stderr; stdout carries only the answer, and under capture stdout belongs to your command.

SHIFTGRAPH_API overrides the API base. It must be https, because every request carries your token; http is accepted only on localhost. The token lands in ~/.shiftgraph/config.json with 0600 permissions.

If capture's command is killed rather than exiting - a job timeout, an OOM-kill, a cancelled workflow - capture exits 128 + signal and says the capture is incomplete. Do not submit that capture: a gate cannot tell a truncated run from a complete one.

Where the comparison happens

Server-side. This client authenticates, captures, submits, and reports; it carries no detection engine. That is why it installs in seconds with nothing behind it, and why the verdict comes with a link to the evidence rather than a local guess.

License

MIT.