CLI and upgrades

The ax CLI is the operator interface for a stack: login, initialize a project, deploy it, inspect state, read logs, and manage lifecycle.

Use ax --help and subcommand help for the exact flags supported by your installed version.

First-time setup

Create a production runner token:

ax generate

Use the same token on the server as RUNNER_TOKEN. Then login to the stack:

ax login apps.example.com

For local development with default Compose values:

ax login localhost --token local-dev-token

The login host must match PLATFORM_BASE_DOMAIN.

Project workflow

From a uv Python project:

ax init
ax deploy

ax init creates the initial app manifest. ax deploy pushes the project to the runner, builds it, and starts it.

Operating apps

Common day-to-day commands:

• ax ps - list deployed apps and process state.
• ax logs myapi --tail 300 - read recent logs for an app.
• ax restart myapi - restart an app after config or dependency changes.
• ax stop myapi - stop an app without deleting its record.
• ax start myapi - start a stopped app.
• ax rm myapi - remove an app from the runner.

Use the app name from ax.toml.

Host and protocol rules

ax login accepts the same hostname or IP used as PLATFORM_BASE_DOMAIN:

• localhost and *.localhost use HTTP.
• Raw public IPs use HTTP.
• Real hostnames use HTTPS.

Do not include http:// or https:// in PLATFORM_BASE_DOMAIN.

Updating the CLI when you pull Ax changes

If you installed with uv tool:

uv tool list
uv tool upgrade ax

If you develop from cli/ with a virtual environment:

cd /path/to/ax/cli
uv sync
uv run ax --help

After a CLI update, run ax --help to confirm the version on your path is the one you expect.