CLI reference#

@rollbird/cli provides the rollbird executable. It requires Node.js 20 or newer and has exactly five commands: login, init, release, rollback, and status.

Availability: @rollbird/cli is available from the public npm registry.

Install the CLI#

Install it as a development dependency in the React Native project:

npm install --save-dev @rollbird/cli

A local install makes npx rollbird use the version pinned by the app.

Global options#

Global options go before the command.

Option	Meaning
`--json`	Write exactly one machine-readable JSON result to stdout. Human progress and errors go to stderr.
`--api-url <url>`	Override the API URL for this invocation. It takes precedence over environment variables and saved credentials.
`--help`	Show command help.

Inspect the command surface:

npx rollbird --help

Use a local API for one status request:

npx rollbird --api-url http://127.0.0.1:8787 status

`rollbird login`#

Authenticate with the device flow, or verify and save an API token for a non-interactive environment.

Usage: rollbird login [options]

Option	Meaning
`--token <token>`	Verify this API token and skip device authorization.
`--org <orgId>`	Save an explicit organization id with `--token`. Normally unnecessary because the API resolves the token's organization.

Interactive example:

npx rollbird login

Expected completion:

✓ Confirmed  in the browser

Logged in

Token example:

npx rollbird login --token rb_live_REDACTED

Expected completion:

✓ Token verified

Logged in

The command writes credentials.json with mode 0600 under $XDG_CONFIG_HOME/rollbird/, or ~/.config/rollbird/ when XDG_CONFIG_HOME is not set. The device code expires; exact failure text is Device code expired. Run rollbird login again.

For CI, prefer the ROLLBIRD_TOKEN environment variable over running login.

`rollbird init`#

Detect the app, link or create its Rollbird project, provision signing, install the SDK, wire native entry points or the Expo config plugin, embed fingerprints, and write rollbird.json.

Usage: rollbird init [options]

Option	Default	Meaning
`--name <name>`	`package.json` name	Name used only when a Rollbird project must be created.
`--channel <channel>`	`production`	Channel embedded in the native configuration.
`--yes`	off	Accept defaults instead of prompting.
`--no-install`	installs	Update `package.json` but skip the package-manager install.
`--ios-bundle-id <id>`	detected	Supply the iOS bundle identifier when detection fails.
`--android-app-id <id>`	detected	Supply the Android application id when detection fails.

Preview-build example:

npx rollbird init --channel preview

Non-interactive example when identifiers and the package name cannot be detected:

npx rollbird init --yes --name fieldkit --ios-bundle-id com.example.fieldkit --android-app-id com.example.fieldkit

init is safe to re-run. Re-run it after native code, native configuration, or native dependencies change, then rebuild the app. A stored fingerprint matches updates only to binaries made from that native state.

Bare projects are edited directly. Expo projects keep the channel, public key, runtime, and per-platform fingerprints in rollbird.json; the @rollbird/react-native config plugin restores them after every prebuild.

init refuses to continue when expo-updates is installed. It also refuses a bare app with neither ios/ nor android/, or an Expo CNG app with no Expo config file in which to register the plugin.

`rollbird release`#

Build, sign, upload, and publish an OTA release.

Usage: rollbird release [options]

Option	Default	Meaning
`--production`	off	Publish to `production`; shorthand for `--channel production`.
`--channel <name>`	`preview`	Publish to this release channel.
`--rollout <percent>`	`100`	Staged rollout percentage from 1 through 100.
`--message <text>`	none	Attach a release message.
`--force`	off	Mark the update `shouldForceUpdate`. The SDK reloads after download by default.
`--platform <platform>`	detected platforms	Build only `ios` or `android`.
`--target-app-version <version>`	none	Target an app version when the app uses the `appVersion` strategy.
`--yes`	off	Skip the interactive production confirmation.

Publish a preview release to both detected platforms:

npx rollbird release --message "Fix offline sign-in"

Expected completion:

✓ Bundled iOS  977 KB
✓ Bundled Android  980 KB
✓ Signed  2 bundles
✓ Uploaded  1.9 MB
✓ Published  Release #7 · 100% rollout

Live in preview

Publish a staged iOS production release without prompting:

