> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orca-klavest.app/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> Install and use the ORCA command-line tool to scan, upload, and manage data quality from your terminal.

## Installation

```bash theme={null}
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

```bash theme={null}
export ORCA_API_URL="https://api.orca-klavest.app"
export ORCA_API_KEY="orca_key_abc123..."
```

### Config file

Create `~/.orca/config.toml`:

```toml theme={null}
[api]
url = "https://api.orca-klavest.app"
key = "orca_key_abc123..."
```

## Commands

### `orca scan`

Trigger a data-quality scan on a connected source.

```bash theme={null}
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**

```bash theme={null}
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**

```bash theme={null}
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.

```bash theme={null}
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**

```bash theme={null}
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.

```bash theme={null}
# 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.

```bash theme={null}
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**

```bash theme={null}
orca alerts --severity critical --since 24h
```

### `orca contracts list`

List all data contracts for the current organisation.

```bash theme={null}
orca contracts list [--format table|json]
```

### `orca contracts evaluate`

Evaluate a data contract and display results.

```bash theme={null}
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**

```bash theme={null}
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.

```bash theme={null}
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**

```bash theme={null}
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.