Run and integrate
CLI
Every dogm command and flag, from the CLI's own help.
dogm compiles, generates, validates and masks specs on your machine. It makes no network calls and needs no account, and it's free on every plan. Until the first release, build it from source.
The help text on this page is the CLI's own --help output for engine 0.1.0, captured when the docs are generated.
Deterministic synthetic data: compile, generate and validate DOGM specs
Usage: dogm <COMMAND>
Commands:
compile Check a spec; print its errors, or a plan summary
generate Generate parts, manifest.json and the reports into a directory
mask Mask real data described by a mask spec (source: external tables)
keygen Write a new 32-byte mask key file. Never overwrites a file
validate Re-read a generated directory and check it against the spec
schema Print spec.schema.json
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help
-V, --version Print versionExit codes#
| Code | Meaning |
|---|---|
0 | Success |
1 | The data was written or read, and at least one check failed |
2 | Compile errors in the spec, or a run error the spec caused (such as an overflow) |
3 | Input or I/O errors: a missing file, a bad key file, an unusable flag value |
In CI, 1 means "the data broke a rule" and 2 means "fix the spec".
dogm compile#
Check a spec; print its errors, or a plan summary
Usage: dogm compile [OPTIONS] <SPEC>
Arguments:
<SPEC>
Options:
--json Print JSON instead of text
--seed <SEED> Child row counts depend on the seed; the summary uses 0 unless given [default: 0]
--rows <ROWS> Row override for a root table, `table=count`; repeatable
-h, --help Print helpChecks a spec and prints every error with its path and code, or a summary of the plan: the spec hash, each table's rows, chunks and parent, and the rule count. --json prints the summary or the errors as JSON. A mask spec (one with source: external tables) prints its mask_spec_hash and the mode of each column instead.
dogm generate#
Generate parts, manifest.json and the reports into a directory
Usage: dogm generate [OPTIONS] --seed <SEED> --out <OUT> <SPEC>
Arguments:
<SPEC>
Options:
--seed <SEED> Required, so every run is reproducible from its command line
--rows <ROWS>
--format <FORMAT> csv, jsonl, sql or parquet [default: csv]
--out <OUT>
--workers <WORKERS> Worker threads (default: all cores). Output is identical for any value
--key-file <KEY_FILE> A file of exactly 32 raw bytes (see `dogm keygen`)
--key-version <KEY_VERSION> The key's version, recorded on the run; a new version is a new mapping [default: 1]
--no-mask Write unmasked data from a spec that has a mask block
-h, --help Print helpWrites one file per table per chunk (customers.part-00000.csv), manifest.json, and the checks report as report.json, report.junit.xml and report.sarif, then prints output_sha256. The output is identical for any --workers value. --rows repeats, once per root table: --rows customers=500 --rows products=40.
A spec with a mask block needs --key-file, or --no-mask to write unmasked data on purpose. --format parquet writes customers.part-00000.parquet (zstd, one row group per 131,072 rows), byte-identical for the same inputs like the other formats, and dogm validate reads it back. SQLite output arrives in a later release; in this version, asking for it is an input error that says so.
dogm validate#
Re-read a generated directory and check it against the spec
Usage: dogm validate <SPEC> <DIR>
Arguments:
<SPEC>
<DIR>
Options:
-h, --help Print helpRe-reads a generated directory and checks it against the spec: keys, references, types, nulls, uniqueness and every rule. Use it after data has been copied, loaded or edited.
dogm mask#
Mask real data described by a mask spec (source: external tables)
Usage: dogm mask [OPTIONS] --in <INPUT> --out <OUT> <SPEC>
Arguments:
<SPEC>
Options:
--in <INPUT> Directory with one <table>.csv or <table>.jsonl per table
--out <OUT>
--key-file <KEY_FILE> A file of exactly 32 raw bytes (see `dogm keygen`)
--key-version <KEY_VERSION> The key's version, recorded on the run; a new version is a new mapping [default: 1]
-h, --help Print helpMasks real data described by a mask spec. The masking guide walks through it.
dogm keygen#
Write a new 32-byte mask key file. Never overwrites a file
Usage: dogm keygen --out <OUT>
Options:
--out <OUT>
-h, --help Print helpWrites 32 random bytes from the operating system to a new file and refuses to overwrite one that exists. On Linux and macOS the file is created readable only by you.
dogm schema#
Print spec.schema.json
Usage: dogm schema
Options:
-h, --help Print helpPrints spec.schema.json, the JSON Schema of the spec. Point your editor's YAML plugin at it for completion and inline errors.