Skip to main content

CLI

CLI release notes

Release notes for cmpatch, published as @codemagic/patch-cli. The CLI has commands for app developers (release-react, wire, doctor) and for self-host operators (selfhost install, upgrade, backup); entries name the audience where it matters. The other surfaces' releases are on the Release Notes page.

npm install -g @codemagic/patch-cli@latest

Reference: CLI reference · GitHub releases

0.11.0​

19th November 2026

Webhooks​

Adds cmpatch webhook for managing a team's webhooks. Requires server 0.11.0.

cmpatch webhook create --url https://example.com/hooks/patch
cmpatch webhook test --webhook-id <id>
cmpatch webhook deliveries --webhook-id <id> --status failed

create, update, and rotate-secret need a browser login. remove and rotate-secret ask before they act, so pass --yes in CI. See Webhooks and the CLI reference.

Build metadata for React Native​

React Native SDK 0.8.0 records the native fingerprint and the embedded bundle's hash inside the app at build time.

cmpatch fingerprint --artifact build/MyApp.ipa
  • Adds cmpatch fingerprint --artifact <path>, which prints the fingerprint, the embedded bundle hash, and the binary version of an .xcarchive, .ipa, .apk, or .aab. It needs no checkout, login, or server.
  • cmpatch wire adds the build metadata step to a bare project. If you upgrade the SDK in a project that is already wired, run wire again. See the upgrade steps.
  • cmpatch doctor warns when the installed SDK has the step and the project does not run it.
  • With SDK 0.8.0 installed, fingerprint, release create, and release-react use the SDK's fingerprint engine. fingerprint --format json adds fingerprintEngine.

See Recorded at build time.

Other changes​

  • Table output of release show, release inspect, release metrics, release list, deployment metrics, member list, and member invite-list now includes values that were only in --format json, such as release notes, download sizes, failure reasons, and a total row. JSON output is unchanged.
  • Prints a one-line notice on a terminal when a newer cmpatch is on npm. The check asks registry.npmjs.org for the latest version once a day. It does not run in CI, when output is piped, or with --format json. Set CMPATCH_NO_UPDATE_CHECK=1 to turn it off.

Fixes​

  • Escapes control characters in table cells, so a failure reason reported by a device cannot send escape sequences to your terminal.
  • Fixes Fly install and upgrade messages that mentioned a build where the server image is pulled.
  • Fixes cmpatch wire in a React Native 0.88 project, where the template keeps bundle selection in SceneDelegate.swift. Wire edits that file, and no longer reports a project that was edited by hand as incomplete.
  • cmpatch wire plans pod install when Podfile.lock names another version of the SDK's pod than the one installed, as after an SDK upgrade.
  • Shows the message of a failed pod install instead of the end of its Ruby backtrace.
  • cmpatch wire no longer shows the build metadata step as already set up in an Expo prebuild project whose ios and android directories do not run it yet. The row says the next prebuild adds it.

See the CLI reference and CLI release.

0.10.0​

17th November 2026

Breaking​

cmpatch selfhost upgrade shows its plan and asks before it changes anything, on a server and on Fly. A run that cannot ask (CI, --non-interactive) needs --yes.

Install and upgrade from the published server image​

