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. New to ox? The quickstart walks through a first deploy. Run ox help for the list below, and ox <command> -h for one command's flags.

curl -fsSL https://deploywithox.com/install.sh | sh
ox login

Flags most commands take

• --json: every ox Cloud command takes it and prints one JSON document with stable field names. On a failure it writes {"error": "...", "code": "..."} to standard error.
• --env E: a command about one project acts on production by default. Add --env staging or --env <branch> for staging or a preview.
• --server S: when two of your servers have a project with the same name, say which one.
• --wait: on a command that starts a run (deploy, rollback, restore and others), stream the run and exit with its result.

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

Exit codes

Sign in from the terminal

ox login

Sign in to ox Cloud with a code you approve in the browser. It prints the sign-in address and a code to type there, then waits until you approve it.

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 a server. --server is needed 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]

What a first deploy still needs; answer it and deploy. Until it is ready it exits 1 and says what to answer. --generate K makes a random value for a missing variable (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 it not needed (your app does not get it at all), and --from-file F reads values from a .env file.

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]

Live commit (and the ref it came from, when someone deployed another ref), URL, processes, and the last run. --wait follows the newest run until it ends and exits with its result, for scripts.

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; its files go to the trash for 7 days. Type the name again after --confirm.

Example: ox delete shop --confirm shop --wait

ox stop <project> [--wait]

