CLI command reference
CLI command reference
Install with npm install -g @codemagic/patch-cli (Node.js >=20), then run cmpatch help for grouped topics, or cmpatch <command> --help for full flags.
- React Native
- Capacitor
React Native apps use cmpatch for server setup, sign-in, apps, releases, and diagnostics.
Capacitor apps use a separate CLI, cmpatch-capacitor. Use cmpatch to run the server (Local evaluation and self-hosting). The two CLIs store sign-ins separately, so sign in with each one you use.
Auth and config
| Command | Description |
|---|---|
cmpatch login / logout / whoami | Browser sign-in via the dashboard (or --token) / sign out / identity |
cmpatch token create | list | revoke | Manage personal access tokens (cm_pat_…) |
cmpatch config list | get | set | unset | Store defaults: server-url, team, team-id |
cmpatch init | Link a project to a server and write codemagic-patch.config.json; interactively install a server or enter an existing URL, sign in after a new install, create or select an app for each platform, then wire the SDK (--skip-wire for the link only) |
cmpatch wire | Wire the SDK into the linked app: install the package, write each platform's deployment key and URLs, hook native bundle selection, export the root through Patch.wrap; shows the plan first (--dry-run --diff to only look) and exits 2 when steps remain for you |
cmpatch context | Show the effective resolved context; add --remote to include server SDK configuration (downloadBaseUrl) |
init now returns the SDK wiring result, so it can exit 2 with the connection
saved but setup incomplete. Existing scripts that only need to link the project
should use init --skip-wire. It also accepts every wire flag; see
cmpatch wire --help.
For unattended wiring, use --yes and, if the working tree has uncommitted
changes, --allow-dirty. Request any needed CocoaPods installation with
--pod-install on macOS; on Linux that step remains incomplete even with the flag.
Local evaluation and self-hosting
local-eval runs the evaluation stack on this machine. If you want to try an OTA
with a ready-made app first, run cmpatch demo to build the bundled app and watch an OTA fix apply; the demo
handles local sign-in and setup. See Local quickstart for the full walkthrough.
The install, upgrade, backup, and restore commands run
the repository's authoritative self-host scripts over SSH. The guided installer
defaults to bundled Postgres and MinIO; external R2/S3/GCS storage supports
automatic and guided first-install setup. External database setup still uses
the direct install.sh path in Infrastructure adapters.
| Command | Description |
|---|---|
cmpatch selfhost local-eval [up|down|status] | Start, stop, or inspect the localhost evaluation stack; up is the default |
cmpatch demo [--platform ios|android] [--checkout <path>] | Run the guided OTA demo against the local evaluation stack; reuse its checkout, sign in, build the app, and publish a fix after confirmation |
cmpatch selfhost install [user@vps] | Check and prepare a server, then run the guided install with DNS, OAuth sign-in (GitHub, Bitbucket Cloud, or GitLab), and optional CDN setup |
cmpatch selfhost upgrade [user@vps] | Fast-forward the server checkout and run the guarded backup-and-update workflow |
cmpatch selfhost backup [user@vps] | Take a mode-aware backup; add --download to copy it to this machine |
cmpatch selfhost restore [backup] [user@vps] | Select or upload a backup, take a safety backup, and restore the components it contains |
DNS setup
--dns-setup auto|manual|cloudflare|domain-connect selects setup-time DNS handling.
Interactive auto offers to add the records for you where it can — on
Cloudflare, or through Domain Connect when your DNS provider advertises the
Patch templates — with a manual alternative; where it cannot, it prints the
records without asking. Unattended auto uses manual DNS. For Cloudflare,
supply a setup-only token through CMPATCH_DNS_CLOUDFLARE_API_TOKEN with Zone
Read and DNS Edit permissions. Existing records require interactive approval
before replacement. Domain Connect requires browser approval.
--public-ip <address> supplies the public IPv4 address the DNS records point
at, for a server that cannot report its own — one behind NAT (Oracle Cloud, a
VM behind a router) or IPv6-only. The wizard asks for it when it needs it; a
scripted run with --dns-setup cloudflare must pass the flag.
External storage install flags
| Flags | Purpose |
|---|---|
--storage-mode bundled|r2|s3|gcs | Storage choice; bundled is the default |
--storage-setup automatic|guided | Create new resources or use console instructions; complete runtime settings skip provisioning |
--download-domain | Viewer domain for guided delivery; external modes reject --storage-domain |
--s3-bucket, --s3-internal-bucket, --s3-region | S3/R2 public/private buckets and region |
--s3-endpoint, --s3-force-path-style true|false | Explicit S3-compatible addressing |
--s3-access-key-id, --s3-secret-access-key | Runtime credentials; prefer S3_ACCESS_KEY_ID / S3_SECRET_ACCESS_KEY environment values |
--gcs-public-bucket, --gcs-internal-bucket, --gcs-credentials-file | GCS buckets and local runtime JSON path |
--gcp-project, --gcs-location, --gcp-account | Interactive GCS setup context |
--aws-profile, --cloudflare-account-id | Explicit setup account selection |
--public-base-url | Final anonymous download URL, including any required bucket prefix |
--cloudflare, --cloudfront | Delivery; CloudFront uses the existing distribution/purge-key flags |
--skip-storage-check | Skip only the subsequent on-server check; CLI pre-install verification still runs |
Setup-only credentials use CMPATCH_R2_SETUP_TOKEN,
CMPATCH_AWS_SETUP_ACCESS_KEY_ID / CMPATCH_AWS_SETUP_SECRET_ACCESS_KEY, or
CMPATCH_GCP_SETUP_CREDENTIALS_FILE. Their flag equivalents are
--r2-setup-token, --aws-setup-access-key-id, --aws-setup-secret-access-key
and --gcp-setup-credentials-file; prefer environment/file inputs. These are
disposable and are never installer runtime values.
A complete runtime configuration (buckets, credentials, and --public-base-url)
skips provisioning. If automatic setup created buckets and then failed, rerun
with --storage-setup guided and the printed names. That re-verifies existing
resources; it does not resume an API call or delete what it already created.
Replacing storage keys later is a manual edit of .env.selfhost. See
Configuration reference.
Apps and deployments
| Command | Description |
|---|---|
cmpatch app create | list | show | rename | remove | setting | Manage apps (and code-signing) |
cmpatch deployment create | list | rename | remove | clear | Manage deployments |
cmpatch deployment history | metrics | Release history / aggregate metrics |
Releases
| Command | Description |
|---|---|
cmpatch release-react | Build and publish from a React Native project |
cmpatch bundle | Build a .cmpatch artifact without uploading |
cmpatch release create | Publish a pre-built bundle / .cmpatch |
cmpatch release list | show | inspect | Browse releases; inspect --wait to poll |
cmpatch release patch | enable | disable | Edit metadata / toggle availability |
cmpatch release promote | Copy a release to another deployment |
cmpatch release rollback | Revert to the previous release |
cmpatch release metrics | Metrics for one release |
release-react bundles JS, resolves a target binary version, and uploads in one step. For iOS, release-react and bundle detect the binary version from the Xcode application target, excluding extensions. If the project has multiple apps, select one with --xcode-project-file and/or --xcode-target-name. Use --build-configuration-name when configurations have different versions. --plist-file selects a plist directly; --plist-file-prefix selects a prefixed plist in the chosen app's directory. If SDK/architecture conditions affect the detected version, or the project or build settings cannot be resolved, pass --target-binary-version with the installed app's version. cmpatch doctor --platform ios accepts the same selection flags.
Android auto-detection supports a static defaultConfig.versionName and a literal common versionNameSuffix. Simple properties are read from the selected module and its Gradle root. Flavor/build-type version overrides and dynamic expressions require --target-binary-version; the CLI does not evaluate Gradle or CI overrides. For those projects, extract the version from the published APK/AAB.
Members and diagnostics
| Command | Description |
|---|---|
cmpatch member add | invite | provision | list | remove … | Team membership and invitations |
cmpatch doctor | Diagnose React Native / Expo setup on configured platforms; optionally verify delivery with --verify-delivery |
cmpatch fingerprint --platform ios|android | Compute the native fingerprint |
List/metrics commands accept --format table|json.
cmpatch-capacitor
CLI for Capacitor and Ionic apps. Install it with npm install -g @codemagic/capacitor-patch-cli (Node.js 20.19+ or 22.12+). It is a 0.x release, so its flags may still change. Run cmpatch-capacitor --help for the command list, or cmpatch-capacitor <command> --help for a command's flags.
| Command | Description |
|---|---|
cmpatch-capacitor login / logout / whoami | Sign in through the browser (or with --token), sign out, show the current user. --no-browser prints the sign-in URL |
cmpatch-capacitor token create | list | revoke | Manage personal access tokens |
cmpatch-capacitor config list | set | unset | Manage the default server URL |
cmpatch-capacitor app create | list | show | rename | setting | remove | Manage apps (one per platform). app create adds Staging and Production deployments |
cmpatch-capacitor deployment create | list | rename | remove | clear | metrics | history | Manage deployments and view deployment keys and metrics |
cmpatch-capacitor release create | Publish built web assets. release with no subcommand is the same |
cmpatch-capacitor release list | show | inspect | metrics | View releases and metrics. inspect --wait waits for processing to finish |
cmpatch-capacitor release patch | disable | enable | promote | rollback | Change rollout, availability, or metadata, promote, or roll back |
Differences from cmpatch
cmpatch-capacitor | |
|---|---|
| Project config | None. There is no init, context, or codemagic-patch.config.json. Select the app and deployment with --app and --deployment (or --deployment-id), and the server with --server-url, CODEMAGIC_PATCH_SERVER_URL, or config set |
| Platform | No --platform flag. Each app is a single platform |
| Publishing | release create --bundle-path <dir|zip> uploads a built webDir (or a ZIP of its contents) with index.html at the top level. No build step |
| Binary version | --target-binary-version is required and must be exact. No native fingerprint. See Binary version compatibility |
| App lookup | Names resolve only to Capacitor apps. IDs (--app-id, --deployment-id, --release-id) skip the lookup and are recommended in CI |
| Output | --format text (default) or --format json (raw server response). table is not accepted |
| Not included | Server management (cmpatch selfhost), team members (dashboard Members page), doctor |
Credentials are resolved in this order: --token, CODEMAGIC_PATCH_TOKEN, then the stored sign-in in ~/.codemagic-patch/credentials-capacitor.json.
Confirmation
Commands that change what devices receive or delete data (release create, patch, disable, enable, promote, rollback, app remove, deployment remove, deployment clear) show a summary and ask for confirmation. The prompt appears only in an interactive terminal. In CI (when CI is set), when stdin or stderr is not a terminal, or with --format json, these commands fail unless you pass -y / --yes. There is no --non-interactive flag.
Exit codes
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | Server or runtime error (not found, duplicate release, network failure, …), or confirmation declined |
| 2 | Usage error, missing --yes, not signed in, or token rejected by the server |
| 3 | Validation error, release processing failed or timed out (inspect --wait), stored sign-in expired or revoked, or browser sign-in denied or timed out |
| 4 | Account disabled |
| 130 | Confirmation prompt interrupted (Ctrl-C) |