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

# Failure Analysis

> CLI commands for running failure analysis, checking status, retrieving results, and listing runs.

All failure analysis commands live under the `fa` group.

```bash theme={"system"}
valiqor fa <run|status|result|list>
```

### Common Flags

Every `fa` subcommand accepts:

| Flag         | Type     | Default | Description           |
| ------------ | -------- | ------- | --------------------- |
| `--api-key`  | `string` | —       | API key override      |
| `--project`  | `string` | —       | Project name override |
| `--base-url` | `string` | —       | Backend URL override  |

***

## fa run

Run failure analysis on a trace or dataset.

```bash theme={"system"}
valiqor fa run [--trace-id <id> | --dataset <path>] [flags]
```

| Flag             | Type                                         | Default       | Description                                                         |
| ---------------- | -------------------------------------------- | ------------- | ------------------------------------------------------------------- |
| `--trace-id`     | `string`                                     | —             | Trace UUID to analyze                                               |
| `--dataset`      | `string`                                     | —             | Path to a dataset JSON file                                         |
| `--feature-kind` | `rag \| agent \| agentic_rag \| generic_llm` | auto-detected | Application type hint                                               |
| `--no-eval`      | `flag`                                       | `false`       | Skip evaluation metrics                                             |
| `--no-security`  | `flag`                                       | `false`       | Skip security audit                                                 |
| `--buckets`      | `string`                                     | —             | Comma-separated failure bucket filter (e.g. `hallucination,safety`) |
| `--async`        | `flag`                                       | `false`       | Submit asynchronously and return a job ID                           |

<Warning>
  `--trace-id` and `--dataset` are mutually exclusive. At least one is required.
</Warning>

### Examples

```bash theme={"system"}
# Analyze a trace (synchronous)
valiqor fa run --trace-id 550e8400-e29b-41d4-a716-446655440000

# Analyze a dataset, skip security
valiqor fa run --dataset inputs.json --no-security

# Filter specific failure buckets
valiqor fa run --trace-id abc123 --buckets hallucination,safety

# Async analysis
valiqor fa run --dataset inputs.json --async
```

### Output

Displays:

* **Summary** — failures detected, passes, severity, confidence, primary failure
* **Alert & CI-gate recommendations**
* **Per-failure tags** — bucket, subcategory, decision, severity, confidence, detector, rationale
* **Linked results** — associated eval run ID and security batch ID (if applicable)

***

## fa status

Check the status of a failure analysis run.

```bash theme={"system"}
valiqor fa status --run-id <id> [flags]
```

| Flag            | Type     | Default      | Description                                    |
| --------------- | -------- | ------------ | ---------------------------------------------- |
| `--run-id`      | `string` | **required** | FA run or job ID                               |
| `--wait` / `-w` | `flag`   | `false`      | Poll until completion with a live progress bar |

```bash theme={"system"}
# Check status once
valiqor fa status --run-id abc123

# Wait with progress bar and ETA
valiqor fa status --run-id abc123 --wait
```

<Info>
  In wait mode, the CLI polls every 3 seconds until the run completes, fails, or is cancelled.
</Info>

***

## fa result

Fetch and display failure analysis results.

```bash theme={"system"}
valiqor fa result --run-id <id> [flags]
```

| Flag       | Type     | Default      | Description                                  |
| ---------- | -------- | ------------ | -------------------------------------------- |
| `--run-id` | `string` | **required** | FA run ID                                    |
| `--json`   | `flag`   | `false`      | Output raw JSON instead of formatted display |

### JSON Output Fields

When using `--json`, the output includes:

| Field               | Description                            |
| ------------------- | -------------------------------------- |
| `run_id`            | Unique run identifier                  |
| `status`            | Run status                             |
| `mode`              | Analysis mode                          |
| `input_type`        | Input source type                      |
| `feature_kind`      | Detected or specified application type |
| `summary`           | High-level results summary             |
| `failure_tags`      | Array of detected failure tags         |
| `eval_run_id`       | Linked evaluation run (if applicable)  |
| `security_batch_id` | Linked security batch (if applicable)  |
| `duration_ms`       | Processing duration in milliseconds    |
| `tokens_used`       | Token consumption for this run         |

```bash theme={"system"}
# Formatted output
valiqor fa result --run-id abc123

# Raw JSON for scripting or CI/CD
valiqor fa result --run-id abc123 --json
```

***

## fa list

List failure analysis runs with pagination.

```bash theme={"system"}
valiqor fa list [flags]
```

| Flag          | Type                                          | Default | Description          |
| ------------- | --------------------------------------------- | ------- | -------------------- |
| `--status`    | `completed \| failed \| running \| cancelled` | —       | Filter by run status |
| `--page`      | `int`                                         | `1`     | Page number          |
| `--page-size` | `int`                                         | `15`    | Items per page       |

### Examples

```bash theme={"system"}
# List all runs
valiqor fa list

# List only completed runs
valiqor fa list --status completed

# Paginate through results
valiqor fa list --page 2 --page-size 10
```

Displays run ID, status, input type, failure count, primary failure, and created date.