# CLI reference

> **Sentinel v2 (beta):** This page documents Sentinel v2, a beta rewrite that may change before the stable release. It does not apply to Sentinel v1, the current stable version: see the [Sentinel v1 documentation](/docs/sentinel.md).

Commands, flags, exit codes, and environment variables of the `altcha-sentinel` binary.

## Synopsis

```text
altcha-sentinel [-c FILE] [COMMAND]

Commands:
doctor           Validate the config and check this host without starting the server
migrate          Convert a snapshot of the previous Sentinel version into a v2 snapshot
healthcheck      Exit 0 when the local server answers GET /, 1 otherwise
license inspect  Decode a license file and check its signature
license request  Print the license request (deployment ID) of the configured database
schema sql       Print the SQL migration of the configured database, for auto_migrate = false
help             Print help for a command

Options:
-c, --config <FILE>  Config file (TOML)
-h, --help           Print help
-V, --version        Print version
```

Without a command, `altcha-sentinel` starts the server. Sentinel is distributed only as the container image `ghcr.io/altcha-org/sentinel`. The binary is `/usr/local/bin/altcha-sentinel` and is the image's entrypoint, so the arguments after the image name are passed to it. The examples below run commands two ways:

- **In a one-off container** (`docker run --rm … ghcr.io/altcha-org/sentinel:2.0.0-beta.1 <command>`) for commands that don't need the running server, such as `doctor --config-only`, `license inspect`, `migrate`, and `schema sql`. Mount the same config file, secrets, and data volume as the server.
- **In the running container** (`docker exec sentinel /usr/local/bin/altcha-sentinel <command>`) for commands that should see the server's environment, network, and database, such as `doctor`, `healthcheck`, and `license request`. On Kubernetes, use `kubectl exec` the same way.

## Global options

| Flag | Default | Description |
| --- | --- | --- |
| `-c`, `--config <FILE>` | `sentinel.toml` | Config file to load. Without the flag, `sentinel.toml` in the working directory is read when present; when it doesn't exist, built-in defaults are used. With the flag, a missing file is an error. Accepted before or after the command. See [Configuration reference](/docs/sentinel/v2/reference/configuration/). |
| `-h`, `--help` | — | Print help for the binary or a command, then exit `0`. |
| `-V`, `--version` | — | Print `altcha-sentinel <version>`, then exit `0`. |

Every command exits `2` on a command-line usage error (unknown flag, missing argument).

## Server (no command)

Starts the server: loads the config, resolves secrets, validates the configuration, connects to the database and KV store, applies schema migrations (or, with `auto_migrate = false`, checks that the schema is current), then serves the listeners until `SIGTERM` or Ctrl-C.

```text
altcha-sentinel [-c FILE]
```

| Exit code | Meaning |
| --- | --- |
| `0` | Clean shutdown after a signal. |
| `1` | Startup failed (config, secrets, validation, storage, schema, or license instance slot); the reason is printed on stderr. |

```bash
docker run -d --name sentinel -p 3000:3000 \
-v "$PWD/sentinel.toml:/etc/sentinel/sentinel.toml:ro" \
-v "$PWD/secrets:/run/secrets:ro" \
-v sentinel-data:/home/nonroot/data \
ghcr.io/altcha-org/sentinel:2.0.0-beta.1 --config /etc/sentinel/sentinel.toml
```

## doctor

Validates the config and checks this host's storage, network, and setup without starting the server.

```text
altcha-sentinel [-c FILE] doctor [--json] [--config-only]
```

| Flag | Default | Description |
| --- | --- | --- |
| `--json` | off | Print the report as JSON instead of text. |
| `--config-only` | off | Only validate the config (`config.file` and `config.valid`): no connections, probes, or file access beyond the files the config names. The `[license] file` isn't read; the full run verifies it. Suits CI. |

| Exit code | Meaning |
| --- | --- |
| `0` | No check failed (warnings and skipped checks included). |
| `1` | At least one check failed, or the JSON report could not be serialized. |

**Output.** The text report groups checks by category and prints each with its status (`ok`, `warn`, `FAIL`, `skip`), check ID, message, and hint, followed by a summary line. Colors are used only when stdout is a terminal and `NO_COLOR` is unset. With `--json`, the report has `version`, `config` (the file read; `null` with the defaults), `generatedAt`, `durationMs`, `summary` (`ok`, `warn`, `fail`, `skipped` counts), and `checks` (each with `id`, `category`, `subject`, `status`, `message`, `hint`, `details`, `durationMs`).

