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 statusTo install it globally:
npm install --global @contrastlabs/cli
contrast auth login
contrast doctorcontrast setup signs in, picks a workspace, sets up the warehouse, and installs the MCP server in Claude Code, Codex, or Cursor.
The status, warehouse, source, ingest, catalog and query commands operate the Contrast Warehouse.
| Task | Command |
|---|---|
| Check warehouse readiness | contrast status or contrast warehouse status |
| Wait until the warehouse is ready | contrast status --watch |
| Read usage | contrast warehouse usage --window 30d |
| List source types | contrast source types |
| Connect a source | contrast source connect <kind> |
| Plan and start ingestion | contrast ingest plan <connection-id> --source-kind <kind>, then contrast ingest start <connection-id> --source-kind <kind> |
| Check ingestion | contrast ingest status [ingestion-run-id] |
| Sync, pause or resume | contrast ingest sync|pause|resume <ingestion-run-id> |
| Recopy tables from the source | contrast ingest resync <ingestion-run-id> [--table <table-id>] |
| Delete a sync (warehouse tables are kept) | contrast ingest delete <ingestion-run-id> |
| Search definitions | contrast catalog search "weekly active users" |
| Inspect a table | contrast catalog table <database> <table> |
| Run SQL | contrast query run "SELECT count(*) FROM ember.default.orders" |
| Page results | contrast query results <query-id> --next-token <token> |
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.
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_URLEvery 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.
| Task | Command |
|---|---|
| Set up an MCP client | contrast setup --client <claude|codex|cursor> |
| Ask Contrast a question | contrast ask "Why did weekly signups change?" |
| List connectors | contrast connectors list |
| Inspect impact | contrast lineage impact <relation_ref> --connector <id> |
| Export lineage | contrast lineage export --out lineage.ndjson |
| Inspect schema changes | contrast schema changes list |
| Investigate a table | contrast investigate table <relation_ref> |
For CI, store CONTRAST_API_TOKEN in the CI secret manager and select a workspace through config or --workspace.
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.
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_connectorcontrast_lineage_sourceImports use the stable resource ID. Plans redact secrets, and updates preserve provider identity so a configuration change cannot silently rebind lineage evidence.