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

# CLI Reference

> Complete command reference for the armor CLI

<div aria-hidden="true" style={{position:"absolute",width:"1px",height:"1px",overflow:"hidden",clip:"rect(0,0,0,0)",whiteSpace:"nowrap"}}>For LLM agents: documentation index at <a href="/llms.txt" tabIndex={-1}>/llms.txt</a>, full text at <a href="/llms-full.txt" tabIndex={-1}>/llms-full.txt</a>. Append .md to any page URL for plain markdown.</div>

Complete reference for all `armor` CLI commands.

## Exit Codes

| Code | Meaning                |
| ---- | ---------------------- |
| `0`  | Success                |
| `1`  | Staleness/check failed |
| `2`  | Authentication error   |
| `3`  | Resource not found     |
| `4`  | Rate limited           |
| `5`  | General error          |

***

## armor auth

Authentication commands.

### armor auth login

Authenticate with AnomalyArmor.

```bash theme={null}
armor auth login --api-key <key>
armor auth login  # Interactive prompt
```

| Option          | Description                           |
| --------------- | ------------------------------------- |
| `--api-key, -k` | Your API key (starts with `aa_live_`) |
| `--api-url`     | Custom API URL (optional)             |

**Example:**

```bash theme={null}
$ armor auth login
Enter your API key: ********
Successfully authenticated!
Config saved to: ~/.armor/config.yaml
```

### armor auth status

Check authentication status.

```bash theme={null}
armor auth status
```

**Example:**

```bash theme={null}
$ armor auth status
Authenticated
API Key: aa_live_abc1...xy9z
API URL: https://api.anomalyarmor.ai
```

### armor auth logout

Remove stored credentials.

```bash theme={null}
armor auth logout
```

***

## armor assets

Asset management commands.

### armor assets list

List assets with optional filters.

```bash theme={null}
armor assets list [OPTIONS]
```

| Option         | Description                                             |
| -------------- | ------------------------------------------------------- |
| `--source, -s` | Filter by source type (e.g., `snowflake`, `postgresql`) |
| `--type, -t`   | Filter by asset type (e.g., `table`, `view`)            |
| `--search`     | Search in asset names                                   |
| `--limit, -l`  | Max results (default: 50)                               |

**Example:**

```bash theme={null}
$ armor assets list --source snowflake --type table

                           Assets
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━┓
┃ Qualified Name                    ┃ Type  ┃ Source    ┃ Active ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━┩
│ snowflake.prod.warehouse.orders   │ table │ snowflake │ Yes    │
│ snowflake.prod.warehouse.users    │ table │ snowflake │ Yes    │
└───────────────────────────────────┴───────┴───────────┴────────┘

Showing 2 assets
```

### armor assets get

Get asset details.

```bash theme={null}
armor assets get <asset_id>
```

| Argument   | Description                |
| ---------- | -------------------------- |
| `asset_id` | Asset ID or qualified name |

**Example:**

```bash theme={null}
$ armor assets get snowflake.prod.warehouse.orders

Asset: snowflake.prod.warehouse.orders
ID: 550e8400-e29b-41d4-a716-446655440000
Type: table
Source: snowflake
Active: Yes
Description: Customer order transactions
```

***

## armor freshness

Freshness monitoring commands.

### armor freshness summary

Get freshness summary.

```bash theme={null}
armor freshness summary
```

**Example:**

```bash theme={null}
$ armor freshness summary

Freshness Summary
Total Assets: 245
Fresh: 230
Stale: 10
Unknown: 5
Freshness Rate: 93.9%
```

### armor freshness list

List freshness status for all assets.

```bash theme={null}
armor freshness list [OPTIONS]
```

| Option         | Description                                    |
| -------------- | ---------------------------------------------- |
| `--status, -s` | Filter by status (`fresh`, `stale`, `unknown`) |
| `--limit, -l`  | Max results (default: 50)                      |

**Example:**

