CLI

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). It is not published to PyPI yet. Once it is, install it with pipx install datanivra-cli. Until then, install the wheels attached to a verified client-package release, or build them from source (tools/release/build_client_packages.py). 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 URL --device --tenant SLUG signs 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 SLUG exchanges 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-stdin reads 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 EMAIL uses the development login. It works only against local or test control planes.
• The CLI stores profiles in profiles.json in your user configuration directory: ~/.config/datanivra on Linux and macOS, %APPDATA%\datanivra on Windows. DATANIVRA_CONFIG_DIR overrides the location. The file is created readable by you only (mode 0600). 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 profiles shows whether a token is stored, never the token itself. datanivra logout revokes the session at the control plane and removes it.

Commands

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": {...}}.

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.

← All documentation