> ## Documentation Index > Fetch the complete documentation index at: https://docs.levelrail.com/llms.txt > Use this file to discover all available pages before exploring further. # Levelrail CLI Reference > Complete reference of all Levelrail CLI commands, organized by group with examples and typical use cases. `levelrail-cli` is a scriptable client for the control plane's HTTP API. Everything it does goes through `/api/v1`, with the same tokens and permissions as the dashboard, so you need no SSH key and no open port on your servers. This page lists every command group with its subcommands and the flags you will use most. Run `levelrail-cli` with no arguments for the command list, or `levelrail-cli -h` for any command's own flags. Commands are shown as `levelrail-cli ...`. If you rename the binary, the command name follows it (the CLI reads its name from `os.Args[0]`). The server is a separate binary, `levelrail`, which has a few maintenance commands of its own, such as `setup-token`, `restore-snapshot`, `restore-db`, `recover-admin`, `upgrade-note` (record who swapped the binary by hand), and `healthcheck`. Those are in [Installing](/installing) and [Disaster recovery](/disaster-recovery). ## Install and sign in `curl -fsSL https://levelrail.com/install-cli.sh | sh` ```bash theme={"dark"} export APP_API_URL=https://console.example.com levelrail-cli auth login --device levelrail-cli auth whoami ``` `--device` prints a short code that you approve in the dashboard, the same model as `gh auth login`. Credentials are saved to `~/.config/levelrail-cli/credentials`. For CI, create an API token under **Settings, API tokens** and pass it with `--token` or `APP_API_TOKEN`. Each command resolves its target in this order, and an explicit flag always wins: | Setting | Flag | Environment variable | Default | | - | - | - | - | | API token | `--token` | `APP_API_TOKEN` | the saved profile | | Control plane URL | `--api-url` | `APP_API_URL` | `http://localhost:8080` | | Profile | `--profile` | `APP_PROFILE` | `default` | Manage more than one control plane with named profiles: `levelrail-cli auth login --profile staging`, then `--profile staging` on any command. `levelrail-cli profile list` shows them. ## Scripting: `--json` and exit codes Every command that returns data or a result supports `--json` (shorthand for `--output json`), and `--query` takes a JMESPath expression. With `--json`, stdout carries only the JSON result. The exceptions are `completion bash|zsh|fish` (a shell script) and `control-plane-backups help-dr` (a static runbook). A test walks the command tree and fails when a new command has no `--json` and is not on that exempt list. On failure, `--json` also prints an error object to stdout (the message still goes to stderr): ```json theme={"dark"} {"error": "server returned 404: app not found", "code": "not_found", "exit_code": 4, "http_status": 404, "hint": "check the resource name with the matching list command"} ``` `error` is the original field. `code` is one of `validation`, `network`, `unauthorized`, `forbidden`, `not_found`, `conflict`, `rate_limited`, `invalid_request`, `server_error`, `api_error`. `http_status`, `retry_after` (rate limits) and `hint` appear when they apply. Exit codes are stable and shared by every command: | Code | Meaning | | - | - | | 0 | Success | | 1 | Usage error (unknown command, missing argument, bad flag); also a failed check for `control-plane-backups verify` and a critical item for `attention` | | 2 | Validation error: well-formed flags, but the request they describe is invalid | | 3 | Network error: the control plane could not be reached | | 4 | API error: the control plane replied with a non-2xx status (use `code` and `http_status` in the JSON error to tell auth, not found and conflict apart) | | 5 | Deploy failed: `apps wait` reached a failed deploy | | 6 | Deploy timeout: `apps wait` or `apps deploys wait` gave up before the deploy converged | | 7 | `apps deploys wait` ended on a deploy that failed, was canceled, superseded or blocked | Codes 3 and 4 are broad on purpose so existing scripts keep working; the JSON error object carries the finer distinction. ## Scripting: `--debug` `--debug` works anywhere on the command line (before or after the subcommand) and traces every outgoing request this invocation makes to stderr: method, URL, and the response status and timing, one line per call. It never prints request or response headers or bodies, so `Authorization` and any token value never appear, even in debug mode; a token that somehow ended up in a URL's query string is also redacted. stdout is untouched, so `--debug` composes with `--json`/`--query` for scripting. ``` levelrail-cli apps list --debug --api-url http://10.0.0.5:8080 ``` ``` DEBUG: GET http://10.0.0.5:8080/api/v1/apps -> 200 OK (42ms) ``` ## Experimental command groups Some groups are off by default and stay hidden from `--help` and shell completion until the shell you run the CLI from sets `APP_EXPERIMENTAL`. This page marks them. The keys are `ai-chat` (`ai`, `settings ai-assistant`), `ai-models` (`models`), `load-balancer` (`lb`), `iac` (`apply`, `diff`, `export`) and `cloudflare-tunnel` (`cloudflare-tunnel`). See [Experimental features](/experimental-features). ## Web CLI console: host diagnostics The dashboard's CLI console (experimental key `cli-console`) runs the commands on this page against the control plane. It also answers a small `host` namespace itself, inside the control plane process, without starting the CLI or any other program. It is read only and is not a shell. | Command | Shows | | - | - | | `host df` | Disk usage of the data directory and `/` | | `host free` | Memory total, used, available, and swap | | `host uptime` | Time since the server booted | | `host load` | 1, 5 and 15 minute load averages and the CPU count | | `host os` | OS name (`PRETTY_NAME` from os-release), kernel release and architecture | | `host service` | The control plane's version, start time, uptime, goroutines, memory (RSS) and whether a restart supervisor (systemd, Docker) was detected | | `host help` | This list | None of them take arguments: paths, process names, container names and flags are refused. Each line goes through the same step-up, one-command-at-a-time, idle timeout, output cap and audit log (`cli_console.run`) as any other console command. Linux only; other platforms reply "not supported on this platform". Set `APP_CLI_CONSOLE_HOST=off` on the server to turn the namespace off while keeping the rest of the console. ## Top-level convenience aliases ``` levelrail-cli deploy --image IMAGE [flags] ``` Alias for `apps deploy`; deploy an image to an existing app. ``` levelrail-cli rollback --image IMAGE [flags] ``` Alias for `apps rollback`; redeploy an older image. ## Apps `apps list` prints every app the caller can read as a bare JSON array. On a fleet large enough that matters, add `--max-items N` to cap the page size; the response becomes `{"items": [...], "next_token": "...", "total_count": N}` instead, and an empty `next_token` means there is no further page. Pass that `next_token` back in as `--starting-token` to fetch the next page (requires `--max-items`, since the server only pages a result when a limit is set): ``` levelrail-cli apps list --max-items 50 --json levelrail-cli apps list --max-items 50 --starting-token 50 --json ``` Run `levelrail-cli apps -h` for the full flag list of any command below. Deploy lifecycle is covered in [Deploying and managing apps](/deploying-apps). ### Create, inspect and list ``` levelrail-cli apps create --name NAME --image IMAGE --port PORT [flags] levelrail-cli apps create --name NAME --port PORT --repo URL --image-repo REPO [flags] levelrail-cli apps create --file app.yaml [flags] levelrail-cli apps create --interactive levelrail-cli apps list [--max-items N] [--starting-token T] [flags] levelrail-cli apps get [flags] levelrail-cli apps status [flags] levelrail-cli apps overview [name ...] [flags] levelrail-cli apps network [flags] levelrail-cli apps validate --file [flags] levelrail-cli apps clone [flags] levelrail-cli apps delete [flags] ``` * `apps create` registers an existing image or triggers a real build from a git repository; `--file` reads an [app spec](/app-spec-reference), `--interactive` runs a step-by-step wizard. Required flags missing outside `--interactive` fail with an error instead of prompting. * `apps status` shows an app's current reconcile conditions; `apps overview` shows CPU, memory, traffic and errors for every app (or the names given) in one request; `apps network` shows the live traffic path (container port, host port, running). * `apps validate` parses and validates an app.yaml or a Docker Compose file locally, with no API call and no deploy. It prints the detected format, service count, and every non-blocking `notices` entry a real deploy would also surface. * `apps delete` removes an app and stops its containers; if the node is unreachable the delete is reported as pending and retried. ### Deploy, roll back and scale ``` levelrail-cli apps deploy --image IMAGE [flags] levelrail-cli apps deploy-compose --file compose.yaml [flags] levelrail-cli apps deploy-spec --file app.yaml --repo-url --ref [flags] levelrail-cli apps builds trigger --repo URL --ref REF [flags] levelrail-cli apps rollback --image IMAGE [flags] levelrail-cli apps promote --to ENVIRONMENT_ID [--target NAME] [--preview] [flags] levelrail-cli apps wait [--attempt-id ID] [--timeout 5m] [--poll-interval 3s] [flags] levelrail-cli apps restart [flags] levelrail-cli apps apply [flags] levelrail-cli apps stop [flags] levelrail-cli apps start [flags] levelrail-cli apps scale --replicas N [--strategy rolling|recreate|blue-green] [flags] levelrail-cli apps group [flags] levelrail-cli apps hook-runs [flags] levelrail-cli apps images [flags] levelrail-cli apps set-node [--with-volumes] [flags] levelrail-cli apps clear-node [--with-volumes] [flags] levelrail-cli apps moves list [flags] levelrail-cli apps moves get [flags] ``` * `apps wait` polls until a deploy attempt converges and exits 0 on success, 5 if it converged as a failure, 6 on timeout. On success it says what happened: `rolled out`, `already up to date` (the deploy changed nothing) or `restarted`; `--json` carries the same as `outcome`. * `apps deploy-spec` fans an app.yaml's `services:` map out into independent builds under one app; `apps group` shows a service's siblings under the same multi-service app. * `apps builds trigger` builds an image from a git source and deploys it to an existing app. * `apps promote` promotes the app's image onto a sibling app in another environment. * `apps apply` restarts an app so saved env, secret and config changes reach the running container; it does nothing when nothing is pending. * `apps scale` changes the replica count and/or the deploy strategy. * `apps hook-runs` shows the most recent outcome of an app's pre and post deploy hooks; `apps images` lists the locally present image tags under the app's current image repo. * `apps set-node` and `apps clear-node` move an app to another node, or back to the control plane's own local node. With `--with-volumes` the named volumes move too, and `apps moves` shows the history of those moves. ### Deploy history, approvals and automation ``` levelrail-cli apps deploys list [flags] levelrail-cli apps deploys show [deploy-id] [flags] levelrail-cli apps deploys wait [deploy-id] [--timeout 10m] [--poll-interval 2s] [flags] levelrail-cli apps deploys compare --from ID [--to ID] [flags] levelrail-cli apps deploys logs [flags] levelrail-cli apps deploys steps [flags] levelrail-cli apps deploys failed [--since 24h] [flags] levelrail-cli apps deploys cancel [flags] levelrail-cli apps deploys rollback-to [--watch] [flags] levelrail-cli apps deploys gate [deploy-id] [--watch] [flags] levelrail-cli deploy status [deploy-id] [--watch] [flags] levelrail-cli apps deploy-safety show|set|targets [flags] levelrail-cli apps timeline [--limit N] [flags] levelrail-cli apps diagnose [--deploy ID] [--apply-fix N] [flags] levelrail-cli apps preflight [--require-env A,B] [flags] levelrail-cli apps freeze show [flags] levelrail-cli apps freeze set --cron EXPR --duration D [--timezone TZ] [--reason TEXT] [flags] levelrail-cli apps freeze clear [flags] levelrail-cli apps schedule set --cron EXPR --branch NAME [flags] levelrail-cli apps schedule get [flags] levelrail-cli apps schedule history [flags] levelrail-cli apps cancel-superseded enable|disable|status [flags] levelrail-cli apps auto-rollback enable|disable|status [flags] levelrail-cli functions deploy|list|invoke|delete [flags] levelrail-cli jobs list|get|create|update|run|history|logs|enable|disable|delete [] [flags] levelrail-cli apps sleep enable|disable|status|wake [flags] levelrail-cli apps canary start|status|weight|promote|abort [flags] levelrail-cli apps auto-update enable|disable|status|check [flags] levelrail-cli apps auto-rollback-slo-burn set off|auto|dry_run|pause_for_human [flags] levelrail-cli apps auto-rollback-slo-burn status [flags] ``` * `apps deploys list` is real, row per attempt deploy history, newest first. `apps deploys show` prints one attempt (the newest by default) with its structured failure: code, cause, failing step, redacted log excerpt, suggested fix, docs link and retryable. See [Deploy failures](/deploy-failures). * `apps deploys wait` blocks until one deploy is healthy, failed, canceled, superseded or blocked (a freeze window or approval) and prints the result with its failure. Exit 0 healthy, 7 failed, canceled, superseded or blocked, 6 timeout. Without a deploy id it resolves the newest deploy once and follows it by id. * `apps deploys compare` diffs two deploy attempts, or one against the current live state. `apps deploys logs` prints one attempt's full build and log output to stdout. `apps deploys steps` streams the pipeline steps (detecting, building, pushing, deploying) until the attempt ends and exits non-zero if a step failed; an already finished attempt replays only a short summary. * `apps deploys failed` lists every app's latest failed deploy in the window (default set by the server), with the image of its newest good deploy as a rollback target. * `apps deploys cancel` cancels a queued or in-progress deploy before it cuts traffic. `apps deploys rollback-to` redeploys a past succeeded deploy's exact image, pinned by digest or rollback pin, with that deploy's config; `--watch` follows it through the readiness gate. * `apps deploys gate` (alias `deploy status`) prints a release's gate timeline: readiness passes, stable window, cutover, drain, rollback pin and post-deploy watch. `--watch` follows it until the release clears its watch, fails, is rolled back or is replaced. Exit 0 healthy or in progress, 7 failed or rolled back. `apps deploy-safety` shows and overrides the per-app thresholds (`set web --stable-window 20s --auto-rollback false`, `default` clears one) and lists pinned rollback targets. See [Deploy safety](/deploy-safety#readiness-gate). * `apps timeline` shows what happened to an app, newest first: deploys, rollbacks, restarts, env, secret and config changes (key names only, never values), scaling, stop and start. * `apps diagnose` explains a failed deploy or crashloop and can apply a suggested fix with `--apply-fix N`. `apps preflight` runs pre-deploy checks (DNS, ports, disk, image, env). * `apps freeze` manages deploy freeze windows: a window starts at every match of a 5 field cron expression, evaluated in `--timezone` (default UTC), and lasts `--duration`. While one is active, webhook, pipeline and released deploys are held and run when the window ends; a manual deploy needs `apps deploy --override-freeze --override-reason TEXT`. `set` replaces the app's windows with the one given. Fleet-wide windows are under `settings deploy-freeze`. * `apps schedule` configures a recurring redeploy of a branch's latest commit on a cron schedule. * `apps cancel-superseded` lets a newer queued deploy replace older queued ones of the same branch. Only queued deploys are replaced; a deploy that already started building is never canceled automatically. * `jobs` manages an app's scheduled jobs: fresh-container or exec cron jobs with run history, logs, retries and catch-up (see [Scheduled jobs](/scheduled-jobs)). `apps scheduled-tasks` is the older exec-only form of the same resource. * `functions` runs an image as a function: it sleeps when idle, and a request to a sleeping one waits through the cold start (see [Functions](/functions)). * `apps sleep` stops an app after it has had no requests for a set time and wakes it on the next request (see [Sleep when idle](/sleep-when-idle)). * `apps canary` runs a new image beside the app and sends it a share of traffic until you promote or abort it (see [Canary deploys](/canary-deploys)). * `apps auto-update` redeploys an app automatically when its image tag moves to a new digest (see [Image auto-update](/image-auto-update)). * `apps auto-rollback` opts an app into or out of automatic rollback when a crashloop alert fires. `apps auto-rollback-slo-burn` sets how the app reacts when an SLO burn rate alert fires. ``` levelrail-cli deployments list [--status a,b] [--app NAME] [--branch B] [--trigger T] [--environment E] [--since 24h] [--until T] [--q TEXT] [--live] [--pr N] [--limit N] [--cursor C] [flags] levelrail-cli deployments summary [--window 24h] [flags] levelrail-cli deployments watch [flags] ``` Deploys across every app you can read: a filterable newest first list (page size default 50, max 200, with `--cursor` paging), counts by status with failure rate and duration percentiles, and a live event stream (`--json` prints one object per event). ``` levelrail-cli deploy-approvals list [--status pending|all|approved|rejected|expired] [--service NAME] [flags] levelrail-cli deploy-approvals get [flags] levelrail-cli deploy-approvals approve [flags] levelrail-cli deploy-approvals reject [--reason TEXT] [flags] ``` A deploy or promote into an environment tagged protected becomes a pending approval that a different, sufficiently privileged user must approve first; the same user or token that requested it cannot decide it. `list` defaults to pending. `approve` runs the gated deploy or promote now; `reject` leaves the app's desired state untouched. ``` levelrail-cli apps deploy-notify-targets list [flags] levelrail-cli apps deploy-notify-targets create --channel-id ID [flags] levelrail-cli apps deploy-notify-targets delete [flags] ``` Attach an already connected notification channel (see [Channels](#channels)) so a deploy success or failure sends a message there. ### Domains, ports and traffic ``` levelrail-cli apps domains list [flags] levelrail-cli apps domains add ... [--dns auto|off|preview] [--replace] [--wait] [--timeout 2m] [flags] levelrail-cli apps domains remove ... [--remove-dns] [flags] levelrail-cli apps streams list [flags] levelrail-cli apps streams create --container-port N --host-port N [--protocol tcp] [flags] levelrail-cli apps streams delete [flags] levelrail-cli apps egress get [flags] levelrail-cli apps egress set --allow host:port [--allow host:port ...] [flags] levelrail-cli apps egress clear [flags] levelrail-cli apps exec-access enable|disable|status [flags] ``` * `apps domains add` creates the DNS record when a provider is connected (`--dns off` skips it, `--dns preview` shows it); `--wait` prints the go-live steps and exits non-zero when the domain is not live within `--timeout`. See [Add a domain and go live](/domains-and-ingress#add-a-domain-and-go-live). * `apps domains` shows or changes an app's domains; a domain already used by another app is refused and nothing is changed. Per-domain TLS, redirects, WAF and the like are under [Domains](#domains). * `apps streams` forwards a host port to one container port as raw TCP (only `tcp` is supported). A stream change takes effect on the app's next container recreation, such as an image change or `apps restart`. * `apps egress` restricts an app's outbound traffic to the declared `host:port` pairs; with nothing configured, egress is unrestricted. DNS and loopback traffic stay open regardless. * `apps exec-access` is on by default. When disabled, `apps exec` and the interactive terminal are refused whatever abilities the token has. ### Run, logs and metrics ``` levelrail-cli apps exec -- [args...] [flags] levelrail-cli apps logs [flags] levelrail-cli apps metrics --metric NAME [flags] levelrail-cli apps requests [flags] levelrail-cli apps resource-usage [flags] levelrail-cli apps resource-recommendation [flags] levelrail-cli apps cost [flags] levelrail-cli apps health-score [flags] levelrail-cli apps log-drain get [flags] levelrail-cli apps log-drain set --type TYPE --target TARGET [flags] levelrail-cli apps log-drain clear [flags] levelrail-cli apps scheduled-tasks create --schedule CRON [--disabled] -- [args...] levelrail-cli apps scheduled-tasks update --schedule CRON [--disabled] -- [args...] levelrail-cli apps scheduled-tasks list [flags] levelrail-cli apps scheduled-tasks get [flags] levelrail-cli apps scheduled-tasks run [flags] levelrail-cli apps scheduled-tasks delete [flags] ``` * `apps exec` runs a command in the app's container and exits with its real exit code. * `apps logs` searches an app's stored log entries, or streams live with `--follow`. For a capped excerpt see `logs query` under [Logs](#logs). * `apps requests` shows request rate, errors and latency from the ingress; `apps resource-usage` ranks every app by latest CPU, memory and network usage. * `apps resource-recommendation` suggests memory and CPU limits from historical usage; `apps cost` estimates what the app's CPU and memory would cost under reference providers (not a real bill). * `usage report|settings|budgets` shows cost showback and manages prices and budgets, see [usage and cost](/usage-and-cost). `usage report --csv` prints the export. * `advisor findings|summary|apply|dismiss|snooze|restore|enable|disable` drives the beta [resource advisor](/resource-advisor). `advisor apply ID` only previews; add `--yes` to apply. * `apps health-score` gives a synthesized pass, warn or fail readiness verdict across deploy health, security, resilience and observability. * `apps log-drain` forwards container logs to an external HTTP or syslog sink, in addition to the built-in node-local log store. * `apps scheduled-tasks` runs a command inside the app's running container on a cron schedule. The command is a real argv with no shell; put `--` before it when the command takes flags. ### Health probes, volumes and storage ``` levelrail-cli apps health get [flags] levelrail-cli apps health set --probe readiness|liveness (--path PATH | --exec CMD | --preset NAME) [--scheme https] [--host HOST] [--tls-skip-verify] [--follow-redirects true|false] [--expected-status 200-399] [--interval 5s] [--timeout 2s] [--failures 3] [--ready-timeout 90s] [flags] levelrail-cli apps health clear [--probe readiness|liveness] [flags] levelrail-cli apps health discover levelrail-cli apps volumes get [flags] levelrail-cli apps volumes attach --name NAME --path PATH [flags] levelrail-cli apps volumes detach --name NAME [flags] levelrail-cli apps storage set --storage-target-id ID [flags] levelrail-cli apps storage clear [flags] levelrail-cli apps build-cache show |--global levelrail-cli apps build-cache set |--global --target ID [--mode min|max] [--disable] levelrail-cli apps build-cache clear levelrail-cli apps build-cache remove |--global ``` * `apps health set` sets one probe and keeps the other. A probe is an HTTP(S) check or a command run inside the container (exit 0 is healthy). `--preset` fills path, interval, timeout and failures from a shortcut (`healthz`, `health`, `api-health`, `ping`, `status`); explicit flags win. `apps health discover` probes well-known paths and reports what each one did. * `apps volumes` manages named Docker volumes outside a redeploy. The name is lowercase letters, numbers and hyphens starting with a letter; the path is where it mounts in the container. * `apps storage set` attaches a connected bucket as object storage and injects its credentials as `S3_*` env vars at container create time. See [Object storage](/object-storage). * `apps build-cache` configures the BuildKit remote cache on a storage destination. `--global` applies to every app without its own setting. `clear` is bounded per call; run it again while it reports more to delete. A cache problem never fails a build. ### Environment, secrets and Vault ``` levelrail-cli apps env import --file .env [--dry-run] [--keep-existing] [--apply] [flags] levelrail-cli apps env export [--out FILE] [--reveal] [--format dotenv|json] [flags] levelrail-cli apps env get [--reveal] [flags] levelrail-cli apps env diff [flags] levelrail-cli apps secrets list [flags] levelrail-cli apps secrets set [--apply] [flags] levelrail-cli apps secrets set --env-file [flags] levelrail-cli apps secrets delete [--force] [--apply] [flags] levelrail-cli apps secrets lock --locked=true|false [flags] levelrail-cli apps vault-env set --path PATH --key FIELD [flags] levelrail-cli apps vault-env clear [flags] levelrail-cli apps preview-env set --value VALUE [flags] levelrail-cli apps preview-env clear [flags] levelrail-cli apps branch-env list [flags] levelrail-cli apps branch-env set --branch PATTERN --value VALUE [--secret] [flags] levelrail-cli apps branch-env clear [flags] ``` * `apps env import` merges a .env file into an app's plain env vars and prints which keys are new, changed or unchanged. Keys that are already secrets are skipped. It reports how many changes are pending, or restarts the app right away with `--apply`. * `apps env diff` compares two apps' env vars, for example staging against production. Secret values are never read: secrets are compared by key only, and the dashboard has the same comparison on an app's Environment page. * `apps env export` writes env vars as .env text; sensitive and secret keys are written empty with a comment unless `--reveal` is given. `apps env get` prints one variable, masked when sensitive. `--reveal` asks for your password (and authenticator code) at the prompt, never from flags or the environment, and needs a token with `read:sensitive` and `secrets:reveal` plus `APP_SECRET_REVEAL_TOKENS=on` on the server. See [Environment variables and secrets](/environment-and-secrets). * `apps secrets set` sets or rotates one secret's encrypted value and declares the key as secret backed so it is injected; `--apply` restarts the app now. With `--env-file` it bulk imports every key in a .env format file as its own secret. Values are never returned: `list` shows key names and locked state only. `lock` toggles a secret's overwrite guard. * `apps vault-env` declares an env var resolved live from the configured external Vault (see [Vault](#vault)); only the reference is stored. * `apps preview-env` and `apps branch-env` override an env var for previews only. A branch override applies when the preview's own branch matches PATTERN (an exact name or a glob such as `release/*`); `--secret` stores it envelope encrypted. Neither affects the app's own running deploy. ### Source, previews and webhooks ``` levelrail-cli apps git-source get [flags] levelrail-cli apps git-source set --repo-url URL [flags] levelrail-cli apps git-source settings [flags] levelrail-cli apps git-source rotate-secret [flags] levelrail-cli apps git-source delete [flags] levelrail-cli apps webhook-deliveries list [flags] levelrail-cli apps webhook-deliveries replay [flags] levelrail-cli apps previews list [app-name] [flags] levelrail-cli apps previews limits [app-name] [flags] levelrail-cli apps previews enable [flags] levelrail-cli apps previews disable [flags] levelrail-cli apps previews approve --yes levelrail-cli apps previews teardown [flags] levelrail-cli apps previews extend [--hours 24] [flags] levelrail-cli apps previews settings [flags] levelrail-cli previews list|delete|extend|settings|approve ... levelrail-cli apps previews pr-status enable [flags] levelrail-cli apps previews pr-status disable [flags] levelrail-cli apps previews sweep [flags] ``` * `apps git-source` connects a repo for auto deploy on push; `settings` sets push path filters and forge status reporting; `rotate-secret` mints a fresh webhook secret, shown once. * `apps webhook-deliveries` lists recent inbound webhook requests, verified or not. `replay` re-runs a stored delivery's payload and can trigger a real build and deploy. * `apps previews` manages preview environments per pull request, see [Preview environments per pull request](/previews). `previews` is the same command at the top level. `extend` keeps one preview past its TTL; `settings` shows or changes the lifecycle, resource, database and exposure policy. `limits` shows or changes preview caps, fork policy and TTL; `approve` deploys a held fork pull request once; `teardown` removes one PR's preview now; `sweep` tears down every stale preview across all apps now; `pr-status` toggles the PR comment and commit status per preview deploy. ### Supply chain ``` levelrail-cli apps sbom [deploy-id] [--download] [--file PATH] [flags] levelrail-cli apps scan enable [flags] levelrail-cli apps scan disable [flags] levelrail-cli apps scan status [deploy-id] [flags] levelrail-cli apps scan run [deploy-id] [flags] levelrail-cli apps scan gate off|warn|block_on_critical [flags] levelrail-cli apps scan override --reason TEXT [flags] ``` `apps sbom` shows a deploy's software bill of materials (newest deploy with one by default), or prints or saves the raw SPDX or CycloneDX document. Scanning is off by default and needs `APP_BUILD_ATTEST=true` on the server so builds produce an SBOM; a server can refuse every scan with `APP_SCAN_ENABLED=false`. `gate block_on_critical` keeps the previous release serving; `override` lets the next blocked release through once, with a recorded reason. See [Supply chain](/supply-chain). ### Alerts, connections and templates ``` levelrail-cli apps alerts list [flags] levelrail-cli apps alerts create --kind KIND [flags] levelrail-cli apps alerts update --kind KIND [flags] levelrail-cli apps alerts delete [flags] levelrail-cli apps alerts slo [--slo 99.9] [--slo-latency-ms N] ``` `apps alerts create` takes one of these kinds: `threshold` (needs `--metric`, `--comparator`, `--threshold`), `crashloop` (`--restart-count-threshold`, `--restart-window`), `cert_expiry`, `patch_status`, `scheduled_task_failure` (`--scheduled-task-id`, `--restart-count-threshold`), `node_disk_space`, `node_resource_usage`, `node_offline`, `domain_health`, `control_plane_backup_stale`, `log_archive_stale`, `backup_missing` (`--backup-resource-kind database` with `--backup-database-name`, or `volume` with `--backup-volume-name`) and `slo_burn` (`--slo`, optional `--slo-latency-ms`). Mute, schedule and review alerts with the top-level [Alerts](#alerts) commands. ``` levelrail-cli apps connect [--field FIELD] [--env-var NAME] [flags] levelrail-cli apps disconnect [flags] levelrail-cli apps connections list [flags] levelrail-cli apps connections suggest [flags] levelrail-cli apps database set --database-name NAME [--env-var VAR] [--field FIELD] [flags] levelrail-cli apps database clear [flags] levelrail-cli apps save-as-template [--template-name NAME] [--description TEXT] [flags] levelrail-cli apps tag [flags] levelrail-cli apps untag [flags] ``` * `apps connect` connects an app to a managed database and injects its resolved connection value as an env var; unlike `apps database`, an app can have any number of these. `connections list` shows each connection, including whether it resolves to a mesh DNS name (cross node capable) or a container name; `connections suggest` lists databases the app could connect to. `apps disconnect` removes one connection by its env var name. * `apps database set` attaches one already created managed database as the app's connection env var source (default `DATABASE_URL`, field `url`); `clear` detaches it. * `apps save-as-template` derives a compose.yaml from the app's current desired state and saves it as a reusable template. No secret, database or vault backed env value is captured, only the key name. * `apps tag` attaches a tag by name, creating it if new; `apps untag` detaches it. See [Tags](#tags). ### Projects, environments and organizations ``` levelrail-cli apps projects create --name NAME [flags] levelrail-cli apps projects list [flags] levelrail-cli apps projects get [flags] levelrail-cli apps projects delete [--cascade] [flags] levelrail-cli apps projects start [flags] levelrail-cli apps projects stop [flags] levelrail-cli apps projects restart [flags] levelrail-cli apps projects env-get [flags] levelrail-cli apps projects env-set --var KEY=VALUE [--var KEY=VALUE ...] [flags] levelrail-cli apps projects topology [flags] levelrail-cli apps environments create --name NAME [--protected] [flags] levelrail-cli apps environments list [flags] levelrail-cli apps environments update --protected=true|false [flags] levelrail-cli apps environments delete [--cascade] [flags] levelrail-cli apps environments env-get [flags] levelrail-cli apps environments env-set --var KEY=VALUE [--var KEY=VALUE ...] [flags] levelrail-cli apps environments env-diff [flags] levelrail-cli apps environments clone-preview --new-name NAME [flags] levelrail-cli apps environments clone --new-name NAME [--app-rename SOURCE=NEWNAME ...] [--domain SOURCE=D1,D2 ...] [--copy-secret-values] [flags] levelrail-cli apps organizations create --name NAME [flags] levelrail-cli apps organizations list [flags] levelrail-cli apps organizations get [flags] levelrail-cli apps organizations delete [--cascade] [flags] levelrail-cli apps organizations set-project [flags] levelrail-cli apps organizations clear-project [flags] levelrail-cli apps organizations env-get [flags] levelrail-cli apps organizations env-set --var KEY=VALUE [--var KEY=VALUE ...] [flags] levelrail-cli apps set-project [flags] levelrail-cli apps clear-project [flags] levelrail-cli apps set-environment [flags] levelrail-cli apps clear-environment [flags] ``` * A project groups apps and databases; an organization groups projects. Deleting either leaves its members running, simply ungrouped again. * Shared env vars layer in this order: organization, then project, then environment, then the app's own env, each overriding the one before. `env-set` replaces that scope's shared env vars. For per scope secrets see [Shared env](#shared-env). * A protected environment requires `--confirm` (or an interactive yes) on `apps deploy`, `apps rollback` and `apps promote` targeting an app tagged with it, and routes the deploy through [deploy approvals](#deploy-history-approvals-and-automation). * `apps environments clone-preview` shows what cloning would create without applying it; `env-diff` diffs two environments' resolved effective env vars. * `apps projects topology` prints a diagram ready graph of a project's apps, databases and volumes. See [Projects and organizations](/projects-and-organizations). ## Tags ``` levelrail-cli tags list [flags] levelrail-cli tags create --name NAME [flags] levelrail-cli tags delete [flags] levelrail-cli tags apps [flags] ``` Tags are arbitrary labels for organizing and filtering apps, always identified by name. `delete` detaches the tag from every app. `apps` lists every app attached to a tag. Attach one to an app with `apps tag`. ## Pipelines ``` levelrail-cli pipelines list [flags] levelrail-cli pipelines validate [--json] levelrail-cli pipelines save [--name N] [--paths G,...] [--paths-ignore G,...] [--report-status=false] [flags] levelrail-cli pipelines delete [flags] levelrail-cli pipelines run [--ref R] [--sha S] [--input k=v]... [--follow] [flags] levelrail-cli pipelines runs [] [--pipeline N] [--limit N] [flags] levelrail-cli pipelines runs --all [--status S] [--app A] [--trigger T] [--pipeline N] [--limit N] [flags] levelrail-cli pipelines logs [--job KEY] [--follow] [flags] levelrail-cli pipelines cancel [flags] levelrail-cli pipelines approve [--reject] [--comment TEXT] [--approval ID] [flags] levelrail-cli pipelines sync [--repo-truth=true|false] [flags] levelrail-cli pipelines triggers [flags] levelrail-cli pipelines oidc [flags] levelrail-cli pipelines oidc rotate-key [--retire-after D] [flags] ``` * `validate` checks a pipeline file locally with no API call and exits 2 when it has problems. * `save` creates or updates pipelines from one file, or from every file in a repository's pipeline directory. * `runs` lists runs, or shows one run's jobs, steps and approval gates; `--all` lists runs across every app. * `approve` decides approval gates, or releases a run held for approval. * `sync` syncs pipeline files from the repository now, or sets the repository as source of truth. * `triggers` shows why recent git events did or did not start runs. * `oidc` shows whether pipeline jobs can mint OIDC tokens and the JWKS URL to wire to a cloud provider; `oidc rotate-key` rotates the signing key, and the old key stays published until it retires. See [Pipelines](/pipelines) and [Pipeline OIDC](/pipelines-oidc).

