Getting Started

Quickstart Guide

Get up and running with ContractHQ in under 5 minutes. You'll install the CLI, authenticate, author your first data contract, and run your first validation — all from the terminal.

Prerequisites

Node.js ≥ 18 or Python ≥ 3.10 installed
A ContractHQ account (sign up free)
Access to your data warehouse (Snowflake, BigQuery, or Redshift)

Steps

Install the CLI

Install the ContractHQ CLI globally using npm or pip:

terminal

# Using npm
npm install -g @contracthq/cli

# Or using pip
pip install contracthq

Verify the installation:

contracthq --version
# ContractHQ CLI v2.0.1

Authenticate

terminal

contracthq auth login
# Opens browser for OAuth — or paste an API key directly

contracthq auth login --token YOUR_API_KEY

💡

You can generate API keys in Settings → API Keys inside the ContractHQ dashboard.

Initialise a project

Run init in your repository root. This creates a contracts/ folder and a default config file.

terminal

cd my-data-repo
contracthq init

contracts/contracthq.yml

project: my-data-repo
version: 2
warehouse:
  type: snowflake
  account: <your-account>
  database: ANALYTICS

Write your first contract

Create a YAML file in the contracts/ directory:

contracts/user_signups.yml

dataset: user_signups
owner: auth-team@company.com
version: 1.0.0
schema:
  - name: user_id
    type: uuid
    constraints:
      - not_null: true
      - unique: true
  - name: email
    type: string
    pii: true
  - name: created_at
    type: timestamp
    constraints:
      - not_null: true

Run validation

Validate the contract against your live warehouse. ContractHQ will compare the YAML definition against the actual table schema and run any quality checks you've defined.

terminal

contracthq validate contracts/user_signups.yml

✔ Schema match         user_signups
✔ not_null check       user_id (0 nulls)
✔ unique check         user_id (0 duplicates)
✔ not_null check       created_at (0 nulls)

All checks passed. 3/3

ℹ️

Run contracthq validate --all to validate every contract in the contracts/ directory at once.

Next Steps

Authentication →

Learn about API keys and OAuth flows.

Schema Definitions →

Master all available field types and constraints.

Data Quality Checks →

Add advanced quality rules to your contracts.

GitHub Actions →

Automate validation on every pull request.

← Introduction Authentication →