ox CLI reference: deploy, logs and vars from a shell

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 <command> -h for one command's flags. New to ox? The quickstart walks through a first deploy.

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 <branch> 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).

ox status shop --json
ox deploy shop --env staging --wait

Exit codes

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 <owner/repo | URL> [--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 <project> [--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 <project> [--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 <project> <new-name>

Rename a project before its first deploy.

Example: ox rename shop store

ox delete <project> --confirm <project> [--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 <project> [--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 <project> 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 <server>.

Example: ox stop shop --wait

ox start <project> [--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 <project> [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 <project> [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.

Example: ox domains shop add shop.example.com --wait

ox trash <project> [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 explains how they fit together.

ox staging <project> [KEY…] [--from-file F] [--domain D] [--branch B] [--remake --confirm <copy>] [--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 <project> [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 <project> --remake --confirm <project>-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 <project> 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 <project> [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 <project>

A project's production, staging, and previews.

Example: ox environments shop

ox promote <project> [--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 <project> --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 <project> --env <branch> [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 <project> [--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 <project> [--secret KEY]... "<command>"

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 <project> [--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.

Example: ox rollback shop --wait

ox runs <project>

The project's runs, newest first.

Example: ox runs shop

ox crons <project> [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 <project> <worker>

A Celery worker's app: the workers online, the tasks and the queues.

Example: ox celery shop worker

ox logs <project> [--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.

Example: ox logs shop --since 2h --severity error

ox metrics [<project>] [--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 <project> [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. -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 <project> 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 <project> 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 <project> 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 <project> shows each red of the run that holds production.

Example: ox tests shop stats --json

ox tests <project> 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 <project> 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 <project> 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 <project> artifacts RUN DIR

Save each failed check's picture as DIR/<check>.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 <project> [--reveal] | vars set <project> [KEY…] [--generate KEY] | vars unset|import|pull|history|restore|sync <project> … [--no-deploy] [--wait] | vars production-only <project> 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.

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).

Example: ox vars set shop STRIPE_KEY

ox services <project> [--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 <project> [now <entry> | download <entry> <source> [--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.

Example: ox backups shop now postgres --wait

ox restore <project> <entry> (--from SOURCE | --file F) --confirm <project> [--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 <project> [drop <entry> --confirm <entry>] [--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 <project> <entry> [tables | keys [PATTERN] | table NAME | key KEY | command BUTTON | query [--from-file F] [--confirm <entry>] | activity | allow-changes [off] | change ACTION NAME [ARG] [--confirm <entry>] [--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 <entry> 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 [<project>] [--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 <server> | restart <server> [--yes] | forget <server> --confirm <server> | move <lost server> --to <server> --confirm <lost server> | cancel <id> | update <server>]

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 <server> 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 <time>: <reason> (last_failure in --json).

Example: ox servers add

Account

ox tokens [create --access A [--name N] | revoke <id | name>]

List, make or revoke personal tokens. --access says what a token can do. read sees projects, runs, logs and status. deploy can also deploy, roll back and mark a check Not a bug, and is the one for CI and coding agents. full can do everything your account can do. --name says what the token is for.

Example: ox tokens create --name ci --access deploy

ox sessions [revoke <id> | revoke --others]

The browsers signed in to your account, as Settings, Sign-in and tokens shows them: an id, the browser, its address, when it signed in and when it was last active. The one you are using is marked. revoke <id> signs that browser out. revoke --others signs out every browser but this one. A token has no browser of its own, so when you run it with a token, it signs out all of them. A browser also signs out by itself 30 days after it signed in. The audit log records each sign-out.

ox audit [--project P] [--action A] [--limit N] [--page N]

The account's audit log, newest first, as Settings shows it: when, who, the action, what it was on, and from which address. --project keeps one project's rows. Name a staging copy or preview by its own name, such as shop-staging. --action keeps one action, such as "explore write". --limit sets the rows per page (25 by default, at most 100), and --page turns to older ones. The log covers the whole account, so it takes no --env or --server.

Example: ox audit --project shop --limit 50

ox plan [upgrade [--yearly] | manage | cancel [--yes] | keep | keep-free [<server>/]<project> | usage [--limit N] | credit]

Your plan, Free or ox Pro, with the project that keeps deploying on Free and the ones paused. upgrade prints the link to pay for ox Pro: $10 a month, or $80 a year with --yearly. manage prints the link to change your card, get invoices, or cancel. Payments are not refunded.

cancel stops ox Pro when the paid month or year ends, or at once when its payment failed. It asks first (--yes without a terminal). keep undoes a cancel before then. keep-free picks the project that keeps deploying on Free. Until you pick, it is your oldest. On ox Pro, this matters only once ox Pro ends.

usage prints your testing credit, its top-ups and the runs that used it (100 by default, at most 1000, with --limit). credit prints the terms and the link to add USD 100 of testing credit, which is paid at cost and is not refunded.

Example: ox plan upgrade

ox account [export [-o FILE] | delete]

Download everything ox holds about you. delete prints the link to Delete account in Settings: an account is deleted only in the console, after a GitHub sign-in of the last 15 minutes, so a stolen token can't delete it. Your apps keep running after you delete it. The ox agent on each server removes itself and leaves /etc/ox/LEFT.txt, and the page lists each server (how to leave).

Example: ox account export -o ox-account.json

ox settings [s3 | huggingface | preview-domain | theme | transparency | times] ...

Account settings: the S3 backup target, the Hugging Face token, the preview domain, the dashboard's look, and the time zone for every time ox shows. The time zone is UTC by default, this device's zone, or a zone such as Europe/Berlin. Secrets come from a file or standard input with --from-file, never as an argument.

Example: ox settings preview-domain preview.example.com

Notifications and webhooks

These commands are listed under Account in ox help.

ox notifications [--project P] [preset problems|everything|nothing | on EVENT... | off EVENT... [--channel email|ENDPOINT] | email on|off | use-account | test]

Choose what reaches your email and each webhook, for the account or one project, and send a test email. preset picks Only problems (recommended), Everything or Nothing for one channel. on and off change single events. --channel picks email or a webhook endpoint.

Example: ox notifications preset problems --channel we_1a2b

ox webhooks [list | add (- | --from-file F) | edit ID | remove ID --confirm ID | rotate ID | test ID [--event TYPE] | deliveries ID [--failed] | redeliver ID MSG | redeliver-failed ID [--since T] | enable ID | disable ID | event-types]

Manage the endpoints that get your events as signed webhooks: add, filter, test, rotate and redeliver. ox reads the address from standard input or a file, never an argument, because it may carry a secret.

Example: echo https://example.com/hook | ox webhooks add - --events deploy.failed

On your server

Run these on the server itself, as root. They do not take --json unless the line says so.

ox install --agent URL --token-file F

Make this host an ox Cloud server. The Add server command runs it.

Example: curl -fsSL https://deploywithox.com/install/<token> | sudo bash

ox install --check

Only check that this host can take ox: ports 80 and 443 free, IPv4 internet access, 1 GB of memory and 10 GB of disk.

Example: sudo ox install --check

ox agent

The ox agent. ox install starts it, so you do not run it by hand.

Example: sudo systemctl status ox-agent

ox leave

Remove only the ox agent: its service, its binary and its link to your account. Your apps, their data, Caddy and the databases keep running as they were, and nothing manages them after this. /etc/ox/LEFT.txt says where everything is. It also says how to switch Caddy from ox's build, which nothing updates after this, to the packaged one, and points to Caddy's apt source so apt upgrade updates it (Keep Caddy updated).

The Add server command adds the host to ox again once no app is left on it. While apps are left, it refuses and names them. sudo ox uninstall deletes them too.

Example: sudo ox leave

ox uninstall

Remove everything ox added to this host. That deletes every project on it, with its app, databases, services and the backups kept on this server. Download your backups and copy anything else you need off the server first (how to leave). The security settings stay. It asks first, and --force or -y skips the question.

Example: sudo ox uninstall

ox doctor

Check the host and name each problem's fix. --json prints the findings as JSON, and --inventory prints everything ox could own on this host.

Example: sudo ox doctor --json

Anywhere

ox check [dir]

Validate a repo's ox.toml and print its resolved plan (offline). --json prints the result as JSON.

Example: ox check --json .

ox version

Print the ox version.

Example: ox version

ox help

Show the list of commands.

Example: ox help