# ox CLI reference: deploy, logs and vars from a shell The ox command line: install it, sign in, and every command for projects, deploys, logs, variables, backups and servers, with --json and its exit codes. The `ox` command does everything the dashboard does, from your terminal: deploy, read logs, roll back, set variables and restore backups. Install it on macOS or Linux, then sign in once with `ox login`. Run `ox help` for the list below, and `ox -h` for one command's flags. New to ox? The [quickstart](https://console.t12.sorv.dev/docs/quickstart) walks through a first deploy. What `ox check` prints for a Fastify app with PostgreSQL and no ox.toml, copied from ox's own tests: each part of the plan, where it came from, the keys ox provides, and `Ready to deploy.` It runs offline, before you sign in. Install and sign in: ```sh curl -fsSL https://deploywithox.com/install.sh | sh ox login ``` ## Flags most commands take - `--json`: prints one JSON document with stable field names. Every ox Cloud command takes it. On a failure, it writes `{"error": "...", "code": "..."}` to standard error. - `--env E`: picks the environment. A command about one project acts on production by default. Add `--env staging` or `--env ` for staging or a preview. - `--server S`: picks the server, when two of your servers have a project with the same name. - `--wait`: streams the run and exits with its result, on a command that starts a run (deploy, rollback, restore and others). JSON for scripts: ```sh ox status shop --json ox deploy shop --env staging --wait ``` ### Exit codes | Code | Meaning | | --- | --- | | `0` | It worked. | | `1` | Something failed. ox refused, the project, run or server was not found, the run you waited on failed, `ox review` still needs answers, or a test run's pictures are gone (`gone`). | | `2` | A command, a flag or an argument is wrong. The message shows the right usage. For a typo, it names the one you likely meant: `did you mean ox deploy?` | | `3` | You are not signed in, or your token expired or was revoked. Run `ox login`. | | `4` | ox Cloud could not be reached. | | `5` | `ox tests run --wait`: the run ended in error, so the tests did not decide (`run_error`). | | `6` | `ox tests run --wait`: the run was skipped, or superseded with no run after it (`run_skipped`). | | `7` | `ox tests run --wait`: the wait ended before the run did. `--timeout` passed (ox may have stopped answering), you stopped it with Ctrl-C, or an answer did not come from ox (`timeout`). | | `8` | `ox tests run --wait`: ox refused. Tests are off, there is no such run, no run was queued within 5 minutes, or the token may not read (`no_run`). | ## Sign in from the terminal **`ox login`** Sign in to ox Cloud. It prints a sign-in address and a code. Type the code there and approve it in the browser. The command waits until you do. Example: `ox login` **`ox logout`** Revoke this machine's token and forget it. Example: `ox logout` ## Project commands: create, list and manage **`ox repos`** The GitHub repositories a new project can be made from. Example: `ox repos` **`ox new [--server S]`** Make a project from a repository, on one of your servers. You need `--server` only when you have more than one. Example: `ox new acme/shop --server web-1` **`ox review [--start CMD] [--generate K] [--skip K] [--from-file F] [--wait]`** Show what a first deploy still needs, answer it, and deploy. Until the project is ready, it exits 1 and says what to answer. `--generate K` makes a random value for a missing variable. It is offered only for a secret your app makes for itself, like `SESSION_SECRET`. A key a service gave you, like `STRIPE_API_KEY`, goes in the file. `--skip K` marks a variable not needed, so your app does not get it at all. `--from-file F` reads values from a .env file. A big repository or a busy server can take minutes to review, and ox asks again until the review ends. Example: `ox review shop --generate SECRET_KEY --wait` **`ox projects`** List your projects with their server and status. Example: `ox projects --json` **`ox status [--wait]`** The live commit, the URL, the processes and the last run. When someone deployed another ref, it also names that ref. For scripts, `--wait` follows the newest run until it ends and exits with its result. Example: `ox status shop` **`ox rename `** Rename a project before its first deploy. Example: `ox rename shop store` **`ox delete --confirm [--wait]`** Delete a project. Type the name again after `--confirm`. Its files go to the trash for 7 days. Example: `ox delete shop --confirm shop --wait` **`ox stop [--wait]`** Stop every process of a project until `ox start`, including a cron run already going. The project gives its `[limits] memory` back to the server, so other deploys can use that room. Its services' memory stays reserved. It stays stopped through deploys, restores and reboots. A deploy of a stopped project ends `left stopped; ox start to run it`, and `ox status` says since when and by which run. If the server's agent is too old for this, ox asks you to update it first with `ox servers update `. Example: `ox stop shop --wait` **`ox start [--wait]`** Start a stopped project. ox first checks that the server has room for it. If another project took the room, the run fails with `The server does not have enough memory` and names what to stop, delete or lower. The project stays stopped. Example: `ox start shop --wait` **`ox autodeploy [on | off | checks on | checks off]`** Show whether every push deploys, or turn that on or off. With `checks on`, a push deploys only once its GitHub checks pass, so your CI decides what goes live. `ox status` says why a commit waits. Example: `ox autodeploy shop checks on` **`ox domains [add D | remove D | primary D] [--wait]`** A project's domains and their DNS. Add one, remove one, or pick the primary one. See [Domains](https://console.t12.sorv.dev/docs/operate/domains). Example: `ox domains shop add shop.example.com --wait` **`ox trash [restore]`** Show a deleted project's variables, or take them back into a new project with `restore`. Example: `ox trash shop restore` ## Staging and previews These commands are listed under Projects in `ox help`. [Staging and previews](https://console.t12.sorv.dev/docs/operate/previews) explains how they fit together. **`ox staging [KEY…] [--from-file F] [--domain D] [--branch B] [--remake --confirm ] [--wait]`** Make the project's staging copy. `--branch B` deploys a branch instead of production's live commit. If the project already has a staging copy, `--branch B` makes the copy track B from now on and deploys it, as the copy's Settings tab does. Use this when the branch it tracked was merged and deleted. Example: `ox staging shop --branch develop --wait` **`ox staging [KEY…] [--from-file F]`** Set staging's own values on the new copy before its first deploy. ox asks for each KEY you name, as `ox vars set` does, so no value goes on the command line. Or give a `.env` file with `--from-file` (`-` reads stdin). A key ox provides is refused. If a test account's email and password variables get no value here, ox makes them: `tester@` at the copy's domain, and a random 24-character password you can read on the copy's Variables tab. Example: `ox staging shop ADMIN_PASSWORD` **`ox staging --remake --confirm -staging`** Delete the staging copy's app and data, make it again with the same name, domain, branch and own values, and deploy it. When tested deploys are on, it also checks sign-in. Use this when `ox tests ` says staging's app was set up before a test account's variable got its own value. The audit log records a delete and a deploy. Example: `ox staging shop --remake --confirm shop-staging` **`ox previews [on | off | start BRANCH | remove BRANCH | --branches all|PATTERNS | --at-once N]`** Branch previews. With no action, it lists them with their state, commit, last deploy and memory, and why a failed one failed, with its fix. The actions turn previews on or off, preview a branch now, remove one, choose which branches get one, or set how many run at once. Example: `ox previews shop --branches feature/*` **`ox environments `** A project's production, staging, and previews. Example: `ox environments shop` **`ox promote [--yes] [--wait]`** Deploy production at the commit staging runs. It shows the commits and asks first. `--yes` skips the question, and you need it when no terminal can answer. Example: `ox promote shop --yes --wait` **`ox protect --env E [on | off | default] | protect --account [on | off] [--new-password]`** Password-protect staging and previews, for one environment or as the account's default. `--new-password` makes a new password. Example: `ox protect shop --env staging on` **`ox keep --env [on | off]`** Keep a preview from the 7-day cleanup. Example: `ox keep shop --env feature/cart on` ## Deploy, roll back and read runs **`ox deploy [--ref R] [--wait]`** Deploy a branch or commit. Without `--ref`, it deploys the project's branch. `--wait` streams the run, and a failure ends with what failed and how to fix it. With auto-deploy on, another ref stays live until the next push to the project's branch, and `ox status` names it. Example: `ox deploy shop --ref main --wait` **`ox exec [--secret KEY]... ""`** Run one line of bash against the live release. It runs as the project's user, with its variables, in the same sandbox as its cron jobs. It has no terminal and no stdin, so pass the command's non-interactive flag. The log streams like `deploy --wait`. ox exits 1 when the command failed, and `--json` has its `exit_code`. The command stops after 10 minutes. The first Ctrl-C stops the command, and a second one only stops watching. Needs a full access token. `--secret KEY` asks for a value without showing it, or reads one line per key from stdin. Never put a secret in the command itself, because the audit log shows the command as typed. Example: `ox exec shop --secret DJANGO_SUPERUSER_PASSWORD "python manage.py createsuperuser --noinput"` **`ox rollback [--release ID] [--restore-variables] [--wait]`** Go back to a kept release, by default the newest one that is not live. `--restore-variables` also brings back the variables that release ran with. See [Roll back](https://console.t12.sorv.dev/docs/operate/rollback). Example: `ox rollback shop --wait` **`ox runs `** The project's runs, newest first. Example: `ox runs shop` **`ox crons [run NAME]`** Cron jobs with their schedules and their next and last runs. `run NAME` runs one now. Example: `ox crons shop run clearsessions` **`ox celery `** A Celery worker's app: the workers online, the tasks and the queues. Example: `ox celery shop worker` **`ox logs [--run ID] [--follow] [--since T] [--until T] [--grep TEXT | --regex RE] [--query Q] [--process P] [--severity S] [-n N] [-o FILE]`** Read and search the processes' logs, or one run's log. `-n` is 100 lines by default. `-o FILE` saves everything that matches, up to 100 MB. `--query` takes the log explorer's query, like `'level:error -healthcheck'`. `--run ID` prints how the run ended (a failure and its fix), then the run's whole log. It does not go with `-n`. `--run ID --follow` prints a run's log as it runs and exits with its result, like a deploy with `--wait`. See [Logs](https://console.t12.sorv.dev/docs/operate/logs). Example: `ox logs shop --since 2h --severity error` **`ox metrics [] [--server S] [--range 1h|24h|7d|30d | --since TIME [--until TIME] | --at TIME]`** CPU and memory of a project or a server, with deploys and alerts. The range is 24h by default, and goes from an hour to a month. Example: `ox metrics shop --range 7d` ## Tested deploys: the AI tester `ox tests` is the console's Tested deploys card, in a terminal. An AI tester uses each pull request's preview as a user would, and production waits while a check is red. `ox tests shop start` turns tests on for a project. ox first turns on branch previews and makes staging, as each is needed. If something only you can fix is open, it lists it and changes nothing. Name the project, then the action. With no action, it prints the setting, the testing credit, how signed-in testing works, GitHub's status, the held commit, the queue and the last runs, in the console's words. Every action takes `--json`, with stable field names and the API's own values, which never change. For example, a paused check's `state` is `quarantined`, the Reporting setting's `mode` is `report`, and Holding's is `on`. The token you need depends on the action: - A read works with any token, a read only one included, so a coding agent can wait for a run and read what failed. - `again`, `not-a-bug` and `undo-not-a-bug` need a token with deploy access. A token's Not a bug always carries a reason, which the owner sees beside the token's name. - Every other action that changes something, `deploy-anyway` included, needs full access. So an agent that pushes and waits cannot ship a held commit. **`ox tests [ACTION …]`** The actions, grouped as `ox tests -h` groups them. The setting. `start` tests pull requests. The first time for your account, it asks you to agree that each run sends the pull request and its preview's pages to an open-source AI model. `--yes` agrees, and start needs it when there is no terminal. `hold on` or `hold off` says whether a red check holds the deploy, and `off` turns tests off. `about TEXT` or `about --clear` says what your users do here, in up to 500 characters as one quoted argument. `record (on | off)`, `recordings`, `recording get ID [-o FILE]` and `recording delete ID` keep, list, save and delete [videos of runs](https://console.t12.sorv.dev/docs/operate/tests#recordings). `-o` names the file, and never overwrites one that is there. `install` installs the test browser again on the servers of staging and the previews after an install failed, as Try again does on the card. Tests that sign in. `signin` says how it works, and `signin check` proves it again. `accounts` lists the test accounts (at most 4). `accounts set SPEC` makes or replaces the account of that name. Staging then gets its own value for each account variable it lacks, and redeploys. `accounts clear` removes them all. `signin-helper [COMMAND | --clear]` shows whether a sign-in helper is set, sets it or removes it. `keys` lists the preview variables that still hold production's value, each with its shape and what to do, and `keys confirm KEY` marks one test-only. Runs: `runs`, `run`, `stats`, `again [--branch B]` (staging without it), `whole-app --confirm P` and `artifacts RUN DIR`. `whole-app` tests the whole app on staging. You type the project's name again because it uses your testing credit. A red check: `not-a-bug`, `undo-not-a-bug` and `deploy-anyway`. Saved checks. `checks` lists them, and `check NAME` shows one with its code and history. `pause CHECK --reason R` stops one from holding deploys, and `resume CHECK` lets it hold them again. `save WALKTHROUGH` and `dismiss WALKTHROUGH` keep or drop a walkthrough the whole-app run offered. `SPEC` is `name=NAME,role=ROLE`, one of `email=ADDRESS`, `email-var=VAR`, or, for an app that signs in by user name, `user=NAME` or `user-var=VAR`, and `password-var=VAR`. `email-var`, `user-var` and `password-var` take a bare variable name that matches `^[A-Z][A-Z0-9_]*$`, never a value and never a `$`. ox refuses any other text before it sends anything, so a shell never expands a secret into the command. Example: `ox tests shop accounts set name=admin,role=admin,email-var=ADMIN_EMAIL,password-var=ADMIN_PASSWORD` **`ox tests runs [--branch B] [--limit N]`** The runs, newest first: 20 by default, at most 100. Example: `ox tests shop runs --branch fix-signup` **`ox tests run (ID | --branch B [--commit C]) [--wait] [--timeout D]`** Show one run. `--branch B` picks the branch's newest run, and `--commit C` (7 to 40 hex characters) the newest run of that push. It prints the summary in its four blocks, then for each check: its class, its finding (what a user hits, or why the check does not count), the error, expected and received, the failing step's line, and the page's text at the failure (8 KiB, redacted). It also prints the paths reached, what the AI says it covered and did not, the pull request's text it read, the bounds and what was used, who marked what Not a bug, and the checks the pull request updated. `--wait` blocks until the run ends and writes a line to standard error at each state change. With `--branch`, it waits up to 5 minutes for the run to be queued. With `--commit`, that is the push's run. Without it, only a run queued after the wait began counts, because right after a push the branch's newest run is still the previous push's. A superseded run is followed to the run that replaced it, with a note, again waiting up to 5 minutes for that run to be queued. If ox fails or cannot be reached during the wait, the command asks again until `--timeout`. `--timeout` is a time such as `2h` (default 90 minutes). With `--json`, the run's `state` is on standard output whenever a run was found, whatever the exit code. Example: `ox tests shop run --branch fix-signup --commit "$(git rev-parse HEAD)" --wait --json` **`ox tests stats`** The health of the tests over the newest 50 runs that ended. For each kind of run, it counts how many passed, failed, were skipped, could not finish or were replaced, with their cost. It counts how many reds stood, were marked Not a bug or were set aside by ox. It gives the median and 90% time to a verdict, and the AI's cost. It lists the 5 checks that fail most, each with where it failed last (run, branch, step and line, error), and the most common reasons a run did not test its change. A run with a red that stands ends with `Next:` and the commands that answer it. `ox tests ` shows each red of the run that holds production. Example: `ox tests shop stats --json` **`ox tests not-a-bug RUN (CHECK | --all) --reason R`** Mark a red check Not a bug, or every red of the run with `--all`, so the commit ships. If the red is a bug, push a fix instead. The reason is required, 1 to 200 characters. Only a click in the console may leave it out. A deploy token may mark and undo, so a coding agent can do it. Each mark shows the token's name and the reason on the run's page, in `ox tests run ID`, in the Kept Not a bug list and in the audit log, so you can see and undo it. When ox can recognize the result again (`matchable` in a run's `--json` check), the merge keeps the mark for the project. A later red with that exact result on any branch then reads "matches Not a bug". `ox tests ` lists the kept marks as `kept_not_a_bug`, each with its `mark`, `state` and `where`. A run check's `not_a_bug` has `mark`, `kept` and `state`. `undo-not-a-bug MARK` flags that result again from the next run. `deploy-anyway [--head SHA] --reason R` lets a held commit with no red to judge ship untested, once. Without `--head`, ox shows the held commit and uses it. With `--json`, you must name it, so a newer push is never deployed by mistake. A commit held by a red is refused (`has_red`). Use `not-a-bug` for that. **`ox tests artifacts RUN DIR`** Save each failed check's picture as `DIR/.png` (PNG, at most 256 KiB, 5 per run). A file that is already there is never overwritten. ox keeps the pictures for 30 days. After that, the command exits 1 with the code `gone`. ### For a coding agent With a deploy token, an agent pushes, then runs `ox tests shop run --branch fix-signup --commit SHA --wait --json`. `run --wait` exits 0 when the run passed (Not a bug included) and 1 when it failed (`run_failed`). The other codes are in the table above: 5 or 6 mean the tests did not decide, 7 that the wait ended first, and 8 that nothing was asked of them. On exit 1, read `.checks[]` where `result` is `red` (`.finding`, `.error`, `.expected`, `.received`, `.step_line`, `.page_text`). Run `ox tests shop artifacts RUN ./shots` for the pictures. A red the change caused is a bug: fix it, push and wait again. Mark a red Not a bug only when the pull request's own intended change explains it (the check expected the old behavior), or when the evidence shows the check is at fault. Name why with `--reason`. Mark one check at a time unless every red has the same cause, and say in the pull request what was marked. ## Variables and services commands **`ox vars [--reveal] | vars set [KEY…] [--generate KEY] | vars unset|import|pull|history|restore|sync … [--no-deploy] [--wait] | vars production-only KEY… [--off]`** Variables: the table, set, unset, import, pull, history, restore, sync and production-only. The verb comes before the project. A save redeploys unless you add `--no-deploy`. See [Variables](https://console.t12.sorv.dev/docs/operate/variables). `ox vars set` takes only key names and asks for each value, so no value lands in your shell history. `--generate KEY` has your server make a random value in the key's well-known format, such as Laravel's `APP_KEY` or `SECRET_KEY_BASE`. It refuses a key that already has a value. While the project's review runs, ox asks again until it ends. On a staging copy or preview, the table names each value that still points at production's address, and the reference to use instead. `ox vars production-only shop KEY` keeps a live key out of new staging copies and previews, and out of `sync`. A new preview takes staging's own value instead. A copy still holding production's value loses it and redeploys. `--off` copies the key into new copies again (see [Keep a secret out of staging and previews](https://console.t12.sorv.dev/docs/operate/variables#production-only)). Example: `ox vars set shop STRIPE_KEY` **`ox services [--reveal]`** The project's service entries, with their type, mode, version, state and keys, and their backups, newest first (the same list as `ox backups`). Example: `ox services shop` ## Data commands: backups, restore, explore **`ox backups [now | download [--output F]] [--wait] | backups key [--json]`** List a project's backups, back up now, or download one. `backups key` prints your backup key, which opens the encrypted copies in your S3 bucket. See [Backups](https://console.t12.sorv.dev/docs/operate/backups). Example: `ox backups shop now postgres --wait` **`ox restore (--from SOURCE | --file F) --confirm [--wait]`** Replace a service entry's data from a backup or a file. `--from` takes the SOURCE column of `ox backups`. `--file` uploads a dump of up to 95 MB. With `--env`, `--confirm` takes the environment's own name, so a restore meant for staging can never be confirmed for production. Example: `ox restore shop postgres --from backup:daily-20261007T030000Z.dump --confirm shop --wait` Example: `ox restore shop postgres --env staging --from backup:daily-20261007T030000Z.dump --confirm shop-staging --wait` **`ox data [drop --confirm ] [--wait]`** List the data of services no longer in ox.toml, or drop it for good. Example: `ox data shop drop redis --confirm redis` **`ox explore [tables | keys [PATTERN] | table NAME | key KEY | command BUTTON | query [--from-file F] [--confirm ] | activity | allow-changes [off] | change ACTION NAME [ARG] [--confirm ] [--cursor C]`** Look into a Postgres, Redis, Neo4j or Qdrant service: browse, query and see activity (read-only until you allow changes). `--cursor` continues a long listing. The audit log records each time changes are turned on or off. With changes allowed, `query --confirm ` runs one Postgres statement read-write and commits it. The audit log records the statement with its values taken out, and the rows it changed. Example: `ox explore shop postgres tables` ## Server commands **`ox storage [] [--server S]`** Where a server's disk went, or a project's share of it. Example: `ox storage --server web-1` **`ox servers [add [--github-keys] | check | restart [--yes] | forget --confirm | move --to --confirm | cancel | update ]`** List your servers, or act on one. `add` prints the command to run on the new server. The server needs your SSH key on it, because ox turns password login off. With `--github-keys` the command puts your GitHub account's SSH keys on the server for the user `ox_user` instead, and lists each key by its type and fingerprint (`login_keys` in `--json`). `check` checks a server now. `restart` restarts one, and `--yes` answers its question. The server and its projects are down for about a minute. A server that needs a restart says so in `check` and on its page. `forget` removes a server from your account, `cancel` cancels an unused add, and `update` updates a server's agent now. `move` moves the projects of a server that is gone for good to another, connected one (`--to`). Then, for each project, add the new deploy key it prints if the project clones over ssh, set the project's variables, deploy it, and restore its data from your bucket. Under the list, ox names each server whose agent is older than ox's current build. ox updates it once ox's own servers have run that build for a day, and `ox servers update ` does it now. ox also names a server that rolled back its last update, with the reason (`rolled_back` in `--json`). An Add server command still waiting shows why its last run on a server failed, as `Last try