Skip to main content

​
Installation

pip install orca-cli
Requires Python 3.10 or later.

​
Authentication

The CLI resolves credentials in the following order:
  1. Explicit CLI flags (--api-key, --api-url)
  2. Environment variables ORCA_API_KEY and ORCA_API_URL
  3. 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]
OptionDescription
--source-idUUID of the data source to scan (required)
--tableSpecific table name to scan
--waitPoll until the scan completes, then print results
--formatOutput format: table (default) or json
--fail-underExit 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]
OptionDescription
FILEPath to the CSV file (required, positional)
--waitWait for processing to complete, then print results
--formatOutput format: table (default) or json
--fail-underExit 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>
OptionDescription
--file-idUUID of the file whose results to fetch
--formatOutput format: table (default) or json
--fail-underExit code 1 if quality score is below this threshold

​
orca alerts

List recent alerts from ORCA. 
orca alerts [OPTIONS]
OptionDescription
--severityFilter by severity: critical, high, medium, low
--sinceTime window, e.g. 7d, 24h
--limitMax alerts to return (default: 50)
--formatOutput 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]
OptionDescription
CONTRACT_IDUUID of the contract (required, positional)
--fail-underExit code 1 if score below threshold
--formatOutput 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]
OptionDescription
--source-idData source UUID (required)
--tableTable name the results belong to (required)
--resultsJSON array of result items (required)
--metadataOptional JSON object of key-value metadata
--formatOutput 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

SettingEnv variableConfig keyDescription
API URLORCA_API_URL[api] urlBase URL of your ORCA instance
API keyORCA_API_KEY[api] keyAPI key with scan permissions
The CLI uses automatic retry with exponential backoff (up to 3 attempts) for transient network errors and 5xx responses.