Usage & flags
NAME
usage - the complete flag surface, with defaults as of 0.9.4
COMMANDS
| Command | Reads | Writes | Can exit 3 |
|---|---|---|---|
| check | stream + lock | report on stdout | yes |
| snapshot | stream | lock file | no |
| explain | lock | report on stdout | no |
| version | nothing | one line on stdout | no |
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.gzneeds no flag. - --sample N
- Stop after N records. Default 5000.
--sample 0reads 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_exceededand not expanded. - --fail-on MODE
- Threshold for exit status 3.
breaking(default) orany. Withany, 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, orgithub. The last one emits workflow annotation lines instead of a table and is described in the CI recipes.- --config PATH
- Config file. Default
.driftpipe.ymlif it exists, otherwise defaults only.--config nonedisables 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_COLORis set to any value.
OPTIONS: snapshot
- --schema PATH
- Lock file to write. Default
schema.lock. Refuses to overwrite an existing file unless--forceis 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) orjson. 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.
| Pattern | Matches |
|---|---|
| order.total | exactly that path, nothing below it |
| order.items[] | the merged element shape of the array at order.items |
| order.items[].sku | a field inside that element shape |
| meta.* | any single segment under meta, not deeper |
| *.trace_id | trace_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
--configflag 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 notedriftpipe snapshot --input dumps/2026-10-15.ndjson.gz --sample 0 \ --note "orders, nightly dump 2026-10-15"# check a fixture in a pull request, strictdriftpipe check --input fixtures/orders.ndjson --fail-on any# from a pipe, ignoring two noisy subtreeszcat dumps/2026-10-15.ndjson.gz | head -n 20000 \ | driftpipe check --ignore 'meta.*' --ignore 'debug.**'# machine-readable report, keep the exit statusdriftpipe check --format json --quiet > drift.json; echo "exit $?"