Contrast CLI and Terraform

Set up agents, operate the warehouse and run read-only SQL with the contrast CLI, and manage configuration as code.

Contrast publishes one command-line tool on npm, @contrastlabs/cli, which installs the contrast command. It signs in through the browser, requires Node.js 20 or later, and you can run it without installing:

npx @contrastlabs/cli auth login
npx @contrastlabs/cli setup
npx @contrastlabs/cli status

To install it globally:

npm install --global @contrastlabs/cli
contrast auth login
contrast doctor

contrast setup signs in, picks a workspace, sets up the warehouse, and installs the MCP server in Claude Code, Codex, or Cursor.

Warehouse CLI

The status, warehouse, source, ingest, catalog and query commands operate the Contrast Warehouse.

TaskCommand
Check warehouse readinesscontrast status or contrast warehouse status
Wait until the warehouse is readycontrast status --watch
Read usagecontrast warehouse usage --window 30d
List source typescontrast source types
Connect a sourcecontrast source connect <kind>
Plan and start ingestioncontrast ingest plan <connection-id> --source-kind <kind>, then contrast ingest start <connection-id> --source-kind <kind>
Check ingestioncontrast ingest status [ingestion-run-id]
Sync, pause or resumecontrast ingest sync|pause|resume <ingestion-run-id>
Recopy tables from the sourcecontrast ingest resync <ingestion-run-id> [--table <table-id>]
Delete a sync (warehouse tables are kept)contrast ingest delete <ingestion-run-id>
Search definitionscontrast catalog search "weekly active users"
Inspect a tablecontrast catalog table <database> <table>
Run SQLcontrast query run "SELECT count(*) FROM ember.default.orders"
Page resultscontrast query results <query-id> --next-token <token>

Run SQL

contrast query run accepts SELECT, SHOW, and DESCRIBE; writes are rejected by the server. Use fully qualified database.schema.table names, or pass --database to set the default database (ember when it exists, otherwise the workspace's only database). When the query finishes, the command returns the first page of rows. Otherwise it returns a query ID; check it with contrast query status <query-id> and fetch rows with contrast query results <query-id>, up to 100 rows per page. Fetching another page doesn't run the query again. Cancel with contrast query cancel <query-id>.

To change data, use SQL in Contrast or dbt. See the SQL reference for the dialect and naming rules.

Credentials and output

Source secrets are never command arguments. OAuth sources return a browser link and the command waits for authorization. Postgres and Supabase sources can read a connection string from an environment variable or stdin:

contrast source connect postgres --credential-env DATABASE_URL

Every command accepts --json for one JSON document on stdout, --workspace <id> (or CONTRAST_WORKSPACE_ID), and --quiet. Exit codes are stable: 2 usage, 3 auth, 4 workspace, 5 validation, 6 API 4xx, 7 API 5xx, 40 watch timeout, 130 cancelled.

Agents and investigation

TaskCommand
Set up an MCP clientcontrast setup --client <claude|codex|cursor>
Ask Contrast a questioncontrast ask "Why did weekly signups change?"
List connectorscontrast connectors list
Inspect impactcontrast lineage impact <relation_ref> --connector <id>
Export lineagecontrast lineage export --out lineage.ndjson
Inspect schema changescontrast schema changes list
Investigate a tablecontrast investigate table <relation_ref>

For CI, store CONTRAST_API_TOKEN in the CI secret manager and select a workspace through config or --workspace.

MCP over stdio

contrast mcp serve bridges stdio to the MCP endpoint at https://contrastdb.com/api/mcp with your saved sign-in, for clients without remote OAuth. It serves the tools the endpoint serves.

Terraform provider

Configure the provider with api_url and a token supplied through CONTRAST_API_TOKEN:

terraform {
  required_providers {
    contrast = {
      source = "contrast/contrast"
    }
  }
}

provider "contrast" {
  workspace_id = var.contrast_workspace_id
}

The provider manages:

  • contrast_connector
  • contrast_lineage_source

Imports use the stable resource ID. Plans redact secrets, and updates preserve provider identity so a configuration change cannot silently rebind lineage evidence.