Load balancers

Experimental: requires `APP_EXPERIMENTAL=load-balancer`. See [Load balancing](/load-balancing). ``` levelrail-cli lb list [--state balancing|degraded|none] [--search Q] [flags] levelrail-cli lb show [flags] levelrail-cli lb set [--algorithm ...] [flags] levelrail-cli lb clear [flags] levelrail-cli lb status [flags] levelrail-cli lb check [flags] levelrail-cli lb history [--limit N] [flags] levelrail-cli lb upstream --state S [flags] levelrail-cli lb export --format terraform|cdk|cloudformation|caddy|caddy-json [--out FILE] levelrail-cli lb import --file app.yaml [--service S] [flags] ``` * `list` shows every load balancer across apps with upstream health. `set` creates or changes the load balancer and only the flags you pass change; `clear` removes it, back to a single upstream. * `status` is the live upstream table; `check` probes every upstream once, right now; `history` shows recent checks and state changes per upstream; `upstream` sets an upstream active, draining or disabled. * `export` generates an infrastructure as code definition with no cloud API calls; `import` loads the `loadbalancer:` block of an app.yaml. ## Preview Deploy previews are the screenshot or metadata card captured after a deploy, not pull request previews (those are `apps previews`). See [Deploy previews](/deploy-previews). ``` levelrail-cli preview status [flags] levelrail-cli preview enable [--mode metadata|screenshot] [--path /] [--wait-ms N] [flags] levelrail-cli preview disable [flags] levelrail-cli preview capture [flags] levelrail-cli preview prune [--all] [flags] ``` `enable` turns deploy previews on: `metadata` reads the page title and social image with one small request (no browser), `screenshot` (the default here) runs a browser container per deploy and pulls a large image once. `capture` recaptures the current release now; `prune` deletes old previews now, or every preview of the app with `--all`. Previews need the server to run with `APP_PREVIEW_ENABLED=true` (the default). ## Databases ``` levelrail-cli databases create --name NAME --engine ENGINE --version VERSION [flags] levelrail-cli databases create --interactive levelrail-cli databases list [flags] levelrail-cli databases get [flags] levelrail-cli databases status [flags] levelrail-cli databases delete [--force] [flags] levelrail-cli databases start [flags] levelrail-cli databases stop [flags] levelrail-cli databases metrics --metric NAME [flags] levelrail-cli databases logs [flags] levelrail-cli databases slow-queries [flags] levelrail-cli databases schema [--columns] [flags] levelrail-cli databases query --sql "select ..." [--explain] [--write --confirm ] [flags] levelrail-cli databases connect --name --engine --host [--password-stdin] [--test] [flags] levelrail-cli databases adopt --container [--node ] [--list] [--password-stdin] [flags] levelrail-cli databases probe [flags] levelrail-cli databases resource-recommendation [flags] levelrail-cli databases set-resources [--memory 512Mi] [--cpu 0.5] [flags] levelrail-cli databases set-project [flags] levelrail-cli databases clear-project [flags] levelrail-cli databases set-node [flags] levelrail-cli databases clear-node [flags] levelrail-cli databases public-access set [--port N] [--bind-address ADDR] [flags] levelrail-cli databases public-access clear [flags] levelrail-cli databases set-version [flags] levelrail-cli databases major-upgrade --version V [flags] levelrail-cli databases major-upgrades [flags] levelrail-cli databases major-upgrade-rollback [flags] levelrail-cli databases major-upgrade-discard [flags] ``` * `status` shows a database's current reconcile conditions (useful when it exists but is not running yet). * `delete` stops and removes a database but keeps its data volume; `--force` is needed if apps use it. * `slow-queries` lists a Postgres or MySQL database's slow query log. * `schema` lists a SQL database's tables with row estimates and sizes; `query` runs one statement through the control plane, read-only by default. See [Database viewer](/database-viewer). `db` is a short alias for `databases`. * `set-resources` applies memory and CPU limits to an already created database, replacing whatever was set before (a full replace, not a patch). * `public-access set` exposes a database on a host port; `--bind-address` is `private` (the default), `public`, or a literal IP. * `set-version` is a minor or patch image change on the same data. `major-upgrade` is a guarded Postgres major upgrade with a rollback snapshot; `major-upgrades` lists the attempts, `major-upgrade-rollback` restores the pre upgrade data, and `major-upgrade-discard` deletes a rollback snapshot to free disk. See [Managing databases](/managing-databases).

