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 a link and a code, 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 saves it empty, 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>

Live commit (and the ref it came from, when someone deployed another ref), URL, processes, and the last run.

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. It stays stopped through deploys, restores, and reboots. 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.

Example: ox start shop --wait

ox autodeploy <project> [on | off]

Show whether every push deploys, or turn that on or off.

Example: ox autodeploy shop off

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> [--domain D] [--branch B] [--wait]

Make the project's staging copy. --branch B deploys a branch instead of production's live commit.

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

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

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; 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]

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> | forget <server> --confirm <server> | move <lost server> --to <server> --confirm <lost server> | cancel <id> | update <server>]

Your servers; add one, check one now, 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, with ox servers update <server>, 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 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 | manage]

Your plan, Free or Pro, with the projects paused on Free; print the link to pay for Pro, or to manage your billing.

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

S3 backup target, Hugging Face token, preview domain, and the dashboard's look. 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]

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