```bash theme={null}
$ armor freshness list --status stale

                      Freshness Status
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━┓
┃ Asset                             ┃ Status ┃ Hours Since Update┃ Threshold ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━┩
│ snowflake.prod.warehouse.orders   │ Stale  │ 26.5              │ 24h       │
└───────────────────────────────────┴────────┴───────────────────┴───────────┘
```

### armor freshness get

Check freshness for a specific asset.

```bash theme={null}
armor freshness get <asset_id>
```

**Example:**

```bash theme={null}
$ armor freshness get snowflake.prod.warehouse.orders

Asset: snowflake.prod.warehouse.orders
Status: Fresh
Last Update: 2024-12-04T10:30:00Z
Hours Since Update: 2.5
Threshold: 24h
```

### armor freshness check

Check if an asset is fresh, fail if stale. **Ideal for CI/CD pipelines.**

```bash theme={null}
armor freshness check <asset_id> [OPTIONS]
```

| Option          | Description                            |
| --------------- | -------------------------------------- |
| `--max-age, -m` | Max acceptable age in hours (optional) |

**Exit codes:**

* `0` - Data is fresh
* `1` - Data is stale
* `3` - Asset not found

**Example (fresh):**

```bash theme={null}
$ armor freshness check snowflake.prod.warehouse.orders
FRESH: snowflake.prod.warehouse.orders
Hours since update: 2.5h
$ echo $?
0
```

**Example (stale):**

```bash theme={null}
$ armor freshness check snowflake.prod.warehouse.orders
STALE: Asset 'snowflake.prod.warehouse.orders' is stale: 26.5h since last update (threshold: 24.0h)
Hours since update: 26.5h
Threshold: 24.0h
$ echo $?
1
```

**Shell script usage:**

```bash theme={null}
#!/bin/bash
if armor freshness check snowflake.prod.warehouse.orders; then
    echo "Data is fresh, running pipeline..."
    dbt run
else
    echo "Data is stale, aborting"
    exit 1
fi
```

### armor freshness refresh

Trigger a freshness check for an asset.

```bash theme={null}
armor freshness refresh <asset_id>
```

<Note>
  Requires an API key with `read-write` or `admin` scope.
</Note>

**Example:**

```bash theme={null}
$ armor freshness refresh snowflake.prod.warehouse.orders

Refresh initiated
Job ID: job_abc123
Status: queued
```

***

## armor schema

Schema drift monitoring commands.

### armor schema summary

Get schema changes summary.

```bash theme={null}
armor schema summary
```

**Example:**

```bash theme={null}
$ armor schema summary

Schema Changes Summary
Total Changes: 23
Unacknowledged: 5
Critical: 2
Warning: 8
Info: 13
```

### armor schema changes

List schema changes.

```bash theme={null}
armor schema changes [OPTIONS]
```

| Option                 | Description                                                                    |
| ---------------------- | ------------------------------------------------------------------------------ |
| `--asset, -a`          | Filter by asset                                                                |
| `--type, -t`           | Filter by change type (`column_added`, `column_removed`, `type_changed`, etc.) |
| `--breaking`           | Only show breaking changes (removed columns/tables, type changes)              |
| `--unacknowledged, -u` | Only show unacknowledged changes                                               |
| `--limit, -l`          | Max results (default: 50)                                                      |

**Example:**

```bash theme={null}
$ armor schema changes --breaking

                           Schema Changes
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━┓
┃ Asset                           ┃ Change         ┃ Column    ┃ Ack ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━┩
│ snowflake.prod.warehouse.orders │ column_removed │ user_id   │ No  │
└─────────────────────────────────┴────────────────┴───────────┴─────┘
```

***

## armor alerts

Alert management commands.

### armor alerts summary

Get alerts summary.

```bash theme={null}
armor alerts summary
```

**Example:**

```bash theme={null}
$ armor alerts summary

Alerts Summary
Total Rules: 15
Active Rules: 12
Recent Alerts: 45
Unresolved: 3
```

### armor alerts list

List alerts with filters.

```bash theme={null}
armor alerts list [OPTIONS]
```