When the config fails to load or validate, no other check runs. Checks that need a running server's state (license status and instances, remote file state, cluster) run only in the API's doctor. See [Troubleshooting](/docs/sentinel/v2/operations/troubleshooting/).

```bash
docker exec sentinel /usr/local/bin/altcha-sentinel --config /etc/sentinel/sentinel.toml doctor --json
```

## migrate

Converts a snapshot of the previous Sentinel version (`.tgz` or age-encrypted `.tgz.age`) into a v2 snapshot to restore with `POST /v2/snapshots/_restore`.

```text
altcha-sentinel [-c FILE] migrate [--output-dir DIR] [--identity FILE] [--skip-logs] INPUT
```

| Argument / flag | Default | Description |
| --- | --- | --- |
| `INPUT` | — | The old snapshot (`.tgz` or `.tgz.age`). Required. |
| `--output-dir <DIR>` | `.` | Directory for the new snapshot; created when missing. |
| `--identity <FILE>` | — | age X25519 identity file that decrypts an encrypted old snapshot. Required when `INPUT` is encrypted. |
| `--skip-logs` | off | Leave out the raw request logs (can be large); hourly statistics are still migrated. |

Run it with the config of the v2 server that will restore the snapshot: secrets in the snapshot are encrypted with its `[secrets] encryption_key`, the output is encrypted to its `[snapshots]` recipients when an identity is configured, and its `[threats]` and `[pow]` settings shape the conversion.

| Exit code | Meaning |
| --- | --- |
| `0` | The snapshot was written. |
| `1` | Conversion failed (unreadable or encrypted input without `--identity`, invalid identity, invalid config or secrets, output file already exists); the reason is printed on stderr. |

**Output.** The file is named `sentinel-<timestamp>-manual.zip` (`.zip.age` when encrypted). Warnings go to stderr as `warning: …`; stdout prints the path and size, the row count per migrated table, and a warning when the file exceeds `[snapshots] max_upload_size`. See [Migrate data](/docs/sentinel/v2/upgrade/migrate-data/).

```bash
docker run --rm \
-v "$PWD/sentinel.toml:/etc/sentinel/sentinel.toml:ro" \
-v "$PWD/secrets:/run/secrets:ro" \
-v sentinel-data:/home/nonroot/data \
-v "$PWD/migration:/migration" \
ghcr.io/altcha-org/sentinel:2.0.0-beta.1 --config /etc/sentinel/sentinel.toml \
migrate --output-dir /migration --identity /migration/old-identity.txt /migration/sentinel-backup.tgz.age
```

The `migration` folder holds the old snapshot and identity and receives the output, so it must be writable by uid `65532`.

## healthcheck

Checks that the server on this host answers on its main listener; meant for container health checks.

```text
altcha-sentinel [-c FILE] healthcheck
```

No flags. It sends `GET /` to `[server] port` on `[server] host` (loopback when `host` is `0.0.0.0` or `::`), with a 3-second timeout and no proxy. With `[server] tls` set, it uses HTTPS without checking the certificate, which names the public host rather than the probed address. It reads only the config file: no storage, no secrets. Without `--config` and with no `./sentinel.toml`, it probes the default port `3000`, as the server does without a config file; a failure then adds `no --config and no ./sentinel.toml: probed the default port 3000; pass the server's --config` to the reason.

| Exit code | Meaning |
| --- | --- |
| `0` | The server answered `200` with `{"ok": true}`. |
| `1` | Connection error, timeout, non-2xx status, or unexpected body (reason on stderr), or the config could not be loaded. |

**Output.** None on success. The Docker image runs it as its `HEALTHCHECK` every 10 s (timeout 5 s, start period 30 s, 3 retries) without `--config`; pass `--config` in your own health check when the config isn't `./sentinel.toml`. See [Monitoring](/docs/sentinel/v2/operations/monitoring/).

```bash
docker exec sentinel /usr/local/bin/altcha-sentinel --config /etc/sentinel/sentinel.toml healthcheck
```

## license inspect

Decodes a license file, prints its contents, and checks its signature. Needs no config or database.

```text
altcha-sentinel license inspect FILE
```

| Argument | Default | Description |
| --- | --- | --- |
| `FILE` | — | The license file. Required. |

