Data Contract CLI

The datacontract CLI is an open-source command-line tool for working with data contracts. It uses ODCS (Open Data Contract Standard) YAML files to lint the data contract, connect to data sources and execute schema and quality tests, detect breaking changes, and export to different formats. The tool is written in Python. It can be used as a standalone CLI tool, in a CI/CD pipeline, or directly as a Python library.

The Data Contract CLI is fully integrated with Entropy Data: it can fetch contracts from your instance, publish contracts and test results back to it, and resolve shared definitions and semantics from it. For how testing fits into the data contract workflow, see Test a data contract and the Data Contracts concept.

For the complete command reference, see the Data Contract CLI documentation.

Install

Install with uv (recommended). The [all] extra bundles every data source connector:

uv tool install --python python3.11 --upgrade 'datacontract-cli[all]'
datacontract --version

The CLI is also available via pip install 'datacontract-cli[all]', pipx, and as a Docker image (datacontract/cli). To install a single connector instead of [all], use a per-source extra, for example datacontract-cli[snowflake].

API Key

Define your API Key as an environment variable. It must be associated with a user:

export ENTROPY_DATA_API_KEY=xxx

The CLI sends it as the x-api-key header. For backwards compatibility, DATAMESH_MANAGER_API_KEY and DATACONTRACT_MANAGER_API_KEY are also accepted.

Host

Commands that talk to Entropy Data — datacontract publish, publishing test results, and resolving definitions and semantics — need your instance's API host. Set it once:

export ENTROPY_DATA_HOST=https://api.entropy-data.com

The default is https://api.entropy-data.com (Entropy Data Cloud), so you can omit it on Cloud. For a self-hosted instance, set your own API host.

Publish Test Results

Pass a data contract's URL to datacontract test to retrieve and test it. Add the --publish option to upload the results to Entropy Data, where they appear in the contract's Data Quality section.

datacontract test https://<your-entropy-data-web-host>/<org>/datacontracts/<contract-id> \
                    --server <server> \
                    --publish https://<your-entropy-data-api-host>/api/test-results

--publish takes the full URL to post results to — on Entropy Data Cloud that is https://api.entropy-data.com/api/test-results. <server> is the name of a server defined in the contract (for example, snowflake); it is optional — the CLI tests all servers by default. Set the data source's credentials as environment variables too — each contract's How to test section shows the exact command for that contract.

Fetching a contract by its Entropy Data URL uses your ENTROPY_DATA_API_KEY, so private contracts are retrieved authenticated.

Publish a Data Contract

Beyond test results, the CLI can publish the contract itself to Entropy Data — creating or updating it in place (PUT /api/datacontracts/<id>). This is useful in a GitOps pipeline where the contract YAML lives in a repository:

export ENTROPY_DATA_API_KEY=xxx
export ENTROPY_DATA_HOST=https://api.entropy-data.com

datacontract publish datacontract.yaml

The contract's id field determines which contract is written. The command prints a link to open the published contract in Entropy Data.

Resolve Definitions and Semantics

Contracts can reference shared definitions and semantics by IRI instead of repeating them inline. By default, the CLI resolves those references against your configured ENTROPY_DATA_HOST and inlines the fetched content before testing or exporting. Set ENTROPY_DATA_HOST to the instance that hosts the definitions, or pass --no-inline-references to skip resolution.

Run in CI/CD

Use datacontract ci in a pipeline to test one or more contracts and gate the build. It emits JUnit or JSON output and GitHub Actions annotations, and can publish results just like test:

datacontract ci datacontract.yaml \
  --publish https://api.entropy-data.com/api/test-results \
  --output test-results.xml --output-format junit \
  --fail-on error

--fail-on accepts warning, error (the default), or never. See CI/CD for full pipeline examples.

Links

• Data Contract CLI documentation
• Data Contract CLI on GitHub