Stop every process of a project until ox start, a cron run already going included. 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. A server whose agent is older than that is asked to update first (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, names what to stop, delete or lower, and 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: your CI decides what goes live, and 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 or remove one. See Domains.

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

ox trash <project> [restore]

The deleted project's variables a new project can take back.

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. On a project that already has a staging copy, --branch B makes the copy track B from now on and deploys it (the same as the copy's Settings tab), which is the fix when the branch it tracked was merged and deleted.

Example: ox staging shop --branch develop --wait

ox staging <project> [KEY…] [--from-file F]

Staging's own values, set on the new copy before its first deploy: each KEY named is asked for as ox vars set asks (never on the command line), or --from-file gives a .env file (or - for stdin). A test account's email and password variable that gets no value here gets one ox makes: tester@ at the copy's domain, and a random 24-character password you can read on the copy's Variables tab. A key ox provides is refused.

Example: ox staging shop ADMIN_PASSWORD

ox staging <project> --remake --confirm <project>-staging

Delete the staging copy's app and data, and make it again with the same name, domain, branch and own values, then deploy it (and check sign-in when tested deploys are on). It is the fix when ox tests <project> says staging's app was set up before a test account's variable got its own value. Audited as 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: list them at a glance (state, commit, last deploy, memory, and why a failed one failed, with its fix), turn on or off, preview a branch now or remove one, choose which branches, or 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 it is required 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; --wait streams the run, and a failure ends with what failed in plain words and how to fix it. Without --ref it deploys the project's branch. 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, as the project's user, with its variables, in the same sandbox as its cron jobs. It has no terminal and no stdin, so give a command that asks its non-interactive flag. The log streams like deploy --wait, and ox exits 1 when the command failed; --json has its exit_code. It stops after 10 minutes. The first Ctrl-C stops the command, a second one only stops watching. --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: the audit log shows the command as typed. Needs a full access token.

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: schedules, next and last runs; run one now.

Example: ox crons shop run clearsessions

ox celery <project> <worker>

A Celery worker's app: workers online, tasks, 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]

The processes' logs, their history and search, or one run's log. --run ID prints the run's whole log, and -n doesn't go with it. --run ID --follow prints a run's log as it runs and exits with its result, like a deploy with --wait. --query takes the log explorer's query, like 'level:error -healthcheck'. -n is 100 lines by default, and -o FILE saves everything that matches, up to 100 MB. See Logs.

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

ox metrics [<project>] [--server S] [--range 1h|24h|7d|30d | --at TIME]

CPU and memory of a project, or of a server, over the last hour to month, with deploys and alerts. The range is 24h by default.

Example: ox metrics shop --range 7d

Tested deploys: the AI tester

ox tests is the Tests card of the console, in a terminal: an AI tester uses each pull request's preview as a user would, and production waits while a check is red. Tested deploys are a beta: turn them on for your account first (ox settings beta tested-deploys on), then for a project. Name the project, then the action; with none it prints the setting, the testing credit, how signed-in testing works, GitHub's status, the held commit, the queue and the last runs. Every action takes --json with stable field names; there mode is the project's own setting, beta_on whether your account has tested deploys on, and active whether tests run (both on). 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 needs a token with deploy access, and every other action that changes something needs full access, so an agent that pushes and waits cannot clear its own red.

ox tests <project> [(on | report) [--accept-data-sharing] | off | about (TEXT | --clear) | users [COMMAND | --clear] | accounts [set SPEC | clear] | keys [confirm KEY] | signin [check] | runs [--branch B] [--limit N] | run (ID | --branch B [--commit C]) [--wait] [--timeout D] | checks | check NAME | again [--branch B] | whole-app --confirm P | not-a-bug RUN (CHECK | --all) [--reason R] | undo-not-a-bug MARK | quarantine CHECK --reason R | restore CHECK | save JOURNEY | dismiss JOURNEY | deploy-anyway [--head SHA] --reason R | artifacts RUN DIR]

The actions: on, report and off are the setting (on and report need --accept-data-sharing the first time, which agrees that the AI tester reads your pull requests and previews); about TEXT or about --clear is what your users do here (up to 500 characters, one quoted argument); users shows whether a sign-in helper is set, sets it with a command or removes it with --clear; accounts lists the test accounts (at most 4), accounts set SPEC makes or replaces the one of that name (staging gets its own value for each account variable it lacks, and redeploys) and accounts clear removes them all; 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; signin says how signed-in testing works and signin check proves it again; checks and check NAME read the saved checks, one with its code and history; again checks a branch again (--branch B, staging without it); whole-app --confirm P tests the whole app on staging, and you type the project's name again because it uses your testing credit; quarantine CHECK --reason R and restore CHECK pause and resume a saved check, and save JOURNEY and dismiss JOURNEY keep or dismiss a walkthrough the whole-app run offered. ox tests -h prints each machine name beside the console's plain word for it (report is "tell me, never hold", flaky is "unstable").

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]

One run: the summary in its four blocks, each check's class, finding (what a user hits, or why the check does not count), error, expected and received, the failing step's line, the page's text at the failure (8 KiB, redacted), 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. --branch B is the branch's newest run, and --commit C (7 to 40 hex characters) the newest run of that push. --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 push's run, and without it only a run queued after the wait began, because right after a push the branch's newest run is still the previous push's. It follows a superseded run to the run that replaced it and says so, waiting up to 5 minutes for that run to be queued. A plane that fails or cannot be reached during the wait is read 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> not-a-bug RUN (CHECK | --all) [--reason R]

Every red asks one question: bug? Push a fix. Not a bug? Mark it. This marks a red check, or every red of the run, so the commit ships. The reason is optional, up to 200 characters. When ox can recognize the result again (matchable in a run's --json check), the merge keeps the mark for the project, and a later red with that exact result on any branch reads "matches Not a bug". ox tests <project> lists the kept marks (kept_not_a_bug, each with its mark, state and where; a run check's not_a_bug has mark, kept and state), and 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, and with --json you 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.

ox tests <project> artifacts RUN DIR

Save each failed check's picture as DIR/<check>.png (PNG, at most 256 KiB, 5 a run). A file that is already there is never overwritten. The pictures are kept 30 days, then the command exits 1 with the code gone.

For an agent with a deploy token: push, then ox tests shop run --branch fix-signup --commit SHA --wait --json. On exit 1 read .checks[] where result is red (.finding, .error, .expected, .received, .step_line, .page_text) and run ox tests shop artifacts RUN ./shots for the pictures; fix, push and wait again. run --wait exits 0 when the run passed (Not a bug included), 1 when it failed (run_failed), 5 when it ended in error (run_error), 6 when it was skipped or superseded with no run after it (run_skipped), 7 when the wait ended before the run did (timeout) and 8 when the plane refused (no_run); see the exit codes above. 5 or 6 mean the tests did not decide, 7 that the wait ended before the run did, 8 that nothing was asked of them.

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, production-only. The verb comes before the project. 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 (Laravel's APP_KEY, SECRET_KEY_BASE, and others) and refuses a key that already has one. A save redeploys unless you add --no-deploy. On a staging copy or preview, the table names each value still pointing 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, and a new preview takes staging's own value instead; a copy still holding production's value loses it and redeploys, and --off copies it into new copies again (see Keep a secret out of staging and previews). See Variables.

Example: ox vars set shop STRIPE_KEY

ox services <project> [--reveal]

Service entries: type, mode, version, state, keys, backups (the same list as ox backups, newest first).

Example: ox services shop

Data commands: backups, restore, explore

ox backups <project> [now <entry> | download <entry> <source> [--output F]] [--wait] | backups key [--json]

A project's backups; back up now; download one. 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]

Data of services no longer in ox.toml; 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, activity (read-only until you allow changes). --cursor continues a long listing. Turning changes on or off is in the audit log. With changes allowed, query --confirm <entry> runs one Postgres statement read-write and commits it; the audit log records it 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 | check <server> | restart <server> [--yes] | forget <server> --confirm <server> | move <lost server> --to <server> --confirm <lost server> | cancel <id> | update <server>]

Your servers; add one, check one now, restart one (--yes answers the question; the server and its projects are down for about a minute, and a server that needs it says so in check and on its page), forget one, move the projects of one that is gone for good to another, connected one (--to; then add the new deploy key it prints for each project that clones over ssh, set each project's variables, deploy it and restore its data from your bucket), cancel an unused add, update its agent. add prints the command to run on the new server. A server whose agent is older than the plane's build is named under the list: the plane updates it once ox's own servers ran that build for a day, and ox servers update <server> does it now, and so is one that rolled back its last update, with the reason (rolled_back in --json).

Example: ox servers add

Account

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

Personal tokens; make one, revoke one. --access says what it can do: read (sees projects, runs, logs and status), deploy (read, plus deploy and roll back: the one for CI), or full (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, Signed-in browsers 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 run with a token it signs out all of them. A browser also signs out by itself 30 days after it signed in. Each sign-out is an audit row.

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 (a staging copy or preview by its own name, such as shop-staging), --action one action, such as "explore write". --limit sets the rows per page (25 by default, at most 100) and --page turns to older ones. It is the account's, 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; print the link to pay for ox Pro ($10 a month, or with --yearly $80 a year), or to change your card, get invoices, or cancel. cancel stops ox Pro when the paid month or year ends, or at once when its payment failed, and keep undoes a cancel before then. cancel asks first (--yes without a terminal). Payments are not refunded. keep-free picks the project that keeps deploying on Free (your oldest until you pick); on ox Pro it 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), and 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 --confirm <github-login>]

Download everything ox holds about you, or delete your account. Deleting keeps your apps running: the ox agent on each server removes itself and leaves /etc/ox/LEFT.txt, and the answer lists each server (how to leave).

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

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

S3 backup target, Hugging Face token, preview domain, the dashboard's look, whether times show in UTC (the default) or your own time zone, and your account's beta features. Secrets come from a file or standard input with --from-file, never as an argument. ox settings beta shows the beta features, and ox settings beta tested-deploys on|off turns tested deploys on or off for your account: off stops every run, lifts every hold and names the commits it released, and each project keeps its own setting for when they are on again.

Example: ox settings beta tested-deploys on

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]

What reaches your email and each webhook, for the account or one project; 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]

Endpoints that get your events as signed webhooks: add, filter, test, rotate, redeliver. The address is read 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, 1 GB of memory, 10 GB of disk.

Example: sudo ox install --check

ox agent

Run the ox agent, which ox install starts. 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 exactly as they were, and nothing manages them after this. /etc/ox/LEFT.txt says where everything is. 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, and 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, so download your backups and copy anything else you need off the server first (how to leave). The security settings stay. It asks first; --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