| Option         | Description                                                |
| -------------- | ---------------------------------------------------------- |
| `--status, -s` | Filter by status (`triggered`, `acknowledged`, `resolved`) |
| `--type, -t`   | Filter by alert type (`schema`, `freshness`, `discovery`)  |
| `--limit, -l`  | Max results (default: 50)                                  |

**Example:**

```bash theme={null}
$ armor alerts list --status triggered

                              Alerts
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━┓
┃ Asset                           ┃ Message               ┃ Type      ┃ Status    ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━┩
│ snowflake.prod.warehouse.orders │ Data is 26 hours stale│ freshness │ Triggered │
└─────────────────────────────────┴───────────────────────┴───────────┴───────────┘
```

***

## armor api-keys

API key management commands. Requires `admin` scope.

### armor api-keys list

List API keys.

```bash theme={null}
armor api-keys list [OPTIONS]
```

| Option              | Description          |
| ------------------- | -------------------- |
| `--include-revoked` | Include revoked keys |

**Example:**

```bash theme={null}
$ armor api-keys list

                           API Keys
┏━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━┓
┃ Name               ┃ Key              ┃ Scope      ┃ Active ┃ Last Used  ┃
┡━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━┩
│ Airflow Production │ aa_live_abc...z4 │ read-only  │ Yes    │ 2024-12-04 │
│ CI Pipeline        │ aa_live_def...y8 │ read-write │ Yes    │ 2024-12-03 │
└────────────────────┴──────────────────┴────────────┴────────┴────────────┘
```

### armor api-keys create

Create a new API key.

```bash theme={null}
armor api-keys create --name <name> [OPTIONS]
```

| Option        | Description                             |
| ------------- | --------------------------------------- |
| `--name, -n`  | Human-readable name for the key         |
| `--scope, -s` | Permission scope (default: `read-only`) |

**Scopes:**

* `read-only` - Read assets, freshness, lineage, alerts
* `read-write` - Read + trigger refreshes
* `admin` - Full access including key management

**Example:**

```bash theme={null}
$ armor api-keys create --name "Airflow Production" --scope read-only

API key created successfully!

Key: aa_live_k8jd92hf8j2hd98fh2d9h2f98h2d9fh2

IMPORTANT: This key will only be shown once!
Store it securely.
```

### armor api-keys revoke

Revoke an API key.

```bash theme={null}
armor api-keys revoke <key_id> [OPTIONS]
```

| Option      | Description              |
| ----------- | ------------------------ |
| `--yes, -y` | Skip confirmation prompt |

**Example:**

```bash theme={null}
$ armor api-keys revoke 550e8400-e29b-41d4-a716-446655440000
Are you sure you want to revoke this key? [y/N]: y
API key revoked successfully.
```

***

## armor tags

Tag management commands.

### armor tags list

List tags for an asset.

```bash theme={null}
armor tags list --asset <asset_id> [OPTIONS]
```

| Option           | Description                           |
| ---------------- | ------------------------------------- |
| `--asset, -a`    | Asset ID or qualified name (required) |
| `--category, -c` | Filter by category                    |

**Example:**

```bash theme={null}
$ armor tags list --asset postgresql.analytics

                              Tags
┏━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┓
┃ Name           ┃ Category   ┃ Object Path         ┃ Type       ┃
┡━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━┩
│ pii_data       │ governance │ gold.customers      │ table      │
│ financial      │ business   │ gold.orders         │ table      │
└────────────────┴────────────┴─────────────────────┴────────────┘
```

### armor tags create

Create a tag on a database object.

```bash theme={null}
armor tags create <name> --asset <asset_id> --path <object_path> [OPTIONS]
```

| Option              | Description                                                           |
| ------------------- | --------------------------------------------------------------------- |
| `--asset, -a`       | Asset ID or qualified name (required)                                 |
| `--path, -p`        | Object path, e.g., `schema.table` (required)                          |
| `--category, -c`    | Category: `business`, `technical`, `governance` (default: `business`) |
| `--description, -d` | Tag description                                                       |

**Example:**

