All failure analysis commands live under the fa group.
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.
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 |
--trace-id and --dataset are mutually exclusive. At least one is required.
Examples
# 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.
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 |
# Check status once
valiqor fa status --run-id abc123
# Wait with progress bar and ETA
valiqor fa status --run-id abc123 --wait
In wait mode, the CLI polls every 3 seconds until the run completes, fails, or is cancelled.
fa result
Fetch and display failure analysis results.
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 |
# 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.
| 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
# 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
