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

# CLI reference

> Command reference for coding agents, automation, and CI/CD pipelines.

The Halios CLI is primarily used by coding agents and CI. Most users do not need to learn these commands to use Halios.

This reference documents the command interface, automation flags, and exit codes for scripting and CI pipelines.

***

## Installation

```bash theme={null}
uv tool install 'haliosai-cli>=2.0.0'
# Or using pipx:
pipx install 'haliosai-cli>=2.0.0'
```

***

## Common Commands

### Authenticate

```bash theme={null}
halios auth login
halios auth status
```

### Configure

```bash theme={null}
halios project init --agent <name> --command "<cmd>"
halios project configure
halios eval review
halios project check
```

### Run evals

```bash theme={null}
halios eval run -k 3
halios eval run --scenario <id> -k 1
halios eval report <run-id> --failures
```

### Inspect traces

```bash theme={null}
halios trace list --environment production
halios trace show <trace-id> --include spans,checks
halios trace failures --environment production
halios scenario generate --from-trace <trace-id>
```

### CI & release gates

```bash theme={null}
halios eval run -k 5 --fail-below 0.95 --json
```

***

## Common Flags

| Flag                   | Supported On          | Description                                                                  |
| :--------------------- | :-------------------- | :--------------------------------------------------------------------------- |
| `--json`               | All commands          | Output machine-readable JSON for coding agents and CI workflows.             |
| `-k <int>`             | `eval run`            | Number of trial repetitions per scenario (e.g. `-k 3`). Default: `1`.        |
| `--fail-below <float>` | `eval run`            | Minimum pass rate required to exit with code `0` (e.g. `--fail-below 0.95`). |
| `--scenario <id>`      | `eval run`            | Target a specific scenario ID for smoke testing.                             |
| `--environment <name>` | `trace list/failures` | Filter traces by environment (`production`, `staging`, `ci`, `ad_hoc`).      |
| `--failures`           | `eval report`         | Filter report to only failing trials and check errors.                       |

***

## Exit Codes

Halios uses deterministic exit codes for CI/CD scripting and automation:

| Exit Code | Status                 | Meaning                                                                                         |
| :-------: | :--------------------- | :---------------------------------------------------------------------------------------------- |
|  **`0`**  | **SUCCESS**            | All checks executed successfully, required pass rate was met, and zero protected checks failed. |
|  **`1`**  | **RELIABILITY FAIL**   | Pass rate dropped below threshold or a protected safety check failed.                           |
|  **`2`**  | **CANDIDATE REJECTED** | Optimization candidate failed verification or regressed baseline.                               |
|  **`>2`** | **SETUP ERROR**        | Missing credentials, broken adapter script, invalid schema, or connection error.                |