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.

Install and sign in

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.

JSON for scripts

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

Exit codes

Code	Meaning
`0`	It worked.
`1`	ox refused, the project, run or server was not found, or the run you waited on failed.
`2`	A flag or an argument is wrong. The message shows the right usage.
`3`	You are not signed in, or your token expired or was revoked. Run `ox login`.
`4`	ox Cloud could not be reached.

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. --generate K makes a random value for a missing variable, --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, 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.; Example: ox stop shop --wait
ox start <project> [--wait]: Start a stopped project.; Example: ox start shop --wait
ox autodeploy <project> [on | off]: Deploy on every push: show or turn 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. Previews and staging 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: show, 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. Without --ref it deploys the project's branch.; 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] [--process P] [--severity S] [-n N] [-o FILE]: The processes' logs, their history and search, or one run's log. -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|unset|import|pull|history|restore|sync <project> … [--no-deploy] [--wait]: Variables: the table, set, unset, import, pull, history, restore, sync. 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. A save redeploys unless you add --no-deploy. See Variables.; Example: ox vars set shop STRIPE_KEY
ox services <project> [--reveal]: Service entries: type, mode, version, state, keys, backups.; 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.; Example: ox restore shop postgres --from backup:daily-20261007T030000Z.dump --confirm shop --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] | 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). --cursor continues a long listing.; 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> | cancel <id> | update <server>]: Your servers; add one, check one now, forget one, cancel an unused add, update its agent. add prints the command to run on the new server.; Example: ox servers add

Account

ox tokens [create [--name N] | revoke <id | name>]: Personal tokens; make one, revoke one. --name says what the token is for.; Example: ox tokens create --name ci
ox account [export [-o FILE] | delete --confirm <github-login>]: Download everything ox holds about you, or delete your account.; 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 console'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] [on EVENT... | off EVENT... [--channel email|ENDPOINT] | email on|off | use-account | test]: Which events email you, for the account or one project; send a test email. --channel picks email or a webhook endpoint.; Example: ox notifications on deploy.succeeded
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 T: 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 (started by install --agent). You do not run it by hand.; Example: sudo systemctl status ox-agent
ox uninstall: Remove everything ox added to this host. 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