CLI

Installation

pip install orca-cli

Requires Python 3.10 or later.

Authentication

The CLI resolves credentials in the following order:

Explicit CLI flags (--api-key, --api-url)
Environment variables ORCA_API_KEY and ORCA_API_URL
Config file at ~/.orca/config.toml

Environment variables

export ORCA_API_URL="https://api.orca-klavest.app"
export ORCA_API_KEY="orca_key_abc123..."

Config file

Create ~/.orca/config.toml:

[api]
url = "https://api.orca-klavest.app"
key = "orca_key_abc123..."

Commands

`orca scan`

Trigger a data-quality scan on a connected source.

orca scan --source-id <UUID> [OPTIONS]

Option	Description
`--source-id`	UUID of the data source to scan (required)
`--table`	Specific table name to scan
`--wait`	Poll until the scan completes, then print results
`--format`	Output format: `table` (default) or `json`
`--fail-under`	Exit code 1 if quality score is below this threshold (for CI)

Example: scan and wait for results

orca scan --source-id a1b2c3d4-5678-9abc-def0-1234567890ab --wait

Quality score: 87

           Column Results
┏━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━┓
┃ Column      ┃ Category    ┃ Confidence ┃ Issues ┃
┡━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━┩
│ email       │ email       │ 0.98       │ 2      │
│ revenue     │ monetary    │ 0.95       │ 0      │
│ signup_date │ datetime    │ 0.97       │ 1      │
└─────────────┴─────────────┴────────────┴────────┘

Example: CI gate

orca scan --source-id $SOURCE_ID --wait --fail-under 80 --format json

Returns exit code 1 if the quality score is below 80.

`orca upload`

Upload a CSV file for data-quality analysis.

orca upload <FILE> [OPTIONS]

Option	Description
`FILE`	Path to the CSV file (required, positional)
`--wait`	Wait for processing to complete, then print results
`--format`	Output format: `table` (default) or `json`
`--fail-under`	Exit code 1 if quality score is below this threshold

Example

orca upload customers.csv --wait

Upload complete.  File ID: f7e8d9c0-1234-5678-9abc-def012345678
Job ID: j1a2b3c4-5678-9abc-def0-1234567890ab

Quality score: 92

          Upload Results
┏━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━┓
┃ Column       ┃ Category      ┃ Confidence ┃ Issues ┃
┡━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━┩
│ customer_id  │ identifier    │ 0.99       │ 0      │
│ full_name    │ person_name   │ 0.96       │ 0      │
│ email        │ email         │ 0.98       │ 1      │
└──────────────┴───────────────┴────────────┴────────┘

`orca results`

Fetch classification and quality results for a file or source.

# By file ID
orca results --file-id <UUID>

# Latest results for a source + table
orca results latest --source-id <UUID> --table <TABLE_NAME>

Option	Description
`--file-id`	UUID of the file whose results to fetch
`--format`	Output format: `table` (default) or `json`
`--fail-under`	Exit code 1 if quality score is below this threshold

`orca alerts`

List recent alerts from ORCA.

orca alerts [OPTIONS]

Option	Description
`--severity`	Filter by severity: `critical`, `high`, `medium`, `low`
`--since`	Time window, e.g. `7d`, `24h`
`--limit`	Max alerts to return (default: 50)
`--format`	Output format: `table` (default) or `json`

Example

orca alerts --severity critical --since 24h

`orca contracts list`

List all data contracts for the current organisation.

orca contracts list [--format table|json]

`orca contracts evaluate`

Evaluate a data contract and display results.

orca contracts evaluate <CONTRACT_ID> [OPTIONS]

Option	Description
`CONTRACT_ID`	UUID of the contract (required, positional)
`--fail-under`	Exit code 1 if score below threshold
`--format`	Output format: `table` (default) or `json`

Example

orca contracts evaluate c9d8e7f6-5432-1abc-def0-9876543210ab

Contract: orders-freshness
Score:    94  PASSED

              Rule Results
┏━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Rule               ┃ Result ┃ Detail                 ┃
┡━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━┩
│ null_rate < 5%     │ pass   │ 1.2% null rate         │
│ no_duplicates      │ pass   │ 0 duplicate rows       │
│ freshness < 24h    │ fail   │ Last update 26h ago    │
└────────────────────┴────────┴────────────────────────┘

`orca ingest`

Push quality results from external tools into ORCA.

orca ingest --source-id <UUID> --table <TABLE> --results '<JSON>' [OPTIONS]

Option	Description
`--source-id`	Data source UUID (required)
`--table`	Table name the results belong to (required)
`--results`	JSON array of result items (required)
`--metadata`	Optional JSON object of key-value metadata
`--format`	Output format: `table` (default) or `json`

Example

orca ingest \
  --source-id a1b2c3d4-5678-9abc-def0-1234567890ab \
  --table orders \
  --results '[{"column":"email","metric":"null_rate","value":0.12}]' \
  --metadata '{"tool":"external_quality_tool","run_id":"run-42"}'

Ingest complete
  Result ID:        res_7f8e9d0c
  Records created:  1
  Alerts triggered: 0

Configuration reference

Setting	Env variable	Config key	Description
API URL	`ORCA_API_URL`	`[api] url`	Base URL of your ORCA instance
API key	`ORCA_API_KEY`	`[api] key`	API key with scan permissions

The CLI uses automatic retry with exponential backoff (up to 3 attempts) for transient network errors and 5xx responses.

Getting started

Features

Administration

Integrations

Security & compliance

Developer Tools

Methodology

Installation

Authentication

Environment variables

Config file

Commands

`orca scan`

`orca upload`

`orca results`

`orca alerts`

`orca contracts list`

`orca contracts evaluate`

`orca ingest`

Configuration reference

​Installation

​Authentication

​Environment variables

​Config file

​Commands

​orca scan

​orca upload

​orca results

​orca alerts

​orca contracts list

​orca contracts evaluate

​orca ingest

​Configuration reference

Installation

Authentication

Environment variables

Config file

Commands

`orca scan`

`orca upload`

`orca results`

`orca alerts`

`orca contracts list`

`orca contracts evaluate`

`orca ingest`

Configuration reference