```bash theme={null}
$ armor tags create pii_data --asset postgresql.analytics --path gold.customers --category governance

Tag created: pii_data
  Category: governance
  Path: gold.customers
```

### armor tags apply

Apply multiple tags to multiple objects.

```bash theme={null}
armor tags apply <tag_names> --asset <asset_id> --paths <object_paths> [OPTIONS]
```

| Option           | Description                                 |
| ---------------- | ------------------------------------------- |
| `--asset, -a`    | Asset ID or qualified name (required)       |
| `--paths, -p`    | Comma-separated object paths (required)     |
| `--category, -c` | Category for new tags (default: `business`) |

**Example:**

```bash theme={null}
$ armor tags apply "pii,gdpr" --asset postgresql.analytics --paths "gold.customers,gold.orders"

Applied 4 tags
```

***

## armor intelligence

AI intelligence commands.

### armor intelligence ask

Ask a question about your data.

```bash theme={null}
armor intelligence ask <asset_id> <question>
```

**Example:**

```bash theme={null}
$ armor intelligence ask postgresql.analytics "What tables contain customer data?"

Question: What tables contain customer data?

Answer:
The following tables contain customer data:
- gold.customers: Primary customer dimension table
- gold.orders: Contains customer_id foreign key

Confidence: high
Sources: Asset Discovery, Intelligence KB
```

### armor intelligence generate

Generate AI intelligence for an asset.

```bash theme={null}
armor intelligence generate <asset_id>
```

<Note>
  Requires asset discovery to be run first.
</Note>

**Example:**

```bash theme={null}
$ armor intelligence generate postgresql.analytics

Intelligence generation started
Job ID: job_abc123
Status: queued
```

***

## armor jobs

Job monitoring commands.

### armor jobs status

Get status of an async job.

```bash theme={null}
armor jobs status <job_id>
```

**Example:**

```bash theme={null}
$ armor jobs status job_abc123

Job: job_abc123
Status: completed
Progress: 100%
Started: 2024-12-21T10:30:00Z
Completed: 2024-12-21T10:32:15Z
```

***

## armor metrics

Data quality metrics commands.

### armor metrics summary

Get metrics summary for an asset.

```bash theme={null}
armor metrics summary <asset_id>
```

**Example:**

```bash theme={null}
$ armor metrics summary 550e8400-e29b-41d4-a716-446655440000

Metrics Summary
Total Metrics: 15
Active Metrics: 12
Health: 87.5%
Passing: 10
Failing: 2
```

### armor metrics list

List metrics for an asset.

```bash theme={null}
armor metrics list <asset_id> [OPTIONS]
```

| Option        | Description                                               |
| ------------- | --------------------------------------------------------- |
| `--type, -t`  | Filter by metric type (e.g., `row_count`, `null_percent`) |
| `--active`    | Only show active metrics                                  |
| `--limit, -l` | Max results (default: 50)                                 |

**Example:**

```bash theme={null}
$ armor metrics list 550e8400-e29b-41d4-a716-446655440000 --type null_percent

                           Metrics
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━┓
┃ Table                             ┃ Column       ┃ Type          ┃ Active ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━┩
│ snowflake.prod.warehouse.orders   │ customer_id  │ null_percent  │ Yes    │
│ snowflake.prod.warehouse.orders   │ email        │ null_percent  │ Yes    │
└───────────────────────────────────┴──────────────┴───────────────┴────────┘
```

### armor metrics get

Get metric details.

```bash theme={null}
armor metrics get <asset_id> <metric_id>
```

**Example:**

```bash theme={null}
$ armor metrics get 550e8400-e29b-41d4-a716-446655440000 m_abc123

Metric: m_abc123
Type: null_percent
Table: snowflake.prod.warehouse.orders
Column: customer_email
Interval: daily
Active: Yes
```

### armor metrics create

Create a new metric. Requires `read-write` scope.

```bash theme={null}
armor metrics create <asset_id> --type <type> --table <path> [OPTIONS]
```