AI models

Experimental: requires `APP_EXPERIMENTAL=ai-models`. See [AI models](/ai-models). ``` levelrail-cli models list [flags] levelrail-cli models get [flags] levelrail-cli models deploy --name NAME --engine ENGINE --model MODEL [flags] levelrail-cli models logs [flags] levelrail-cli models delete [flags] levelrail-cli models restart [flags] levelrail-cli models rotate-key [flags] levelrail-cli models keys list|create|revoke|rotate [flags] levelrail-cli models usage [flags] levelrail-cli models residency --mode M [flags] levelrail-cli models swap-group --group G [flags] levelrail-cli models wake|sleep [flags] levelrail-cli models fit --engine E --model M [flags] levelrail-cli models metrics [flags] levelrail-cli models gpus [flags] levelrail-cli models preflight [flags] levelrail-cli models cache list [flags] levelrail-cli models cache prune [--dry-run] [volume...] [flags] ``` * `deploy` runs a model as a container on a GPU node and prints its API key once. Flags: `--engine` (`ollama`, `vllm` or `llamacpp`), `--model`, `--node`, `--gpus` (a count or `all`), `--gpu-devices`, `--context`, `--quantization`, `--domain`, `--hf-token-from-env`, `--residency` (`always` or `on_demand`), `--idle-ttl`, `--swap-group`. * `logs` searches a model engine's logs, or `--follow` streams download and load progress live. `delete` keeps the downloaded weights volume. `restart` recreates the engine container. * `rotate-key` issues a new API key, printed once; `keys` manages named API keys with limits, expiry and rotation grace; `usage` shows gateway requests, tokens, errors and latency per key. * `residency` sets a model always resident or `on_demand` (stopped when idle, started on first request); `wake` and `sleep` start or stop an on demand engine now; `swap-group` lets models share a GPU (`--clear` removes it). * `fit` estimates VRAM fit on each GPU node; `gpus` lists GPU nodes with VRAM and usage; `preflight` checks a Hugging Face repo (access, size, quantizations, fit, disk); `metrics` shows engine metrics. * `cache list` shows cached model weights per node; `cache prune` removes unused, unreferenced weights (use `--dry-run` first). ## Auth ``` levelrail-cli auth login [--device] [--profile NAME] [flags] levelrail-cli auth whoami [flags] levelrail-cli auth session-link [flags] levelrail-cli auth code [flags] levelrail-cli auth approve --match N [flags] levelrail-cli auth deny [flags] levelrail-cli auth devices [revoke ] [flags] levelrail-cli auth code-login [--admins true|false] [--others true|false] [flags] levelrail-cli auth 2fa status [flags] levelrail-cli auth 2fa setup [flags] levelrail-cli auth 2fa enable --code CODE [flags] levelrail-cli auth 2fa disable --code CODE|--recovery-code CODE [flags] levelrail-cli auth 2fa recovery-codes --code CODE [flags] ``` * `login` authenticates and persists a new API token; with `--profile NAME` it saves under a named profile instead of overwriting `default`. * `login --device --json` prints one JSON line first (`verification_url`, `user_code`, `expires_in`, `expires_at`) so an agent can relay it, then the token resource once approved. See [Attention center](/attention-center). * `session-link` mints a short lived (about 2 minutes), single use login link that signs in as whoever minted it, meant for browser automation. It needs a token with the root ability. * `code` prints the sign-in codes waiting for your account with the requester's IP address, browser and time, plus password sign-ins from new browsers waiting for approval; `approve` and `deny` decide one of those (`approve` needs `--match` with the two digit number the waiting browser shows, typed in; a wrong number denies it, and the number is never printed by `code`), and `devices` lists or revokes browsers trusted for password sign-in. They need a token that belongs to your user. Listing and `devices` accept `write:sensitive`; showing a code and `approve` or `deny` need `signin:approve`, which no device login, root or `write:sensitive` token carries. Mint one from a signed-in session with `levelrail-cli tokens create --name approver --abilities signin:approve --expires-in-days 30` (it must expire within 30 days by default, cannot be an agent token, and is revoked when you change or reset your password or sign out your other sessions), or use the dashboard. `code-login` shows or changes who may sign in with a code (changing it needs root). See [Identity and access](/identity-and-access#sign-in-with-a-code). * Every `2fa` subcommand needs a live session: `--username` and `--password` (prompted if omitted), never the CLI's saved bearer token. `setup` starts enrollment and returns a secret and provisioning URI; `enable` confirms it and returns recovery codes once; `recovery-codes` regenerates them and invalidates the old set. ## Auth engine ``` levelrail-cli auth-engine status [flags] ``` Shows which auth engine is active, the areas served by the library, and the shadow comparison counters with the most recent mismatches. Needs a root token. ## Profile ``` levelrail-cli profile list [flags] ``` List configured credentials profiles and their API URLs. ## Tokens ``` levelrail-cli tokens create --name NAME (--abilities LIST | --preset observer|deployer|operator) [--agent NAME] [--agent-description TEXT] [flags] levelrail-cli tokens list [flags] levelrail-cli tokens revoke [flags] ``` Every `tokens` subcommand requires a username and password (prompted if omitted), because these routes are session only server side and a bearer token cannot call them. `create` mints a new API token; `--agent` labels it as issued to an AI agent so audit entries record the agent name. `list` never shows a secret. ## Domains Per domain settings take ` `, and the domain must already be one of the app's configured domains. Domain TLS and ingress behavior is covered in [Domains and ingress](/domains-and-ingress). ``` levelrail-cli domains list [flags] levelrail-cli domains check [flags] levelrail-cli domains doctor [--json] levelrail-cli domains summary [--json] levelrail-cli domains activity [--limit N] [--before CURSOR] [--actions PREFIXES] [--json] levelrail-cli domains certificates [flags] levelrail-cli domains basic-auth get|set|clear [flags] levelrail-cli domains maintenance get|set|clear [flags] levelrail-cli domains redirect get|set|clear [--target URL] [flags] levelrail-cli domains tls-cert get [flags] levelrail-cli domains tls-cert set --cert-file FILE --key-file FILE [flags] levelrail-cli domains tls-cert clear [flags] levelrail-cli domains tls-cert renew [flags] levelrail-cli domains waf get|set|clear [flags] levelrail-cli domains error-pages get [--code N] [flags] levelrail-cli domains error-pages set --code N (--body TEXT | --body-file PATH) [flags] levelrail-cli domains error-pages clear [--code N] [flags] levelrail-cli domains dns list [flags] levelrail-cli domains dns add --type T --name N --value V [flags] levelrail-cli domains dns remove --type T --name N --value V [flags] levelrail-cli domains go-live [--dns auto|off|preview] [--replace] [--plan] [--wait] [--timeout 2m] [flags] levelrail-cli domains go-live runs [--limit N] [flags] levelrail-cli domains go-live undo [flags] levelrail-cli domains backfill-base-domain [--confirm] [flags] levelrail-cli settings domain-automation get|set [flags] levelrail-cli domains cloudflare-dns get|set|clear [flags] levelrail-cli domains route53-dns get|set|clear [flags] levelrail-cli domains standalone list [flags] levelrail-cli domains standalone add --target TARGET [--confirm] [flags] levelrail-cli domains standalone update [--target TARGET] [flags] levelrail-cli domains standalone remove [flags] ``` * `standalone` manages [standalone domains](/standalone-domains): domains with no app that proxy to `PORT`, `HOST:PORT`, an `http(s)://` URL, `app:NAME[:PORT]` or `container:NAME:PORT`. Options are `--upstream-tls`, `--insecure-skip-verify`, `--tls-server-name`, `--host-header preserve|upstream|NAME`, `--no-websocket`, `--connect-timeout`, `--read-timeout`, `--strip-prefix` and `--description`. Loopback, private, container and control-port targets need `--confirm`. `update` sends only the flags you pass. Per-domain commands take `_standalone` as the app name, for example `domains waf set _standalone tools.example.com`. * `list` shows every app's domains in one call. `check` runs a real DNS lookup and reports whether the domain reaches this control plane. `certificates` lists every certificate in certmagic storage, healthy or not. * `basic-auth set` takes `--username` and `--password`. `maintenance set` serves a fixed maintenance response instead of proxying, without stopping the container. `redirect set --target URL` redirects every request for the domain; maintenance mode takes precedence if both are set. * `tls-cert` uploads an operator supplied certificate and key; `clear` reverts to automatic issuance and `renew` forces re-issuance of an automatic certificate. * `waf` configures the opt-in Web Application Firewall and rate limiting. `--mode` defaults to `detect` (matches are logged, never rejected) rather than `block`. * `error-pages` sets custom HTML for status code 404, 500, 502 or 503; `clear` removes one mapping, or all if `--code` is omitted. * `dns` reads and writes the real A, AAAA, CNAME, TXT, MX, SRV and CAA records in the domain's zone through whichever DNS-01 provider is configured. `remove` must match an existing record exactly. * `cloudflare-dns set --cf-api-token TOKEN` and `route53-dns set --aws-access-key-id ID --aws-secret-access-key KEY` configure the ACME DNS-01 credentials needed for wildcard domains. A domain is wildcard eligible by having a leading `*.` label; if both providers are enabled, Cloudflare takes precedence. ## DNS See [DNS zones and records](/dns). ``` levelrail-cli dns zones list [--provider cloudflare|route53] levelrail-cli dns zones create [--account-id ID] levelrail-cli dns zones nameservers levelrail-cli dns zones verify levelrail-cli dns zones delete --confirm [--force] levelrail-cli dns records list [--type T] [--search S] levelrail-cli dns records add|update --name N --type T --value V [--value V2] [--ttl S] [--proxied] [--routing weighted|failover|multivalue --set-id ID ...] levelrail-cli dns records delete --name N --type T [--set-id ID] levelrail-cli dns records import --file F [--format bind|json] [--apply] [--replace --confirm ] levelrail-cli dns records export [--format bind|json] [--out F] levelrail-cli dns records template