# 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`. New to ox? The [quickstart](https://deploywithox.com/docs/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:

```sh
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:

```sh
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. |

## 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. `--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](https://deploywithox.com/docs/operate/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](https://deploywithox.com/docs/operate/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: 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](https://deploywithox.com/docs/operate/rollback).

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](https://deploywithox.com/docs/operate/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](https://deploywithox.com/docs/operate/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](https://deploywithox.com/docs/operate/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`

Last updated 2026-10-08. The page as HTML: https://deploywithox.com/docs/cli