CLI reference
Commands, flags, exit codes, and environment variables of the altcha-sentinel binary.
Synopsis
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 versionWithout 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 asdoctor --config-only,license inspect,migrate, andschema 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 asdoctor,healthcheck, andlicense request. On Kubernetes, usekubectl execthe 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. |
-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.
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. |
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.tomldoctor
Validates the config and checks this host's storage, network, and setup without starting the server.
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.
docker exec sentinel /usr/local/bin/altcha-sentinel --config /etc/sentinel/sentinel.toml doctor --jsonmigrate
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.
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.
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.ageThe 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.
altcha-sentinel [-c FILE] healthcheckNo 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.
docker exec sentinel /usr/local/bin/altcha-sentinel --config /etc/sentinel/sentinel.toml healthchecklicense inspect
Decodes a license file, prints its contents, and checks its signature. Needs no config or database.
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.
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.liclicense request
Prints the license request (with the deployment ID) of the configured database, creating the deployment ID first when needed.
altcha-sentinel [-c FILE] license requestNo 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 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.
docker exec sentinel /usr/local/bin/altcha-sentinel --config /etc/sentinel/sentinel.toml license request > license-request.jsonschema 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.
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.
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.sqlEnvironment variables
Variables the binary reads directly. Variables referenced from the config file with ${ENV_VAR} are covered in the Configuration reference. 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. |