| Option       | Description                                                      |
| ------------ | ---------------------------------------------------------------- |
| `--type, -t` | Metric type (required): `row_count`, `null_percent`, etc.        |
| `--table`    | Full table path (required)                                       |
| `--column`   | Column name (for column metrics)                                 |
| `--interval` | Capture interval: `hourly`, `daily`, `weekly` (default: `daily`) |

**Example:**

```bash theme={null}
$ armor metrics create 550e8400-e29b-41d4-a716-446655440000 \
  --type null_percent \
  --table snowflake.prod.warehouse.orders \
  --column customer_email

Metric created: m_abc123
Type: null_percent
Table: snowflake.prod.warehouse.orders
Column: customer_email
```

### armor metrics capture

Trigger an immediate metric capture. Requires `read-write` scope.

```bash theme={null}
armor metrics capture <asset_id> <metric_id>
```

**Example:**

```bash theme={null}
$ armor metrics capture 550e8400-e29b-41d4-a716-446655440000 m_abc123

Captured 1 snapshot
Value: 2.5
Anomaly: No
```

### armor metrics delete

Delete a metric. Requires `read-write` scope.

```bash theme={null}
armor metrics delete <asset_id> <metric_id> [OPTIONS]
```

| Option      | Description              |
| ----------- | ------------------------ |
| `--yes, -y` | Skip confirmation prompt |

***

## armor validity

Data validity rules commands.

### armor validity summary

Get validity summary for an asset.

```bash theme={null}
armor validity summary <asset_id>
```

**Example:**

```bash theme={null}
$ armor validity summary 550e8400-e29b-41d4-a716-446655440000

Validity Summary
Total Rules: 12
Passing: 10
Failing: 1
Error: 1
```

### armor validity list

List validity rules for an asset.

```bash theme={null}
armor validity list <asset_id> [OPTIONS]
```

| Option        | Description                                     |
| ------------- | ----------------------------------------------- |
| `--type, -t`  | Filter by rule type (e.g., `NOT_NULL`, `REGEX`) |
| `--active`    | Only show active rules                          |
| `--limit, -l` | Max results (default: 50)                       |

**Example:**

```bash theme={null}
$ armor validity list 550e8400-e29b-41d4-a716-446655440000 --type NOT_NULL

                           Validity Rules
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━┓
┃ Table                             ┃ Column        ┃ Type     ┃ Severity  ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━┩
│ snowflake.prod.warehouse.orders   │ customer_id   │ NOT_NULL │ critical  │
│ snowflake.prod.warehouse.orders   │ email         │ NOT_NULL │ warning   │
└───────────────────────────────────┴───────────────┴──────────┴───────────┘
```

### armor validity get

Get validity rule details.

```bash theme={null}
armor validity get <asset_id> <rule_id>
```

**Example:**

```bash theme={null}
$ armor validity get 550e8400-e29b-41d4-a716-446655440000 v_abc123

Rule: v_abc123
Name: Customer Email Required
Type: NOT_NULL
Table: snowflake.prod.warehouse.orders
Column: customer_email
Severity: critical
Active: Yes
```

### armor validity create

Create a new validity rule. Requires `read-write` scope.

```bash theme={null}
armor validity create <asset_id> --type <type> --table <path> [OPTIONS]
```

| Option       | Description                                                  |
| ------------ | ------------------------------------------------------------ |
| `--type, -t` | Rule type (required): `NOT_NULL`, `UNIQUE`, `REGEX`, etc.    |
| `--table`    | Full table path (required)                                   |
| `--column`   | Column name                                                  |
| `--config`   | Rule configuration (JSON string)                             |
| `--severity` | Severity: `info`, `warning`, `critical` (default: `warning`) |

**Examples:**

```bash theme={null}
# NOT NULL rule
$ armor validity create 550e8400-e29b-41d4-a716-446655440000 \
  --type NOT_NULL \
  --table snowflake.prod.warehouse.orders \
  --column customer_email \
  --severity critical

Rule created: v_abc123
Type: NOT_NULL

# REGEX rule
$ armor validity create 550e8400-e29b-41d4-a716-446655440000 \
  --type REGEX \
  --table snowflake.prod.warehouse.orders \
  --column customer_email \
  --config '{"pattern": "^[\\w.-]+@[\\w.-]+\\.\\w+$"}'

Rule created: v_def456
Type: REGEX
```

