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

# CLI

> The sengol command: credentials, commands by persona, and exit codes.

The `sengol` CLI ships in the `sengol` package. Most commands are clients of
the appliance's API. A few run locally with no appliance at all.

```bash theme={null}
sengol --help
```

## Credentials

API commands read `SENGOL_API_URL` and exit `2` without it.

| Commands | Credential used, in order |
| - | - |
| `gate`, `promote`, `report generate`, `controlbook gold-score`, `check-drift`, `worker run` | `SENGOL_API_TOKEN`, then CI OIDC. **They ignore `sengol login`.** |
| `audit list`, `audit export`, `audit verify` (online) | as above, then the `sengol login` session |
| `agents secrets`, `lifecycle certify` / `revoke`, `judge promote` | the `sengol login` session first |

* `SENGOL_API_TOKEN` takes an `sk_` token or a session JWT.
* `sengol login` opens your SSO in a browser. `sengol login --device` prints
  a code to approve at `/device` in the Console, and also works for local
  users with a password.
* `sengol auth status` shows the cached session. `sengol logout` clears it.

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

It exits `1` here because this shell has not run `sengol login`.

## Commands by persona

### Everyone

| Command | Runs | Does |
| - | - | - |
| `sengol license status` | locally | Shows the licence state this process would see |
| `sengol policy list [--region] [--industry]` | locally | Lists the policy catalog |
| `sengol regulation show <ID>` | locally | A regulation's obligations and suggested evaluators |
| `sengol eval list [--category] [--policy]` | locally | Lists evaluators |

### Developers

| Command | Does |
| - | - |
| `sengol gate --config sengol.yaml [--dataset-path F] [--fail-on-gate-failure]` | Runs the evaluation gate. See [Gate releases in CI](https://docs.sengol.io/guides/ci-gate.md). |
| `sengol eval resume <run_id>` | Finishes uploading an interrupted dataset run |
| `sengol promote --run-id <id>` | Writes the promotion record for a passed run |
| `sengol audit list [--agent-id] [--limit] [--format json]` | Lists recent signed records |
| `sengol analyze --traces F.jsonl` | Clusters failures in a trace file and suggests evaluators (local) |
| `sengol regression list` / `add` / `run` | Turns production failures into regression cases |

### Compliance

| Command | Does |
| - | - |
| `sengol controlbook validate --file F` | Validates a ControlBook (local) |
| `sengol report generate --controlbook F --format json\|pdf --agent A --from D --to D` | Generates a report locally. **The signature is empty**: use the Console or API for reports of record. |

### Reviewers

| Command | Does |
| - | - |
| `sengol review list [--status PENDING]` | Lists review items |
| `sengol review decide <id> --approved \| --rejected --failure-mode M` | Records a decision. A second decision on the same item exits `1`. |

### Auditors

| Command | Does |
| - | - |
| `sengol export --agent A --out pack.json [--wait-for-countersign]` | Exports an evidence pack (JSON) |
| `sengol verify --offline pack.json --trusted-keys-file K` | Verifies a pack offline. Same exit codes as [`sengol-verify`](https://docs.sengol.io/journeys/auditor#exit-codes). |
| `sengol audit verify --chain --agent-id A` | Online check of the chain and every HMAC |

### Operators

| Command | Does |
| - | - |
| `sengol worker run --config sengol.yaml` | Runs the background evaluation worker. The only command that checks the licence. |
| `sengol agents register` / `secrets` / `quarantine` / `release` | Agent credentials and quarantine. `register` works only for an agent that already exists. A new agent needs an approved intake. |
| `sengol access grants` / `grant` / `whoami` | Resource-scoped access (needs `users:admin`) |

## Exit codes for `sengol gate`

| Code | Meaning |
| - | - |
| `0` | Passed, or failed without `--fail-on-gate-failure` |
| `1` | Failed, with `--fail-on-gate-failure` or `--promote` |
| `2` | Config, dataset or evaluator error |
| `3` | An evaluator raised an exception |
| `4` | The appliance refused the run, or a case could not be signed |
| `5` | Upload retries exhausted; run `sengol eval resume <run_id>` |

## Logs

Commands log to stderr in structured form. Redirect it to keep output clean:

```bash theme={null}
sengol policy list --region EU 2>/dev/null
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.