cmpatch selfhost install and upgrade pull the image published with each server release instead of building it on the server. An install no longer waits for a build or needs the 2 GB of memory a build takes. On Fly, the image is deployed directly, without the remote builder.

  • upgrade moves the server's checkout to the newest server release and runs that release's upgrade script. An install from before published images runs the default branch and moves the same way. A checkout with local edits or commits, or one newer than the release, is refused.
  • Before it asks, upgrade pulls the target image and runs the image's schema check against the database. It refuses a database that has applied a migration the release does not know. --skip-schema-check skips the check and is unsafe.
  • Adds --build-from-source, which builds the image on the server (or on Fly's remote builder), and --image <ref>, which runs an image you name. Both work on install and upgrade, Fly included.
  • If an upgrade fails after the stack is recreated, the command prints the rollback steps in order, with this server's paths.

Update the CLI before upgrading a server to 0.10.0. See Upgrades.

React Native SwiftPM mode​

cmpatch wire detects an app converted with npx react-native spm add. It skips the CocoaPods step and the pod install prompt, upgrades an installed SDK that has no Package.swift, and adds npx react-native spm to the next steps. The plan shows an iOS packages row, and --format json adds project.iosDependencyManager.

  • wire installs React Native SDK 0.7.0 or later in every app, so an app that converts from CocoaPods later needs no SDK upgrade.
  • In SwiftPM mode, the iOS fingerprint leaves out Package.resolved under xcshareddata/swiftpm and Xcode's xcuserdata folders, which exist on your machine but not in a CI checkout. CocoaPods and Android fingerprints are unchanged. See Fingerprinting.

API tokens and service accounts​

  • Adds cmpatch member rotate-token --email <email>. It replaces the token of a service account created with member provision, prints the new token once, and stops the old token immediately; update the CI secret that held it. It confirms unless --yes and needs a browser login. member list marks service accounts. Requires server 0.10.0.
  • Server 0.10.0 refuses the commands that create credentials or grant access, such as token create, member invite, and app transfer, from a --token login or CODEMAGIC_PATCH_TOKEN. The CLI says to remove the token and run cmpatch login. Full list in the server notes.

Other changes​

  • deployment timeseries prints the range totals, the success rate, and the active devices of the last complete day under its table. In --format json, deployment metrics, release metrics, and deployment timeseries add success_rate and a summary, and each timeseries series adds its cumulative Applied count. Requires server 0.10.0; output is unchanged against an older server.
  • Adds error.hint to --format json errors. It carries the remedy that text output prints, such as the sign-in command after a 401.
  • Adds an install survey. After a first successful selfhost install, the CLI asks once per machine how you heard about Codemagic Patch. Enter skips it and sends nothing. An answer sends the choice, the install method, and for Other the text you type. --no-telemetry and DO_NOT_TRACK=1 turn it off, and a run that cannot prompt never asks.

Fixes​

  • Fixes selfhost install --ngrok on an ephemeral address, which registered its OAuth callback against an address that changes on the next run. The install now stops and asks for your account's dev domain with --ngrok-domain. Free plans have one. Contributed in codemagic-patch#42. See Reach a real phone with ngrok.

See the CLI reference and CLI release.

0.9.0​

3rd November 2026

Install with a separate Postgres database​

On a first cmpatch selfhost install, the wizard asks where the database runs. The default is still the bundled Postgres on the server. A separate database is for backups and point-in-time recovery, and is needed for disk space above a few million daily active users. Choose it and paste your provider's connection string (--database-url on an unattended run). The wizard shows the server's IP to allow, then checks from the server itself that the database user can connect and create tables. The choice is fixed once .env.selfhost is written, so --repair refuses --database-url.

The string has to end in sslmode=require. A string that names sslrootcert or sslmode=verify-full is refused. The stored string gains uselibpqcompat=true, so the server's PostgreSQL client (pg 8) treats require as encrypt-only. Without it, pg 8 treats require as verify-full, which rejects the certificates managed Postgres providers use. See Run the installer.

Promote picks deployments, and both release commands ask for the rollout​

cmpatch release promote lists the app's deployments to pick the source and destination from, instead of asking you to type their names. release-react already did this for its deployment. Both commands ask for a rollout percentage (Enter keeps 100) instead of using 100 without asking. Runs that cannot prompt (--yes, CI, --format json, piped output) keep the default, and an explicit --rollout-percentage is left alone.

Usage report opt-out​

cmpatch selfhost install --no-telemetry writes SERVER_TELEMETRY=false, so the server never sends the daily anonymous usage report that server 0.9.0 turns on. The flag works on a first install, with --ngrok and --fly, and with --repair on an installed server. The install summary says whether the report is on.

Fixes​

  • Fixes cmpatch init turning down valid servers with "not like a Codemagic Patch server". Its /health/ready probe expected checks to be a list, while the server sends an object.
  • The storage choice in the install wizard and the local evaluation stack call the bundled object store Silo, which is what runs. The MINIO_* variables, the /minio/health/ready path, and backup archive names are unchanged.

See the CLI reference and CLI release.

0.8.0​

28th October 2026

Install on Fly.io​

cmpatch selfhost install --fly deploys Patch onto Fly.io with Tigris object storage, from this machine and without a VPS, DNS records, or certificates. It can create Postgres or use a database you run. Existing Fly installs can also be registered.

selfhost upgrade, backup, and restore work on a recorded Fly install. upgrade snapshots the database when cmpatch created it and deploys the newest release (or --tag). backup saves the database dump on this machine. restore replaces the database from one of those backups while your apps keep downloading from storage. See Install on Fly.io, Fly backup, and Fly restore.

Install on this machine with ngrok​

cmpatch selfhost install --ngrok installs the full stack, with OAuth sign-in and bundled Postgres and storage, on the machine it runs on, reached at your ngrok account's https:// address. It is for trying Patch on real devices without a domain, open ports, or a server. The free plan is capped, and apps keep the address they were built with. See Reach a real phone with ngrok.

Fixes​

  • Fixes overlapping runs signing each other out. When two runs that share the stored session (a terminal and a CI step, two jobs on one machine) both needed to refresh an expired access token, the second refresh was refused and that run deleted the stored credentials, including the session the first run had just saved. Runs now refresh one at a time under a lock next to the credential store. A run that gets the lock first re-reads the store and, if another run has already refreshed the session, uses that session instead of sending its own refresh. A refresh the server refuses still clears the stored credentials and asks you to sign in again.
  • Flag errors point at the command's help. An unknown flag, a missing or invalid value, or a stray argument inside a command now ends with Run `cmpatch help <command>` for usage instead of pointing at the root listing, which does not name the command's flags. Contributed in codemagic-patch#37.

See the CLI reference and CLI release.

0.7.0​

19th October 2026

Breaking​

cmpatch member remove, member update, member invite-revoke, and token revoke now show what they change and ask before they change anyone's access, as app remove does. Without a terminal (in CI, with --non-interactive, or with --format json) they exit 2 instead of running. Add --yes to scripts that call them.

Dashboard parity: server, teams, app transfer​

  • Adds cmpatch server status, which prints the server's own view of its database, storage, disk, download URL, and version: the same checks as the dashboard's Status page. cmpatch doctor checks from your machine instead.
  • Adds cmpatch team list and cmpatch team show, which list the teams you can see and show one team's details. They give the name or ID to pass as --team or store with cmpatch config set team.
  • Adds cmpatch app transfer, which moves an app and its deployments to another team, picked with --dest-team / --dest-team-id or from a list of your other teams. It confirms unless --yes. Capacitor apps move the same way. Pass the ID that cmpatch-capacitor app list shows as --app-id.

Metrics from the CLI​

cmpatch help metrics lists these commands alongside deployment metrics, deployment history, and release metrics.

  • Adds cmpatch deployment timeseries, which prints a deployment's counters per day, the numbers behind the dashboard's deployment chart. Pick the window with --range 7d|30d|90d|1y or --from / --to, narrow it with --binary-version / --binary-version-prefix, and use --format json for the per-release series.
  • Adds cmpatch deployment failures / failure-events and cmpatch release failures / failure-events. They drill into a failure reason from deployment metrics or release metrics, as the dashboard's failure dialog does. failures --reason <reason> lists the codes under it. Adding --code <code>, or --no-code for the failures that reported none, shows that code's top exit reasons and messages. failure-events lists the single events of one code, a page at a time with --limit and --cursor.
  • cmpatch release list --binary-version lists only the releases that target one binary version (--binary-version 1.2.3), and --binary-version-prefix every version under a prefix (--binary-version-prefix 1.2), like the binary version filter on the dashboard's deployment page.

Other changes​

  • cmpatch app setting without --require-code-signing shows whether the app requires code signing, instead of failing on a missing flag or asking for a value. Pass --require-code-signing=<true|false> to change it, as before.
  • cmpatch release promote without --label, on a terminal, lets you pick the release from the source deployment's list, newest first with its status and target binary version, instead of typing a label. Help no longer claims --rollout-percentage and --disabled default to the source release; they default to 100 and off.
  • Adds cmpatch token revoke --name <name>, which revokes a token by the name you gave it at creation. A name shared by several tokens is refused, and the error lists their IDs to pass as --token-id.
  • Removes the hidden cmpatch release inspect --logs flag, which only ever reported that no log API exists. It now fails as an unknown flag. For failure detail, use deployment failures / failure-events.

See the CLI reference and CLI release.

0.6.0​

6th October 2026

React Native app filtering​

Teams can now include Capacitor apps, which are managed with cmpatch-capacitor. cmpatch shows only React Native apps: app create records the app as React Native, and app list, the interactive pickers, init, and doctor request only React Native apps from the server. Apps selected by id (--app-id, --deployment-id) are not checked. app show prints the framework when the server reports one. On servers older than 0.6.0, all apps are listed; every app on such a server is a React Native app.

  • Server 0.6.0 error messages no longer name a cmpatch command, so the CLI prints the remedy itself. For example, an upload rejected for a missing signature still prints the --private-key-path commands to run.

See the CLI reference and CLI release.

0.5.0​

23rd September 2026

cmpatch wire​

cmpatch wire installs the Patch SDK in a supported React Native or Expo project and configures it. It sets the deployment key and server URLs, adds the native bundle-loading hooks, and wraps your root component with Patch.wrap. cmpatch init runs it; pass --skip-wire to only connect the app. Run cmpatch wire --dry-run --diff to preview the changes. If wire cannot finish the setup, it prints a Patch.wrap snippet to add by hand.

init does not run wiring while CodePush or expo-updates is still in the project. See Native setup.

GitLab and Bitbucket sign-in in the self-host wizard​

For operators: cmpatch selfhost install supports Bitbucket Cloud and GitLab sign-in, in the wizard and in non-interactive setup. For a self-managed GitLab instance, enter its address when asked or pass --gitlab-oauth-base-url.

  • When a release change is blocked by a 409 conflict, the CLI names the release to wait for and the cmpatch release inspect --release-id <id> --wait command to run before retrying.
  • Fixes cmpatch release-react on React Native 0.87, which removed react-native/cli.js from its package exports. The command failed with "Could not resolve react-native from project root", mostly in npm projects.
  • Improves iOS and Android binary version detection, so OTA releases target the correct app version. It handles Android versionNameSuffix and asks you to pass the target explicitly when the project is ambiguous.
  • cmpatch doctor no longer fails the credential check for logins made with cmpatch login --token. Adds --xcode-project-file, --xcode-target-name, and --build-configuration-name to it.
  • Prints progress steps in non-interactive output such as CI logs, including during long builds and bundle uploads.
  • cmpatch debug shows only Patch SDK logs and filters out unrelated system messages.
  • cmpatch release metrics labels its columns ready and applied.

See the CLI reference and CLI release.

0.4.0​

14th September 2026

cmpatch demo​

With the local evaluation stack running, cmpatch demo runs an OTA update on a demo app, without integrating Patch into your own app. The wizard checks prerequisites, builds a bundled demo app on an iOS simulator or Android emulator, and shows a bug in its catalog. After you approve publishing the fix, it resumes the app, which downloads, installs, and applies the update.

cmpatch doctor​

cmpatch doctor checks React Native and Expo integration on iOS and Android, including native configuration, authentication, and deployment settings. The report lists likely causes and separates confirmed failures from incomplete checks. Add --verify-delivery to probe manifests and artifacts; JSON output is available for CI. The optional --fix --server-url <url> creates missing server configuration after a readiness check, if you approve it.

External storage and DNS in the self-host wizard​

For operators: cmpatch selfhost install offers Cloudflare R2, Amazon S3, and Google Cloud Storage alongside bundled MinIO. The wizard configures storage or prints console instructions, then verifies public downloads and private-object protection. DNS setup supports Cloudflare and compatible Domain Connect providers, with manual instructions as a fallback.

When a setup step fails, the wizard lets you correct it and retry. These options apply to new installations; they do not migrate existing storage.

See the CLI reference and CLI release.

0.3.0​

7th September 2026

Self-host install wizard​

For operators: cmpatch selfhost install installs and operates a production server from your own machine. The wizard pairs with the host over SSH, checks it, can install Docker and Git with your consent, then sets up domains, DNS, GitHub OAuth, and optional Cloudflare or CloudFront. The CLI also runs backup, restore, and upgrade.

cmpatch selfhost install

If you have no server URL yet, cmpatch init offers to run the install, then continues with sign-in and app creation. An interrupted backup restarts the server before it exits. Interrupted restore and upgrade runs print the rollback command instead. The wizard sets up the bundled Postgres and MinIO stack with GitHub sign-in. Bitbucket, external databases, and S3/GCS still require running install.sh directly. See Install and Operations.

cmpatch selfhost local-eval​

The evaluation stack is unchanged, but you no longer clone the repo first. cmpatch keeps its own copy and updates it on later runs. If Docker is missing or not running, it asks before installing or starting it.

cmpatch selfhost local-eval

See Local quickstart and the CLI release.

0.2.0​

25th August 2026

Interactive prompts​

When a flag is missing, cmpatch prompts for it instead of exiting with a usage line. It also shows progress and offers sign-in and retry options when browser login fails. In CI and scripts the CLI stays non-interactive: pass the flags you need, or use --yes where supported. See CLI command reference.

Fingerprint mismatch check​

The CLI blocks a release aimed at the wrong native binary unless you confirm it. It compares the release fingerprint against the value already recorded for that deployment and binary version. When they differ, the CLI shows the details and lets you cancel or proceed.

In CI, where there is no prompt, pass --allow-fingerprint-mismatch only after you have verified the release targets the intended native binary:

cmpatch release-react \
--deployment Production \
--allow-fingerprint-mismatch \
--yes

The CLI sends block_on_fingerprint_mismatch: true by default, so on server 0.2.0 or newer a mismatch returns 409 and no release is created. See Fingerprinting.

  • cmpatch release metrics breaks failures down by category (integrity, signature, rollout, or another category) instead of showing a single failed count. See Analytics and metrics.

See the CLI release.