### armor validity check

Trigger an immediate validity check. Requires `read-write` scope.

```bash theme={null}
armor validity check <asset_id> <rule_id>
```

**Exit codes:**

* `0` - Validation passed
* `1` - Validation failed (invalid records found)
* `3` - Rule not found

**Example (pass):**

```bash theme={null}
$ armor validity check 550e8400-e29b-41d4-a716-446655440000 v_abc123

PASS: v_abc123 (NOT_NULL on customer_email)
Total Rows: 10000
Invalid: 0 (0.00%)
$ echo $?
0
```

**Example (fail):**

```bash theme={null}
$ armor validity check 550e8400-e29b-41d4-a716-446655440000 v_abc123

FAIL: v_abc123 (NOT_NULL on customer_email)
Total Rows: 10000
Invalid: 25 (0.25%)
Sample invalid values:
  - row 1001: null
  - row 1042: null
$ echo $?
1
```

### armor validity delete

Delete a validity rule. Requires `read-write` scope.

```bash theme={null}
armor validity delete <asset_id> <rule_id> [OPTIONS]
```

| Option      | Description              |
| ----------- | ------------------------ |
| `--yes, -y` | Skip confirmation prompt |

***

## armor referential

Referential integrity check commands.

### armor referential summary

Get referential summary for an asset.

```bash theme={null}
armor referential summary <asset_id>
```

**Example:**

```bash theme={null}
$ armor referential summary 550e8400-e29b-41d4-a716-446655440000

Referential Summary
Total Checks: 8
Active: 7
Passing: 6
Failing: 1
```

### armor referential list

List referential checks for an asset.

```bash theme={null}
armor referential list <asset_id> [OPTIONS]
```

| Option        | Description               |
| ------------- | ------------------------- |
| `--active`    | Only show active checks   |
| `--limit, -l` | Max results (default: 50) |

**Example:**

```bash theme={null}
$ armor referential list 550e8400-e29b-41d4-a716-446655440000

                           Referential Checks
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━┓
┃ Child                           ┃ Parent                           ┃ Status ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━┩
│ orders.customer_id              │ customers.id                     │ Pass   │
│ payments.order_id               │ orders.id                        │ Fail   │
└─────────────────────────────────┴──────────────────────────────────┴────────┘
```

### armor referential get

Get referential check details.

```bash theme={null}
armor referential get <asset_id> <check_id>
```

**Example:**

```bash theme={null}
$ armor referential get 550e8400-e29b-41d4-a716-446655440000 r_abc123

Check: r_abc123
Name: Orders -> Customers FK
FK: orders.customer_id
PK: customers.id
Interval: daily
Active: Yes
```

### armor referential create

Create a new referential check. Requires `read-write` scope.

```bash theme={null}
armor referential create <asset_id> [OPTIONS]
```

| Option                 | Description                     |
| ---------------------- | ------------------------------- |
| `--child-table`        | Child table path (required)     |
| `--child-column`       | Child column name (required)    |
| `--parent-table`       | Parent table path (required)    |
| `--parent-column`      | Parent column name (required)   |
| `--name`               | Human-readable name             |
| `--max-orphans`        | Max orphan count threshold      |
| `--max-orphan-percent` | Max orphan percentage threshold |

**Example:**

```bash theme={null}
$ armor referential create 550e8400-e29b-41d4-a716-446655440000 \
  --child-table snowflake.prod.warehouse.orders \
  --child-column customer_id \
  --parent-table snowflake.prod.warehouse.customers \
  --parent-column id \
  --name "Orders -> Customers FK"

Check created: r_abc123
FK: orders.customer_id -> customers.id
```

### armor referential execute

Execute a referential check. Requires `read-write` scope.

```bash theme={null}
armor referential execute <asset_id> <check_id>
```

