datamimic

datamimic [command] [options]datamimic run [descriptor] [--platform-configs json] [--task-id id] [--test-mode]datamimic lint descriptor [-f text|json] [--fail-on error|warning] [--max-diagnostics n]datamimic dry-run descriptor [--max-count n] [--sample-rows n] [--timeout seconds] [--allow-side-effects] [--smoke-export] [-f text|json]datamimic scaffold spec [--format text|json] [--max-count n] [--sample-rows n] [--acceptance-requirements file] [--smoke-export] [--deterministic-replay]datamimic init name [-t dir] [-f]datamimic capabilities [--section names] [--full]datamimic reference topic [name] [--category cat] [--kind kind]datamimic demo list | info name | create [name] [-t dir] [-o] [--all]datamimic info | version

datamimic is the command-line front end for DATAMIMIC Community Edition (CE), a Python engine that generates deterministic synthetic test data and can pseudonymize staging exports. Pipelines are XML descriptors (`<setup>`, `<generate>`, `<variable>`, `<key>`). New models can also be authored as model.dm.json and compiled with scaffold.Install the CE package with pip install datamimic-ce (Python 3.10+). The same wheel exposes datamimic-mcp when the optional mcp extra is installed (`pip install "datamimic-ce[mcp]"`), mapping reference, scaffold, lint, and dry-run to MCP tools.CE targets local, CI, and agent workflows: CSV, JSON, XML, XLSX, DbUnit, fixed-width (.fcw), SQLite, PostgreSQL, MySQL, Oracle, MS SQL, and MongoDB. Domain services cover people, addresses, healthcare, finance, insurance, e-commerce, and public-sector entities. The same seed plus the same model and engine version is specified to replay byte-identical output. Set rngSeed on `<setup>` or a `<variable>` for that contract; omit it for a non-reproducible, privacy-maximized transformation.A typical XML path is lint → dry-run → run. run is the production engine: it changes into the descriptor directory, optionally loads conf/environment.env.properties, and writes real targets. dry-run caps counts and strips targets so a bad model cannot fill a database. scaffold is the agent-oriented path: one compile/lint/bounded-run/acceptance transaction per changed model.dm.json.The Enterprise Platform (EE) is a separate commercial product with a UI, PII scanner, RBAC, scheduler, and a different execution engine. This page documents the open-source datamimic CLI from the CE package.

run [descriptor]

Execute a DATAMIMIC XML descriptor for real. Default path is datamimic.xml. The process chdirs to the descriptor's parent directory for the run, then restores the original cwd.

JSON object of platform configuration values passed into the engine.

Optional task identifier recorded on the run.

Run the engine in test mode.

Check one XML descriptor for schema, semantics, and best-practice rules. Each finding has a rule id (DMxxx) and a fix hint.

Human text (default) or machine-readable JSON. Applies to lint, dry-run, and scaffold. capabilities always prints JSON.

With lint, severity that makes the process exit 1. Default error. warning also fails on warnings.

Cap the number of lint diagnostics (default 200, range 1–200).

Bounded, target-neutralized execution: sample rows without writing real file or database targets unless --allow-side-effects is set.

Per-`<generate>` record cap for dry-run and scaffold (default 10, range 1–1000). Nested generates share the cap.

Sample rows captured per product (default 5, range 1–50).

Dry-run wall-clock limit (default 30, range 1–120).

Keep file/DB targets and allow `<execute>` during a dry-run. Default is neutralized.

Push captured rows through file exporters in a temp directory (no kept artifacts) to catch serialization crashes. Also available on scaffold.

Compile, lint, bounded-run, and accept one model.dm.json intent document. Use - to read the spec from stdin. Stop when the JSON result has verified=true; generated XML is runtime output, not a second source of truth.

Extra JSON array of caller-owned assertions for this scaffold transaction. They are evaluated but not written back into the spec.

With scaffold, run the same seeded bounded model a second time and compare captured rows.

Create a project directory with a starter layout. Name may contain letters, numbers, underscores, and dashes only.

Parent directory for init or demo create. demo create --all requires this.

With init, overwrite an existing project directory.

Print the live DSL surface as JSON. Default is a compact index.

Emit the complete capabilities manifest.

Comma-separated manifest sections (for example elements,rules).

Query model, rule, and authoring reference data. Topics: overview, element, generators, entities, context, timeseries, targets, distributions, converters, rules, scaffold, authoring. authoring uses --category / --kind instead of name.

Authoring-reference listing. Only valid with topic authoring.

Typed fragment within that category (for example weighted, memstore).

List packaged demo projects.

Show one demo's metadata (description, dependencies, usage).

Copy a packaged demo into the working directory (or --target). --all copies every demo and requires --target. -o / --overwrite replaces existing files.

Print version, Python, OS, config path, output directory, and log level.

Print the DATAMIMIC library version.

DATAMIMIC_CONFIG

Config file shown by datamimic info. Unset displays as Default.

Output directory shown by info. Unset means the current directory.

Log level (default INFO).

datamimic.xml

Default descriptor path for datamimic run.

Canonical intent document for datamimic scaffold. Top-level keys are version, seed, products, and expectations.

Optional environment properties loaded from the descriptor's parent directory on run. Missing file is ignored.

0

Success. For scaffold, also requires verified=true. For lint, no diagnostics at or above --fail-on. For dry-run, ok is true.

Failed run, failed or unverified scaffold (after render), lint findings at the chosen threshold, or a usage error such as a missing descriptor or invalid project name.

Hard failure: scaffold render error, or presenter fail() default (bad JSON flags, and similar).

The PyPI distribution is datamimic-ce, not datamimic. A global datamimic on PATH can be an older install; in a checkout use .venv/bin/datamimic.run writes real files and databases. Point source at a controlled export or staging copy, never a live production connection. dry-run without --allow-side-effects is the safe preview.CE identifies PII fields by hand in the XML model. Seeded mode is reproducible (same source row maps to the same synthetic value when distribution="ordered"). Unseeded mode is non-deterministic by design. The project does not claim GDPR anonymization on a whole dataset.CE is a Python multiprocess engine sized for millions of records. Coordinated multi-system runs, Kafka, and billion-record throughput are EE.A `<key name="ts">` or `<variable name="ts">` shadows the time-series namespace (ts.now, ts.step, ts.series). Name the output column something else, for example timestamp.

rapiddweller (Hamburg / Asia) has shipped model-driven test data since Benerator in 2006. DATAMIMIC Community Edition is the Python successor to that XML-descriptor engine. CE was released under the MIT License in December 2024. Version 3.0.0 added first-class time-series `<generate start/end/interval>` loops; 4.0.0 extended setup-level rngSeed to standalone literal generators.

faker(1), fakedata(1), python(1), pip(1)

Source code · Homepage · Documentation