# CLI (/reference/cli)

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

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

```bash
npm install -D @upwell/cli
npx upwell --help
```

Node 20 or newer.

## Files [#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):

```json title="upwell.json"
{
  "policy": "config/policy.json",
  "releases": "config/releases.json"
}
```

`--file <path>` overrides both for one command.

## Changing files safely [#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 [#commands]

### init [#init]

```bash
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](#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 [#doctor]

```bash
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 [#publish]

```bash
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](/docs/policy/hosting) 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 [#status]

```bash
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 [#policy-validate]

```bash
upwell policy validate [--file <path>]
```

Runs [`validatePolicy()`](/docs/policy/validation), 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 [#policy-set-latest--minimum]

```bash
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 [#policy-set-ota-runtime]

```bash
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 [#releases-add]

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

```bash
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 [#releases-list--remove--validate]

```bash
upwell releases list [--platform ios] [--runtime 3.4.0]
upwell releases remove <id>
upwell releases validate
```

### explain [#explain]

Runs [`explain()`](/docs/reference/core) on your policy with a device described by flags, and
prints the decision and every rule it checked. With the
[example policy](https://github.com/updateswell/upwell/blob/main/docs/examples/policy.json):

```bash
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`, `--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 [#schema]

```bash
upwell schema policy > policy.schema.json
```

Prints the JSON Schema for `policy` or `releases`.

## Scripts, CI and agents [#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](/docs/guides/automate-your-policy).

Every command takes `--json`. stdout then holds exactly one JSON value:

```json
{ "ok": true, "data": { "file": "/repo/upwell/policy.json", "changed": true, "written": true, "diff": ["…"], "risks": [] } }
```

```json
{ "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](https://github.com/updateswell/upwell/issues) |
