driftpipev0.9.4docs for Sign in

Usage & flags

NAME

usage - the complete flag surface, with defaults as of 0.9.4

COMMANDS

CommandReadsWritesCan exit 3
checkstream + lockreport on stdoutyes
snapshotstreamlock fileno
explainlockreport on stdoutno
versionnothingone line on stdoutno

There is no default command: running driftpipe with no arguments prints the synopsis and exits 1. That is deliberate, because the two plausible defaults - check and snapshot - differ by whether your lock file survives.

OPTIONS: check

--schema PATH
Lock file to compare against. Default schema.lock. Exits 4 if it is missing, truncated, or written by a newer lock format.
--input PATH
Record stream. Default -, meaning standard input. Gzip is detected from the first two bytes, so .ndjson.gz needs no flag.
--sample N
Stop after N records. Default 5000. --sample 0 reads the whole stream. The first N records are used, not a random sample - see the note on head bias under limitations.
--max-depth N
How deep to descend into nested objects. Default 8. Paths below the limit are counted once as depth_exceeded and not expanded.
--fail-on MODE
Threshold for exit status 3. breaking (default) or any. With any, a single new optional field fails the build.
--ignore PATH
Path pattern to exclude from the comparison. Repeatable. Patterns are matched against the full path, not against single segments; the syntax is below.
--format MODE
text (default), json, or github. The last one emits workflow annotation lines instead of a table and is described in the CI recipes.
--config PATH
Config file. Default .driftpipe.yml if it exists, otherwise defaults only. --config none disables file loading entirely, which is what you want inside a container.
--timeout DUR
Wall clock limit for the whole run. Default 30s. Accepts Go duration strings such as 500ms, 2m. On expiry the exit status is 2, never 0, and the partial report is discarded.
--print-config
Resolve every setting, print it with the source it came from, and exit 0 without reading the stream. Added in 0.9.0; the output format is shown under config.
--quiet
Suppress the header and the summary line. Differences are still printed, and the exit status is unchanged.
--no-color
Never emit escape sequences. Also implied when stdout is not a terminal, or when NO_COLOR is set to any value.

OPTIONS: snapshot

--schema PATH
Lock file to write. Default schema.lock. Refuses to overwrite an existing file unless --force is given, so a snapshot cannot quietly erase the baseline a check was failing against.
--input PATH, --sample N, --max-depth N
As for check. A snapshot taken with a small sample produces a narrow lock, and every later check will report the fields the sample missed as additive.
--force
Overwrite the lock in place. The previous contents are not backed up; that is what version control is for.
--note TEXT
Free-text note stored in the lock. Useful for recording which fixture or date the baseline came from, and printed by explain.

OPTIONS: explain

--schema PATH
Lock file to read. Default schema.lock.
--path PATH
Print only the subtree under this path. Without it the whole tree is printed.
--format MODE
text (default) or json. The JSON form is the lock contents, re-emitted with keys sorted, and is stable enough to diff between releases.

PATH SYNTAX

One syntax is used for --ignore, for --path and in the config file.

PatternMatches
order.totalexactly that path, nothing below it
order.items[]the merged element shape of the array at order.items
order.items[].skua field inside that element shape
meta.*any single segment under meta, not deeper
*.trace_idtrace_id one level under any single top-level key
debug.**debug and everything below it, at any depth

Patterns are matched after the path is built, so ignoring a subtree still costs the work of walking it. Ignoring debug.** saves memory only in the sense that the paths are not retained in the merged shape.

INPUT FORMATS

  • Newline-delimited JSON, one object per line. Blank lines are skipped; a line that is not an object is an input error.
  • A single JSON array of objects, detected when the first non-space byte is [. It is streamed, not loaded whole.
  • Concatenated JSON objects with no separator at all, which some producers emit.
  • Any of the above wrapped in gzip.

Nothing else: no Parquet, no Avro, no CSV, no XML. The reasons and the non-plans are on the limitations page.

ENVIRONMENT

DRIFTPIPE_CONFIG
Overrides the default config path. A --config flag beats it.
NO_COLOR
If set to any value, including the empty string, colour is disabled.
TZ
Only affects the timestamp written into a new lock, which is always stored in UTC regardless.

EXAMPLES

# baseline from yesterday's dump, whole file, with a note
driftpipe snapshot --input dumps/2026-10-15.ndjson.gz --sample 0 \
  --note "orders, nightly dump 2026-10-15"

# check a fixture in a pull request, strict
driftpipe check --input fixtures/orders.ndjson --fail-on any

# from a pipe, ignoring two noisy subtrees
zcat dumps/2026-10-15.ndjson.gz | head -n 20000 \
  | driftpipe check --ignore 'meta.*' --ignore 'debug.**'

# machine-readable report, keep the exit status
driftpipe check --format json --quiet > drift.json; echo "exit $?"