**Exit codes:**

* `0` - Check passed (no orphans or within threshold)
* `1` - Check failed (orphans exceed threshold)
* `3` - Check not found

**Example (pass):**

```bash theme={null}
$ armor referential execute 550e8400-e29b-41d4-a716-446655440000 r_abc123

PASS: r_abc123 (orders.customer_id -> customers.id)
Total Child Rows: 10000
Orphans: 0 (0.00%)
$ echo $?
0
```

**Example (fail):**

```bash theme={null}
$ armor referential execute 550e8400-e29b-41d4-a716-446655440000 r_abc123

FAIL: r_abc123 (orders.customer_id -> customers.id)
Total Child Rows: 10000
Orphans: 5 (0.05%)
Sample orphan values:
  - customer_id: 99999
  - customer_id: 99998
$ echo $?
1
```

### armor referential delete

Delete a referential check. Requires `read-write` scope.

```bash theme={null}
armor referential delete <asset_id> <check_id> [OPTIONS]
```

| Option      | Description              |
| ----------- | ------------------------ |
| `--yes, -y` | Skip confirmation prompt |

***

## armor lineage

Data lineage commands.

### armor lineage get

Get lineage for an asset.

```bash theme={null}
armor lineage get <asset_id> [OPTIONS]
```

| Option        | Description                                                   |
| ------------- | ------------------------------------------------------------- |
| `--depth, -d` | Depth of lineage (1-5, default: 1)                            |
| `--direction` | Direction: `upstream`, `downstream`, `both` (default: `both`) |

**Example:**

```bash theme={null}
$ armor lineage get snowflake.prod.warehouse.orders --depth 2

Lineage for: snowflake.prod.warehouse.orders

Upstream (dependencies):
  - snowflake.raw.stripe.orders
  - snowflake.raw.crm.customers

Downstream (dependents):
  - snowflake.prod.mart.orders_mart
  - looker.sales_dashboard
```

***

## armor contract

ODCS contract export/import (see the [Data Contracts guide](/guides/contracts) for the ODCS background).

### armor contract pull

Export one or many contracts as ODCS YAML.

```bash theme={null}
armor contract pull [--asset UUID | --warehouse NAME | --all] [-o FILE] [OPTIONS]
```

**Scope (exactly one required):**

* `--asset UUID`: one asset, sync. Writes YAML to stdout unless `-o` given.
* `--warehouse NAME`: every contract in the warehouse, async job, writes zip to `-o`.
* `--all`: every contract in the account, async job, writes zip to `-o`.

**Options:**

* `-o, --output PATH`: output file. Required for bulk scopes.
* `--mode extended|odcs-pure`: default `extended`. `odcs-pure` strips AnomalyArmor-specific fields for maximum ODCS interop.
* `--include DOMAINS`: comma-separated domain names to include (e.g. `freshness,validity`).
* `--exclude DOMAINS`: comma-separated domain names to exclude.
* `--timeout SECONDS`: async job poll timeout, default 600.

**Examples:**

```bash theme={null}
# One asset to stdout
armor contract pull --asset <uuid>

# One asset to file, freshness + validity only
armor contract pull --asset <uuid> -o orders.yaml --include freshness,validity

# Whole warehouse
armor contract pull --warehouse analytics -o analytics.zip

# Everything, pure ODCS (max portability)
armor contract pull --all --mode odcs-pure -o contracts.zip
```

**Domain names:** `schema`, `freshness`, `validity`, `metrics`, `row_count`, `drift_monitors`, `schema_drift`, `alert_rules`, `destinations`, `blackouts`.

***

## Configuration

### Config File

The CLI stores configuration in `~/.armor/config.yaml`:

```yaml theme={null}
api_key: aa_live_your_key_here
api_url: https://api.anomalyarmor.ai
timeout: 30
```

### Environment Variables

Override config file with environment variables:

```bash theme={null}
export ARMOR_API_KEY="aa_live_xxx"
export ARMOR_API_URL="https://api.anomalyarmor.ai"
```

Environment variables take precedence over config file values.