CLI
The upwell command. Validate and edit policy.json and releases.json, and see what any build would be told.
@upwell/cli is the command line for your policy and release notes. It edits the files in your
repo, so every change goes through review like any other, and it runs the same engine as the app:
upwell explain tells you exactly what a device on a given build would see.
npx @upwell/cli policy validateIt's not installed with upwell. Run it with npx, or add it as a dev dependency to pin a version
in CI:
npm install -D @upwell/cli
npx upwell --helpNode 20 or newer.
Files
Commands read and write upwell/policy.json and upwell/releases.json. To keep them somewhere
else, add an upwell.json at the root of the app's repo (the CLI finds it from any subdirectory):
{
"policy": "config/policy.json",
"releases": "config/releases.json"
}--file <path> overrides both for one command.
Changing files safely
Commands that write show the change as a diff first, and only touch the lines they change: your formatting, key order and inline objects stay as they were.
- In a terminal, they ask before writing.
- Without a terminal (CI, scripts, agents), with
CIset, or with--json, they never ask: pass--yesto write. - Changes that affect installs already out there need
--confirm, and the CLI says who is affected:- raising
minimum(or setting it for the first time): installs below it are blocked until they update - lowering
latest: installs in between stop being offered an update - changing
ota.latestRuntimeVersion: installs on the old runtime become stranded
- raising
--dry-runshows the diff and writes nothing.
A change that would make the document invalid is refused with the validator's errors.
Commands
init
npx @upwell/cli init [--with-expo-updates] [--yes] [--dry-run]Sets Upwell up in an Expo app, in one go after showing what it will do:
- Installs
upwell(andexpo-updateswith--with-expo-updates) withnpx expo install. - Adds
"upwell"to the plugins inapp.json. With a dynamicapp.config.js/.tsit tells you what to add instead: it never edits code. - Writes
upwell/policy.jsonwithlatestandminimumat the app's current version and builds, andota.latestRuntimeVersionwhen the runtime can be computed (a fixed string, or theappVersion/nativeVersionpolicies). Installs without Upwell never read the policy, so startingminimumthere blocks nobody. An existing policy is kept. - Writes
upwell.json.
Then it prints the UpwellProvider snippet to add to your app and, in a terminal, offers to
publish the policy right away. Rebuild the native app afterwards: Upwell adds native
code.
| Option | |
|---|---|
--with-expo-updates | Also install expo-updates, for OTA updates |
--skip-install | Don't run npx expo install; print the command instead |
--static | Read app.json directly instead of running npx expo config |
doctor
npx @upwell/cli doctor [--policy-url <url>] [--releases-url <url>] [--offline]Finds setup problems before your users do. It reads the resolved app config
(npx expo config, falling back to app.json), package.json, eas.json, upwell.json and your
documents, fetches the published policy the way a device does, and reports each finding with a
fix. Errors make it exit with code 1, so it can gate CI.
| Finding | Severity | |
|---|---|---|
EXPO_MISSING, UPWELL_MISSING | error | Packages Upwell needs |
UPWELL_NOT_INSTALLED | warning | In package.json, not in node_modules |
NO_OTA | info | No expo-updates: store updates only |
PLUGIN_NOT_CONFIGURED | info | The config plugin is optional |
UPDATES_URL_MISSING, RUNTIME_VERSION_MISSING | error | expo-updates can't find or match OTA updates |
RUNTIME_POLICY_NEEDS_NEWER_UPWELL | warning | A runtimeVersion policy needs upwell 0.1.3+ for stranded detection in development builds |
CHANNEL_MISSING | warning | No channel in eas.json build profiles or expo-channel-name header |
UPDATES_CHECK_AUTOMATICALLY | info | expo-updates also checks on its own |
POLICY_INVALID, POLICY_WARNING (and RELEASES_…) | error / warning | The local files, with the app's validator |
NO_POLICY, POLICY_NOT_PUBLISHED | info | What runs without a policy, or that the published copy wasn't checked |
POLICY_URL_NOT_HTTPS | error | Android release builds block plain HTTP (a warning for localhost and 10.0.2.2) |
POLICY_URL_UNREACHABLE, POLICY_URL_INVALID | error | Devices can't fetch it, or reject it |
POLICY_CACHE_LONG | warning | Cache-Control above 5 minutes delays changes |
POLICY_OUT_OF_DATE | warning | The published copy differs from the local file |
LATEST_BEHIND_APP | warning | The app being built is newer than latest (a reminder for after the release) |
OTA_RUNTIME_DIFFERS | warning | This build's runtime isn't the policy's OTA runtime |
APP_STORE_ID_MISSING | warning | The App Store sheet works best with ios.appStoreId |
The published URLs come from --policy-url / --releases-url, or publish.urls in
upwell.json. When there is one, the app is compared with the published copy, since that's what
devices see. --offline skips the network.
publish
npx @upwell/cli publish [--to gist|github] [--repo owner/name] [--dry-run] [--confirm]Puts policy.json, and releases.json when you have one, at a stable public URL:
| Target | URL |
|---|---|
gist (default) | https://gist.githubusercontent.com/<owner>/<gist id>/raw/policy.json |
github (--repo) | https://raw.githubusercontent.com/<owner>/<repo>/<branch>/<path>/policy.json |
It validates both files, shows the diff against what's live, and applies the same rules as
policy set: --yes without a terminal, and --confirm for changes that affect installs. The
first run records the target and URLs in upwell.json ("publish"), so later runs, status and
doctor know them. See Hosting the policy for auth, caching and rollback.
| Option | |
|---|---|
--to | gist or github |
--repo | A public repo for --to github (implies it) |
--branch | Default: the repo's default branch |
--path | Directory in the repo. Default upwell |
status
npx @upwell/cli statusWhere the documents are published, the last revision, whether each published file matches the local one, and whether the raw URL already serves it (GitHub caches raw files for 5 minutes). Works without a token for public targets.
policy validate
upwell policy validate [--file <path>]Runs validatePolicy(), the validator the app runs on every fetched
policy. Errors fail the command (exit code 1); warnings are printed and don't.
policy set latest / minimum
upwell policy set latest --platform android --version 3.4.0 --build 340 [--released-at today]
upwell policy set minimum --platform ios --version 3.2.0 --build 1| Option | |
|---|---|
--platform | android or ios (required) |
--version | Display version (required) |
--build | Build number: versionCode on Android (written as a number), CFBundleVersion on iOS (written as a string) (required) |
--released-at | ISO date it went live in the store, or today. Drives staleness on iOS. Setting the same version again keeps its date |
Creates the policy file if there isn't one.
policy set ota-runtime
upwell policy set ota-runtime 3.4.0 [--platform android]Sets ota.latestRuntimeVersion, the runtime your newest OTA updates target. Without --platform
it sets every platform the policy has.
releases add
upwell releases add --id <update group id> --kind fix --notes "Fixed checkout on iOS 27"
upwell releases add --from-eas-update eas-update.json --kind fix| Option | |
|---|---|
--kind | fix, content or feature (required) |
--id | The update group id or an update id |
--notes | What changed, in words users read. With --from-eas-update, defaults to the update message |
--runtime | Runtime version. Default: the policy's ota.latestRuntimeVersion for those platforms |
--platform | android, ios or android,ios (default: both) |
--published-at | ISO timestamp (default: now) |
--from-eas-update | A file with the output of eas update --json |
New releases go first in the file. Ids are unique (ignoring case).
With --from-eas-update, the id, platforms, runtime and date come from EAS:
eas update --branch production --message "Fixed checkout" --json --non-interactive > eas-update.json
npx upwell releases add --from-eas-update eas-update.json --kind fix --yesWhen both platforms share a runtime, that's one release with the update group id. With
per-platform runtimes (the fingerprint runtime policy), each platform gets its own release with
its update id. The SDK matches either id.
releases list / remove / validate
upwell releases list [--platform ios] [--runtime 3.4.0]
upwell releases remove <id>
upwell releases validateexplain
Runs explain() on your policy with a device described by flags, and
prints the decision and every rule it checked. With the
example policy:
upwell explain --platform android --build 330 --runtime 3.3.0 --play-version-code 340store.recommended (playFlexible)
recommended: stranded on runtime 3.3.0, latest OTA needs 3.4.0
installed: android 330 (build 330), source play, runtime 3.3.0
newer: policy latest 340 > installed build 330
staleness: 2 days (policy latest.releasedAt)
stranded: yes, runtime 3.3.0 != latest OTA runtime 3.4.0
minimum: build 330 meets minimum 300
stranded escalation: 2 days < strandedRequireAfterDays 14
→ store.recommended: recommended: stranded on runtime 3.3.0, latest OTA needs 3.4.0| Option | |
|---|---|
--platform, --build | The installed app (required) |
--version | Installed version (required on iOS, which compares versions first) |
--runtime | Installed OTA runtime, for stranded detection |
--source | play, appStore, testFlight, sideload or unknown. Default: the platform's store |
--now | Evaluate at another date, e.g. to see when requireAfterDays kicks in |
--installation-id | The install id that picks the rollout bucket (default upwell-cli) |
--play-version-code, --play-priority, --play-staleness-days | What Google Play reports. Without them there is no Play info, as on a device Play can't reach |
--app-store-version, --app-store-released-at | What the App Store lookup returns |
--ota | The OTA adapter's status: available, downloading, ready, … |
--no-policy | Explain an app without a policy |
schema
upwell schema policy > policy.schema.jsonPrints the JSON Schema for policy or releases.
Scripts, CI and agents
Recipes for EAS, GitHub Actions and coding agents (with an AGENTS.md snippet for your app repo)
are in Automate your policy.
Every command takes --json. stdout then holds exactly one JSON value:
{ "ok": true, "data": { "file": "/repo/upwell/policy.json", "changed": true, "written": true, "diff": ["…"], "risks": [] } }{ "ok": false, "error": { "code": "CONFIRMATION_REQUIRED", "message": "…", "risks": ["raises the android minimum from …"] } }| Exit code | Meaning |
|---|---|
0 | Done |
1 | Failed: see error.code (for doctor: errors were found) |
2 | Usage: bad or missing options (USAGE) |
3 | Needs --yes, or --confirm for a risky change (CONFIRMATION_REQUIRED) |
error.code | |
|---|---|
USAGE | Bad or missing options |
FILE_NOT_FOUND | The policy, releases or EAS file doesn't exist |
INVALID_JSON | A file isn't valid JSON |
INVALID_CONFIG | upwell.json is malformed |
INVALID_DOCUMENT | The document is invalid, or would be after the change; errors lists why |
INVALID_EAS_UPDATE | The --from-eas-update file isn't eas update --json output |
RELEASE_EXISTS | releases add with an id that's already there |
RELEASE_NOT_FOUND | releases remove with an unknown id |
CONFIRMATION_REQUIRED | Re-run with --yes (or --confirm); risks says who is affected |
ABORTED | Answered no at the prompt |
NOT_AN_EXPO_APP | init outside an Expo app (no expo dependency) |
INSTALL_FAILED | npx expo install failed during init; nothing was written |
CHECKS_FAILED | doctor found errors; findings lists everything it found |
AUTH_MISSING, AUTH_INVALID | No GitHub token, or GitHub rejected it |
GITHUB_FORBIDDEN | GitHub refused: usually a missing gist scope or contents: write |
GITHUB_UNREACHABLE, GITHUB_ERROR | Network or other GitHub errors |
GIST_NOT_FOUND | The gist recorded in upwell.json was deleted |
REPO_NOT_FOUND, REPO_PRIVATE | The --repo target doesn't exist, or isn't public |
INTERNAL | A bug: please report it |