Purpose
The datanivra CLI is a thin client of the REST API for operators and CI/CD pipelines: requesting datasets, checking job status, listing certified versions and managing policies you are permitted to manage.
Installation
The CLI is the Python package datanivra-cli (Python 3.12 or 3.13). Install it from PyPI with pipx install datanivra-cli (or pip install datanivra-cli in a virtual environment). Versions follow Semantic Versioning, and the CLI, the Python SDK and the TypeScript SDK are released together.
Design guarantees
- The CLI talks only to the control-plane API. It does not contain connectors or the engine, so it cannot read your source databases or move rows — this is enforced by an import-boundary test in the repository.
- Credentials come from the environment or your CI secret store; the CLI never prints tokens.
- Output is metadata: ids, states, counts, checksums and evidence references.
Using it in pipelines
A typical pipeline step requests a dataset for an ephemeral environment, waits for the certified version and then runs tests. See TDM in CI/CD for the pattern and the API overview for idempotency keys, which make retries safe.
export DATANIVRA_BASE_URL=https://api.example.test
export DATANIVRA_TOKEN="$DATANIVRA_CI_TOKEN" # from your CI secret store; never printed
datanivra datasets request create request.json --idempotency-key "$CI_PIPELINE_ID" -o json
datanivra jobs wait "$JOB_ID" --timeout 1800 # exit 0 only if the job succeeded
datanivra certify reports --dataset-id "$DATASET_ID" -o json | jq '.items[0].status'The URL must use https://. Plain http:// is accepted only for a loopback address (a local control plane), because the session token would otherwise travel unencrypted; --insecure-http is an explicit opt-in for a trusted private network.
Reusing the pipeline id as the idempotency key means a retried pipeline step returns the original request instead of creating a second one.
Signing in
datanivra login --url https://api.datanivra.com(the default, also--console) works for every account, including email sign-in (CLI 0.2.0 or later;pipx upgrade datanivra-cli). The CLI prints a code such asBCDF-GHJKand a console address; open the address in a browser where you are signed in to DataNivra, check that it shows the same code, tick the confirmation and choose Approve. The CLI finishes on its own. Codes expire after 10 minutes and work once. If the browser was not signed in and you sign in with an email link, open the address the CLI printed again afterwards.datanivra login-codes show CODE/approve CODE --yes/deny CODEdecides another machine's sign-in code from a terminal where you are already signed in (approving signs that CLI in as you).datanivra tokenprints the stored session token for an MCP client or a script (keep it secret). Sessions last 15 minutes; the CLI renews a stored session before a command when it is close to expiry, up to 12 hours after sign-in.datanivra login --url URL --device --tenant SLUGsigns you in with your organisation's identity provider (OpenID Connect device flow). The CLI prints a web address and a short code on standard error; open the address in any browser, enter the code and approve. The CLI then exchanges the identity provider's ID token for a DataNivra session. This needs a control plane with identity-provider sign-in configured.datanivra login --url URL --id-token-stdin --tenant SLUGexchanges an ID token that you already obtained from the identity provider (for example in a CI job with workload identity). The token must be issued for the CLI's client id and be at most 10 minutes old.datanivra login --url URL --token-stdinreads a session token from standard input, so it never appears in your shell history. The CLI checks the token against the API before it stores it.datanivra login --url URL --tenant SLUG --email EMAILuses the development login. It works only against local or test control planes.- The CLI stores profiles in
profiles.jsonin your user configuration directory:~/.config/datanivraon Linux and macOS,%APPDATA%\datanivraon Windows.DATANIVRA_CONFIG_DIRoverrides the location. The file is created readable by you only (mode0600). The CLI refuses to use a profile file that other users can read. - A stored token is only ever sent to the URL it was issued for.
datanivra profilesshows whether a token is stored, never the token itself.datanivra logoutrevokes the session at the control plane and removes it.
Commands
| Command | What it does | |
|---|---|---|
login, logout, renew, whoami, profiles, token, login-codes | manage your session and profiles | |
org get / tenant / update --name, roles list | organisation, tenant and the role catalogue | |
users list / invite / roles USER --role R | users and role assignments | |
agents list / get / revoke --yes | customer agents | |
agents enroll --name N --token-file PATH | issue a one-time enrollment token; it is written to a new owner-only file and never printed | |
sources list / get / schema / create FILE | registered sources (by connection_ref only) and discovered schema metadata | |
discover run SOURCE [--wait], discover findings, discover schema, discover review FINDING --status S --reason-code C | metadata discovery (the work runs on your agent) and finding review | |
policies list / get / versions / create FILE / new-version POLICY FILE | policies and their versions | |
policies submit / approve / deprecate --yes / revoke --yes POLICY VERSION | policy lifecycle (separation of duties is enforced by the control plane) | |
identity suggest --source S --source S [--min-confidence C] | cross-system identity-link suggestions from discovered metadata (never values); suggestions are always proposed | |
identity validate POLICY VERSION | check an identity-graph version against the latest discovery; exits 1 when it is not usable | |
identity plan --root SOURCE:SCHEMA.TABLE [--graph POLICY:VERSION] | explain which tables a subset would reach, through which foreign key or identity link, and why expansion stopped (row estimates only) | |
masking-domains list | the masking-domain registry (built-in and tenant-defined domains, versions, entities) | |
environments list / create FILE | target environments (by target_ref only) | |
datasets list / get / versions / manifest / lineage | datasets, manifests (counts and checksums) and lineage | |
datasets provision DATASET VERSION --environment-id E [--wait], datasets rollback DATASET --to-version N, datasets revoke DATASET --yes | provisioning lifecycle; the work runs on your agent | |
datasets request create FILE / list / get / cancel | dataset requests | |
jobs list / get / steps / events / cancel / wait | job tracking | |
certify reports / report / evidence | certification reports, gate outcomes and evidence references | |
| `certificates list / get / status / download ID [--format json\ | html] [--out FILE] / keys` | signed test-data certificates (DataNivra-certified against configured policy gates — not a regulatory or third-party certification), their current signed status, the evidence package or a printable report, and the published verification keys |
certificates verify FILE [--keys KEYS.json] [--online] [--require-state ISSUED] | verify a certificate or package offline; exit 0 only when the signatures, status and state verify (exit codes 10–18 name the failure) | |
refresh start DATASET --reason-code CODE [--wait], refresh history, refresh calendar | dataset refresh | |
audit list / verify / export [--since T] [--until T] [--out FILE] | tamper-evident audit trail and the auditor's evidence export (exit 1 when the chain does not verify) | |
capacity estimate / plan | capacity and cost estimates computed by the control plane | |
packs list / enable / disable --yes | industry packs | |
billing entitlement / usage / subscription / checkout --plan P / cancel --yes | plan, entitlements and usage |
Every user operation of the v1 API has a command; packages/cli/tests/test_cli_coverage.py fails when a new operation is added without one.
List commands accept --limit, --cursor and --all, plus every filter the API documents (for example jobs list --state FAILED --kind REFRESH).
Output and exit codes
The default output is a human-readable table. With -o json (or DATANIVRA_OUTPUT=json) the CLI prints stable JSON: one object for a single resource, or {"items": [...], "next_cursor": ...} for a list. Keys are sorted. Errors go to standard error as {"error": {...}}.
| Exit code | Meaning |
|---|---|
| 0 | success |
| 1 | API error, the job you waited for did not succeed, or identity validate found conflicts |
| 2 | usage or configuration error |
| 3 | not signed in, or the session has expired |
| 4 | network error |
| 5 | output refused by the privacy guard, or a response the CLI could not read |
| 10–18 | certificates verify only: malformed input (10), untrusted key (11), invalid signature (12), status about something else (13), state not accepted (14), manifest mismatch (15), status missing or stale (16), no trusted keys given (17), key substituted (18) |
Before anything is printed, a privacy guard checks every value against the contract's data classes. Anything that is not classified as allowed control-plane metadata is refused, and the CLI exits with code 5.