npx rollbird release --production --platform ios --rollout 10 --message "Fix checkout" --yes

Publish an update for builds using strategy: "appVersion":

npx rollbird release --channel production --target-app-version 2.4.0 --yes

Rollout must be an integer from 1 through 100. Platform must be exactly ios or android. A release to a channel different from the channel stored in rollbird.json succeeds but prints a warning because the current build will not request it.

When Git metadata is available, the command attaches commit, branch, and author. It records GitHub Actions, GitLab, Bitrise, or CircleCI when their environment variables identify the provider.

`rollbird rollback [number]`#

Disable a release on one channel and serve the previous valid bundle. Rollback is instant and free, never consumes release quota, and is not blocked by plan status or storage.

Usage: rollbird rollback [options] [number]

Option	Default	Meaning
`--channel <name>`	`production`	Channel to roll back.
`--yes`	off	Skip the confirmation prompt.

Roll back the active production release:

npx rollbird rollback

Roll back release 17 on preview without prompting:

npx rollbird rollback 17 --channel preview --yes

Expected completion when an earlier release exists:

✓ Rolled back  release #17

Now serving release #16 on preview

When no earlier OTA bundle remains, the app returns to its embedded bundle. Builds made after the newly served release never move below their own embedded bundle.

`rollbird status`#

Show the linked project, every channel's latest release, production-release usage, storage usage, and dashboard URL.

Usage: rollbird status [options]

Run it from the directory containing rollbird.json:

npx rollbird status

Example output:

rollbird status · Fieldkit (fieldkit)

production          #7 · active · 100% rollout · 2 hours ago
preview             #8 · active · 25% rollout · 5 minutes ago

Production releases █░░ 1 / 3 · resets Oct 1
Storage             18 MB / 250 MB

Dashboard
https://app.rollbird.dev/p/fieldkit

Values and channels come from the current account; the example is not a promise of plan limits. The limit source of truth is the live account response.

JSON output#

Put --json before the command. Success writes one JSON object to stdout; failures use { "error": { ... } } and preserve the same process exit code as human output.

npx rollbird --json status

Release example:

npx rollbird --json release --production --yes

The success object includes releaseId, number, channel, platforms, and per-platform sizes. A limited production plan may also include a quota object. Do not scrape human-readable timelines; use JSON and exit codes.

Authentication resolution#

Credentials resolve in this order:

ROLLBIRD_TOKEN, with optional ROLLBIRD_ORG and ROLLBIRD_API_URL.
The credentials file written by rollbird login.

--api-url overrides both URL sources for one invocation. A token belongs to one organization; ROLLBIRD_ORG is normally unnecessary and must match when set.

Exit codes#

Exit codes are a public automation contract.

Code	Meaning	Typical cases
`0`	Success	Command completed.
`1`	Local or build failure	Bundler, filesystem, parser, or unexpected local exception.
`2`	Usage, configuration, or ordinary request failure	Missing `rollbird.json`, invalid flag, cancellation, API 4xx other than authentication or plan limits.
`3`	Authentication failure	Missing credentials, invalid/forbidden token, expired device code.
`4`	Plan or quota refusal	API HTTP 402, with upgrade metadata when supplied.
`5`	Network, storage, or server failure	Fetch failure, rejected upload, API 5xx.

Example shell gate:

npx rollbird --json release --production --yes

Read the process status directly. Do not translate every nonzero code into a retry: code 2 needs corrected input, code 3 needs credentials, code 4 needs an account decision, and only code 5 is normally transient.

Do not do this#

Do not invent a sixth command or a flag not listed here.
Do not store a token in rollbird.json; it contains public project configuration only.
Do not use --yes as authentication. It only skips supported confirmations or accepts init defaults.
Do not publish to a channel the installed binary was not built to request.
Do not treat rollback as quota-bearing. Rollback is always free and available.

View this page as Markdown

CLI reference#

Install the CLI#

Global options#

rollbird login#

rollbird init#

rollbird release#

rollbird rollback [number]#

rollbird status#

JSON output#

Authentication resolution#

Exit codes#

Do not do this#

`rollbird login`#

`rollbird init`#

`rollbird release`#

`rollbird rollback [number]`#

`rollbird status`#