Upwell

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 validate

It'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 --help

Node 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):

upwell.json
{
  "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 CI set, or with --json, they never ask: pass --yes to 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
  • --dry-run shows 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:

  1. Installs upwell (and expo-updates with --with-expo-updates) with npx expo install.
  2. Adds "upwell" to the plugins in app.json. With a dynamic app.config.js/.ts it tells you what to add instead: it never edits code.
  3. Writes upwell/policy.json with latest and minimum at the app's current version and builds, and ota.latestRuntimeVersion when the runtime can be computed (a fixed string, or the appVersion / nativeVersion policies). Installs without Upwell never read the policy, so starting minimum there blocks nobody. An existing policy is kept.
  4. 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-updatesAlso install expo-updates, for OTA updates
--skip-installDon't run npx expo install; print the command instead
--staticRead 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.

FindingSeverity
EXPO_MISSING, UPWELL_MISSINGerrorPackages Upwell needs
UPWELL_NOT_INSTALLEDwarningIn package.json, not in node_modules
NO_OTAinfoNo expo-updates: store updates only
PLUGIN_NOT_CONFIGUREDinfoThe config plugin is optional
UPDATES_URL_MISSING, RUNTIME_VERSION_MISSINGerrorexpo-updates can't find or match OTA updates
RUNTIME_POLICY_NEEDS_NEWER_UPWELLwarningA runtimeVersion policy needs upwell 0.1.3+ for stranded detection in development builds
CHANNEL_MISSINGwarningNo channel in eas.json build profiles or expo-channel-name header
UPDATES_CHECK_AUTOMATICALLYinfoexpo-updates also checks on its own
POLICY_INVALID, POLICY_WARNING (and RELEASES_…)error / warningThe local files, with the app's validator
NO_POLICY, POLICY_NOT_PUBLISHEDinfoWhat runs without a policy, or that the published copy wasn't checked
POLICY_URL_NOT_HTTPSerrorAndroid release builds block plain HTTP (a warning for localhost and 10.0.2.2)
POLICY_URL_UNREACHABLE, POLICY_URL_INVALIDerrorDevices can't fetch it, or reject it
POLICY_CACHE_LONGwarningCache-Control above 5 minutes delays changes
POLICY_OUT_OF_DATEwarningThe published copy differs from the local file
LATEST_BEHIND_APPwarningThe app being built is newer than latest (a reminder for after the release)
OTA_RUNTIME_DIFFERSwarningThis build's runtime isn't the policy's OTA runtime
APP_STORE_ID_MISSINGwarningThe 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:

TargetURL
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
--togist or github
--repoA public repo for --to github (implies it)
--branchDefault: the repo's default branch
--pathDirectory in the repo. Default upwell

status

npx @upwell/cli status

Where 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
--platformandroid or ios (required)
--versionDisplay version (required)
--buildBuild number: versionCode on Android (written as a number), CFBundleVersion on iOS (written as a string) (required)
--released-atISO 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
--kindfix, content or feature (required)
--idThe update group id or an update id
--notesWhat changed, in words users read. With --from-eas-update, defaults to the update message
--runtimeRuntime version. Default: the policy's ota.latestRuntimeVersion for those platforms
--platformandroid, ios or android,ios (default: both)
--published-atISO timestamp (default: now)
--from-eas-updateA 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 --yes

When 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 validate

explain

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 340
store.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, --buildThe installed app (required)
--versionInstalled version (required on iOS, which compares versions first)
--runtimeInstalled OTA runtime, for stranded detection
--sourceplay, appStore, testFlight, sideload or unknown. Default: the platform's store
--nowEvaluate at another date, e.g. to see when requireAfterDays kicks in
--installation-idThe install id that picks the rollout bucket (default upwell-cli)
--play-version-code, --play-priority, --play-staleness-daysWhat Google Play reports. Without them there is no Play info, as on a device Play can't reach
--app-store-version, --app-store-released-atWhat the App Store lookup returns
--otaThe OTA adapter's status: available, downloading, ready, …
--no-policyExplain an app without a policy

schema

upwell schema policy > policy.schema.json

Prints 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 codeMeaning
0Done
1Failed: see error.code (for doctor: errors were found)
2Usage: bad or missing options (USAGE)
3Needs --yes, or --confirm for a risky change (CONFIRMATION_REQUIRED)
error.code
USAGEBad or missing options
FILE_NOT_FOUNDThe policy, releases or EAS file doesn't exist
INVALID_JSONA file isn't valid JSON
INVALID_CONFIGupwell.json is malformed
INVALID_DOCUMENTThe document is invalid, or would be after the change; errors lists why
INVALID_EAS_UPDATEThe --from-eas-update file isn't eas update --json output
RELEASE_EXISTSreleases add with an id that's already there
RELEASE_NOT_FOUNDreleases remove with an unknown id
CONFIRMATION_REQUIREDRe-run with --yes (or --confirm); risks says who is affected
ABORTEDAnswered no at the prompt
NOT_AN_EXPO_APPinit outside an Expo app (no expo dependency)
INSTALL_FAILEDnpx expo install failed during init; nothing was written
CHECKS_FAILEDdoctor found errors; findings lists everything it found
AUTH_MISSING, AUTH_INVALIDNo GitHub token, or GitHub rejected it
GITHUB_FORBIDDENGitHub refused: usually a missing gist scope or contents: write
GITHUB_UNREACHABLE, GITHUB_ERRORNetwork or other GitHub errors
GIST_NOT_FOUNDThe gist recorded in upwell.json was deleted
REPO_NOT_FOUND, REPO_PRIVATEThe --repo target doesn't exist, or isn't public
INTERNALA bug: please report it

On this page