OTA Update CLI Reference

Every ota CLI command: init, release, promote, rollback, status and doctor, plus the flags and environment variables they read.

The CLI is what publishes updates. Install it once, globally — or prefix any command below with npx @otaupdate/cli instead.

terminal

npm install -g @otaupdate/cli
ota --version

Sign in

It already knows where to send requests — there's no server to point it at:

terminal

ota login

Prompts for your email and password, then the 6-digit code sent to your inbox. Credentials are saved to a profile on this machine. Good for local, interactive use.

terminal

ota whoami       # who am I, and in which organizations
ota logout       # forget the saved credentials

Day-to-day commands

Every command below is run from your project root and reads ota.config.js, so no command takes an app name, a key or a version.

Command	What it does
`ota init`	Once per app: creates the project, writes ota.config.js and the release scripts, prints one SDK key per channel. Safe to re-run — it repairs rather than duplicates.
`ota release`	Builds the JS bundle for each configured platform and publishes it to a channel. Defaults to staging.
`ota promote`	Serves what one channel is serving from another, reusing the stored bundle. No rebuild, no re-upload.
`ota rollback`	Republishes the previous release as a new mandatory one, which reaches devices that already installed the bad build.
`ota status`	The last ten releases and what each is doing right now.
`ota doctor`	Checks environment, project, bundle identifiers, git state and scripts, and names the fix for each failure.

terminal

ota init
ota release --channel staging -m "Fix checkout crash"
ota promote --from staging --to production
ota rollback --channel production --platform ios
ota status
ota doctor

ota init also writes these as npm scripts, which is what most teams end up typing: ota:staging, ota:prod, ota:prod:mandatory, ota:promote, ota:rollback, ota:doctor. Flags still work through them — npm run ota:prod -- --rollout 10, or without the -- on yarn and pnpm.

Adding another channel

A project starts with production and staging. To add a qa or canary, open the project in the dashboard and create it there — lowercase letters, digits and dashes. It gets its own SDK key immediately, and a build carrying that key follows that channel.

Publishing to it needs no setup:

terminal

ota release --channel qa
ota promote --from qa --to production     # promote works between any two channels
ota rollback --channel qa

The scripts are not regenerated for a new channel

ota init writes scripts for staging and production only, and re-running it does not add one for a channel you created later. Add the line yourself so the new channel is as memorable as the other two:

package.json

{
  "scripts": {
    "ota:qa": "ota release --channel qa"
  }
}

Your own scripts are never overwritten — a later ota init leaves them alone.

A new channel also needs a build that carries its key before any device can receive those releases. Publishing to a channel nobody has built for succeeds and reaches nothing.

Global flags

Flag	Environment variable	Meaning
`--api-key <key>`	`OTA_API_KEY`	Authenticate this command with an API key instead of the saved profile.
`--server <url>`	`OTA_SERVER_URL`	Point at a non-default server. Rarely needed.
`--profile <name>`	—	Use a named credential profile — one per account or organization.
`--format json`	—	Machine-readable output, including errors with a stable code.
—	`OTA_DEBUG=1`	Print full stack traces on failure.

Organization and account commands

Command	What it does
`ota api-key create <name>`	Creates a publishing key, shown once. Use for CI.
`ota api-key list`	Lists keys with their prefix and last use.
`ota api-key revoke <keyId>`	Revokes a key immediately.
`ota member list \| add \| role \| rm`	Manage who can publish, and at what role.
`ota org list \| add`	List your organizations, or create one (user session only).

app and deployment commands are the previous generation

ota app … and ota deployment … still exist for organizations created before projects and channels. If you ran ota init, you are on projects — use the commands above.