Alpha. VIA is under active development. APIs, operational flows, and host requirements may change between releases.

This page lists the operator commands that are present in the current Via and Vary CLIs. Examples use `prod` as the named target and `my-api` as an existing Via app. Operator examples assume `via install` has added your host user to the Via admin/shared group. Reconnect or run `newgrp vary` after first install so the membership is active in your shell. ## Server status ```bash via status via status --json ``` `via status` reports the Via version, installed service runtime, default toolchain, upgrade state, production/dev mode, external URL, tracked component states, Docker reachability, state-directory free space, and an overall `healthy` or `degraded` result. It exits non-zero when the report is degraded. Useful local overrides: ```bash via status --config /etc/via/server.toml via status --config-dir /etc/via --state-dir /var/lib/via --log-dir /var/log/via via status --systemd-dir /etc/systemd/system --install-root /opt/vary ``` The tracked components are `control-plane`, `builder`, `runner`, `test-runner`, `config-server`, and `proxy`. ## Server doctor ```bash via doctor via doctor --fix via doctor --json via doctor --skip-host-checks ``` `via doctor` checks the control-plane schema first, then host/service prerequisites unless `--skip-host-checks` is passed. It exits non-zero for failed checks or an unknown-newer schema. Use `via doctor --fix` when doctor reports a safe host repair, such as runtime-trust bootstrap drift, before rerunning the normal health check. Useful local overrides: ```bash via doctor --db-path /var/lib/via/control-plane.db via doctor --config-dir /etc/via --state-dir /var/lib/via --log-dir /var/log/via via doctor --systemd-dir /etc/systemd/system ``` If doctor reports `prebaseline_checksum_drift`, create a drift-safe backup before repair: ```bash via backup create --include-control-plane --allow-checksum-drift /var/lib/via/backups/prebaseline.zip ``` Preview a metadata-only rebaseline before applying it: ```bash via control-plane rebaseline --from-prebaseline --backup-id --dry-run --json ``` Apply only after the compatibility report is clean: ```bash via control-plane rebaseline --from-prebaseline --backup-id \ --confirm "REBASELINE /var/lib/via/control-plane.db TO 1" via upgrade resume via doctor ``` The clean-install path is destructive and requires a typed confirmation: ```bash via control-plane clean-install --dry-run ``` ## App status ```bash vary app status my-api --target prod vary app status my-api --target prod --json vary app inspect my-api --target prod vary app inspect my-api --target prod --env prod --json ``` `status` gives the current deploy/build/runtime snapshot. `inspect` adds state-transition history, gate results, declared config and secret names, runtime health checks, add-ons, and recent events. Secret values are never printed. For same-host operator access, use the local Via commands: ```bash via app status my-api via app inspect my-api via app doctor my-api ``` ## Logs Remote log access: ```bash vary app logs my-api --target prod vary app logs my-api --target prod --source runtime --tail 200 vary app logs my-api --target prod --source build --tail 200 vary app logs my-api --target prod --follow ``` Local phase-specific log access: ```bash vary app logs my-api --build vary app logs my-api --test vary app logs my-api --mutation vary app logs my-api --deploy vary app logs my-api --audit vary app logs my-api --runtime --since 2026-04-25T12:00:00Z ``` Local `--since` and `--until` values are ISO-8601 instants. Remote target mode uses `--since` as the byte offset returned by the previous log response. ## Builds and deploys ```bash vary app builds my-api --target prod vary app build --target prod vary app build logs --target prod --app my-api --tail 200 vary app build logs --target prod --app my-api --follow vary app build cancel --target prod --app my-api --follow vary app deploys my-api --target prod vary app deploy --target prod vary app deploy retry --target prod --app my-api --apply-manifest --follow ``` `builds` and `deploys` list recent rows for an app. `build` and `deploy` show a single row by id. `build logs` requires the app name through `--app` unless the current project has `[app].id` in `vary.toml`. Use `--apply-manifest` on deploy retry so Via reconciles against the current effective manifest before queueing the replacement deploy. The app-level diagnostic commands are: ```bash vary app doctor my-api --target prod vary app smoke my-api --target prod vary app repair my-api --target prod --dry-run --json vary app repair my-api --target prod ``` `doctor` diagnoses route, runtime, dependency, build consistency, stuck build, and log-availability problems. `smoke` probes the advertised app route from the developer workstation. `repair` renews runtime identity and relaunches the runtime; unsafe repair actions require `--allow-unsafe --reason `. ## Releases and rollback ```bash vary app releases my-api --target prod vary app releases my-api --target prod --limit 10 --json vary app rollback my-api --target prod vary app rollback my-api --target prod --release vary app rollback my-api --target prod --json ``` Rollback targets releases, not deploy ids. Without `--release`, the server chooses the immediately previous release for the app. Rollback flips the app's current release and does not trigger a rebuild. ## Domains, certificates, and routes Developer app route intent lives in `via.app.toml` and is applied by deploy: ```bash vary app deploy my-api --target prod --apply-manifest vary app deploy my-api --target prod --resume vary app smoke my-api --target prod ``` Operator route and certificate surfaces: ```bash via domain list via domain requests via domain approve my-api api.example.com --reason "approved" via domain reject my-api api.example.com --reason "not allowed" via load-balancer routes via load-balancer validate via load-balancer reload via load-balancer status via certificate list via certificate inspect --server https://vary.example.com --session-token ``` `via domain approve`, `via domain reject`, and `via domain requests` are local-only operator commands. `via load-balancer status` is local-only. The certificate lifecycle commands use the operator API and require `--server` and `--session-token`, except `via certificate list`, which also supports local control-plane reads. Certificate private keys, PEM material, ACME account keys, and storage paths must not appear in app-owner responses, CLI output, audit exports, operation logs, or health reports. For certificate-specific workflows, see [Certificates](/docs/via/certificates/). ## Key rotation ```bash via key rotate identity via key rotate artifacts via secret key rotate ``` Each rotation archives the previous active key under `previous/`, writes a new active key, and records an audit event. The commands accept `--actor`, `--config-dir`, `--state-dir`, `--log-dir`, and `--systemd-dir`. | Command | Rotates | Audit action | |---|---|---| | `via key rotate identity` | JWT identity signing key | `identity_key_rotated` | | `via key rotate artifacts` | Artifact signing key | `artifact_key_rotated` | | `via secret key rotate` | Secret encryption key | `secret_encryption_key_rotated` | Tokens minted under the previous identity key continue to verify until they expire. Artifacts signed under the previous artifact key continue to launch. Secrets encrypted under the previous secret key continue to decrypt until that value is rewritten. To re-encrypt an app secret after rotating the server secret key: ```bash vary app env rotate my-api DATABASE_URL --target prod ``` ## Backup and restore ```bash via backup create /var/backups/vary/.zip via backup create --include-secrets /var/backups/vary/.zip via backup restore /var/backups/vary/.zip via backup restore /var/backups/vary/.zip --overwrite via backup restore /var/backups/vary/.zip --skip-secret-key ``` The default backup includes server config, public identity material, signing keys, bare repos, artifacts, SQLite add-on state, and a control-plane database snapshot. It does not include the secret encryption key file. `--include-secrets` adds that key; treat the archive itself as a recovery key. Restore refuses to write over an initialized host unless `--overwrite` is passed. `--skip-secret-key` keeps the target host's existing secret encryption key instead of writing the key from the bundle. After restore, restart the Via services: ```bash systemctl restart via-server via-builder via-runner via-test-runner via-config ``` Continue to [TLS, routing, and the proxy](/docs/via/proxy/) for the public-traffic surface.