Documentation menu
Getting started
New in v2.0
Feature deep dives
Reference
DevOps CLI & upgrades
DevOps CLI, Validate & Self-Upgrade
29 command groups cover setup, tasks, logs, backups, docker, k8s and TLS, with a read-only validator for CI and an upgrade engine behind a health gate.
Verified against the checkout built for v2.2.4 · updated 20 Oct 2026
OperationsNew in v2.0
atf validate is read-only and exits non-zero on failure, so it works as a pre-deploy gate in any pipeline.
Lifecycle in one place
atf setup # guided wizard: validate, build, then prove each service
atf status --watch # live board of services, ports and tasks
atf doctor --fix # diagnose and repair
atf system upgrade # git pull -> build -> recreate -> alias repair -> health gate
atf system service install# start the stack at boot (systemd / launchd / Task Scheduler)
atf release portable # build dist/atf.pyz — the single-file CLIThe validator
atf validate runs read-only checks and exits 0 only when every one passes. --strict promotes warnings to failures, --runtime adds live checks against the running stack, and --deep runs the repository audits. --json prints exactly one JSON object, so a pipeline can consume it.
| Check | What it proves |
|---|---|
| layout | The checkout is complete: compose file, Dockerfiles, CLI and services. |
| env-file / env-keys / env-secrets | Required keys exist, secrets meet the length floor, .env is not world readable. |
| env-typos / env-ignored | No stray keys the example file does not document; .env is git-ignored. |
| compose | docker-compose.yml parses cleanly. |
| catalog / catalog-placeholders / catalog-rtl | Ten-language key and placeholder parity, and no RTL leakage into English. |
| secrets-scan | No credential-shaped literal in any tracked file. |
| database / proto / ports | SQLite integrity, generated stubs not older than the .proto sources, no foreign process on ATF ports. |
| container-env (runtime) | The running API reports the configuration it actually received — this is the check that catches a container older than .env. |
Upgrades with a health gate
atf system upgrade pulls, rebuilds, recreates the containers, repairs the compose network aliases and then requires the health check to pass. If the stack does not come back healthy, the failure is loud rather than a half-migrated install.
Container recreation is the step that most often breaks networking: a manually recreated container loses its compose alias. The upgrade path reconnects the aliases, so the core, api and web names stay resolvable to each other and to the external AI bridge.
Scriptable output
atf validate --strict --json | jq '.checks[] | select(.status != "ok")'
atf system services --json | jq '{healthy, total, failing}'
atf status --json | jq '.services[] | {name, port, reachable}'Frequently asked
Can I use the validator in CI without touching a running stack?
Yes. atf validate is read-only by default; --runtime only adds checks, and nothing it runs mutates the deployment.
How do I know an upgrade worked?
atf system upgrade ends in a health gate over all four services. atf system services reports state, health, endpoint and version per service, and exits non-zero if anything is down.
Do I need docker to use the CLI?
No. There are docker, source and portable modes; atf platform prints the exact install commands for the host you are on, and the portable build is a single standard-library file.