| Exit code | Meaning |
| --- | --- |
| `0` | The signature is valid (including a license bound to a deployment). |
| `1` | The file can't be read, can't be decoded, or its signature is invalid. |

**Output.** Plain text: `signer root`, `signer kid`, `digest`, the payload as pretty-printed JSON, then `signature: valid`, `signature: valid; bound to deployment <id>`, or `signature: INVALID: <reason>`. See [Licensing](/docs/sentinel/v2/configure/licensing/).

```bash
docker run --rm -v "$PWD/license.lic:/tmp/license.lic:ro" \
ghcr.io/altcha-org/sentinel:2.0.0-beta.1 license inspect /tmp/license.lic
```

## license request

Prints the license request (with the deployment ID) of the configured database, creating the deployment ID first when needed.

```text
altcha-sentinel [-c FILE] license request
```

No flags. It connects to the configured database (creating `data_dir` for the embedded database) and applies schema migrations, so run it with the server's config. With `[database] auto_migrate = false`, it only checks the schema and fails while changes are pending; apply the output of [`schema sql`](#schema-sql) first.

| Exit code | Meaning |
| --- | --- |
| `0` | The request was printed. |
| `1` | Config, database connection, migration, or schema check failed; the reason is printed on stderr. |

**Output.** The license request as pretty-printed JSON on stdout. Send it to ALTCHA to get a license bound to this deployment. See [Licensing](/docs/sentinel/v2/configure/licensing/).

```bash
docker exec sentinel /usr/local/bin/altcha-sentinel --config /etc/sentinel/sentinel.toml license request > license-request.json
```

## schema sql

Prints the SQL that brings the configured database to this version's schema, for a database administrator to apply when `auto_migrate = false`. It changes nothing.

```text
altcha-sentinel [-c FILE] schema sql [--clickhouse]
```

| Flag | Default | Description |
| --- | --- | --- |
| `--clickhouse` | off | Print the migration of the `[clickhouse]` tables instead of the main database's. Needs `[clickhouse] url`. |

Without `--clickhouse`, it connects with the `[database]` credentials and covers ExotDB's system tables (embedded databases only), Sentinel's tables, and the built-in KV store's tables when the KV store keeps its data in the database. Run it with the new version's image and the server's config: `url`, `table_prefix`, and the `[redis]` settings decide which tables the script covers. With embedded SQLite, it creates `data_dir` and an empty database file when they're missing.

| Exit code | Meaning |
| --- | --- |
| `0` | The script was printed, including a script with nothing to apply. |
| `1` | Config, database or ClickHouse connection, or schema read failed, or `--clickhouse` without `[clickhouse] url` (`no [clickhouse] url configured`); the reason is printed on stderr. |

**Output.** The script on stdout. For the main database: a header with the generating version and the SQL dialect, then one section per part of the schema, with a `--` comment naming each change. With `--clickhouse`: a header with the generating version and the target ClickHouse database, then the statements. A current schema prints `-- The schema is current; nothing to apply.` (`-- The ClickHouse schema is current; nothing to apply.` with `--clickhouse`). See [Schema migrations](/docs/sentinel/v2/operations/schema-migrations/).

```bash
docker run --rm \
-v "$PWD/sentinel.toml:/etc/sentinel/sentinel.toml:ro" \
-v "$PWD/secrets:/run/secrets:ro" \
ghcr.io/altcha-org/sentinel:2.0.0-beta.1 --config /etc/sentinel/sentinel.toml \
schema sql > migration.sql
```

## Environment variables

Variables the binary reads directly. Variables referenced from the config file with `${ENV_VAR}` are covered in the [Configuration reference](/docs/sentinel/v2/reference/configuration/). The log level comes from the config, not from `RUST_LOG`.

| Variable | Used by | Description |
| --- | --- | --- |
| `HOSTNAME` | server | Node ID of this replica's license instance slot; keep it stable so a restart reclaims its slot at once. Falls back to the host name. |
| `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` (or lowercase) | server, `doctor` | Proxy for outbound HTTP calls (license server, remote files, alerts, AI providers). On macOS and Windows, system proxy settings apply to schemes without a variable. `healthcheck` ignores them. |
| `NO_COLOR` | `doctor` | When set, the text report is printed without colors. |
| `OTEL_*` | server | Standard OpenTelemetry exporter settings, used when telemetry is enabled and the config sets no endpoint. |
