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 wireadds the build metadata step to a bare project. If you upgrade the SDK in a project that is already wired, runwireagain. See the upgrade steps.cmpatch doctorwarns when the installed SDK has the step and the project does not run it.- With SDK 0.8.0 installed,
fingerprint,release create, andrelease-reactuse the SDK's fingerprint engine.fingerprint --format jsonaddsfingerprintEngine.
Other changes
- Table output of
release show,release inspect,release metrics,release list,deployment metrics,member list, andmember invite-listnow 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
cmpatchis on npm. The check asksregistry.npmjs.orgfor the latest version once a day. It does not run in CI, when output is piped, or with--format json. SetCMPATCH_NO_UPDATE_CHECK=1to 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 wirein a React Native 0.88 project, where the template keeps bundle selection inSceneDelegate.swift. Wire edits that file, and no longer reports a project that was edited by hand as incomplete. cmpatch wireplanspod installwhenPodfile.locknames another version of the SDK's pod than the one installed, as after an SDK upgrade.- Shows the message of a failed
pod installinstead of the end of its Ruby backtrace. cmpatch wireno longer shows the build metadata step as already set up in an Expo prebuild project whoseiosandandroiddirectories 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.
upgrademoves 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,
upgradepulls 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-checkskips 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 oninstallandupgrade, 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.
wireinstalls 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.resolvedunderxcshareddata/swiftpmand Xcode'sxcuserdatafolders, 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 withmember provision, prints the new token once, and stops the old token immediately; update the CI secret that held it. It confirms unless--yesand needs a browser login.member listmarks 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, andapp transfer, from a--tokenlogin orCODEMAGIC_PATCH_TOKEN. The CLI says to remove the token and runcmpatch login. Full list in the server notes.
Other changes
deployment timeseriesprints 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, anddeployment timeseriesaddsuccess_rateand asummary, and each timeseries series adds its cumulative Applied count. Requires server 0.10.0; output is unchanged against an older server.- Adds
error.hintto--format jsonerrors. It carries the remedy that text output prints, such as the sign-in command after a401. - 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-telemetryandDO_NOT_TRACK=1turn it off, and a run that cannot prompt never asks.
Fixes
- Fixes
selfhost install --ngrokon 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 initturning down valid servers with "not like a Codemagic Patch server". Its/health/readyprobe expectedchecksto 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/readypath, 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 usageinstead 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 doctorchecks from your machine instead. - Adds
cmpatch team listandcmpatch team show, which list the teams you can see and show one team's details. They give the name or ID to pass as--teamor store withcmpatch config set team. - Adds
cmpatch app transfer, which moves an app and its deployments to another team, picked with--dest-team/--dest-team-idor from a list of your other teams. It confirms unless--yes. Capacitor apps move the same way. Pass the ID thatcmpatch-capacitor app listshows 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|1yor--from/--to, narrow it with--binary-version/--binary-version-prefix, and use--format jsonfor the per-release series. - Adds
cmpatch deployment failures/failure-eventsandcmpatch release failures/failure-events. They drill into a failure reason fromdeployment metricsorrelease metrics, as the dashboard's failure dialog does.failures --reason <reason>lists the codes under it. Adding--code <code>, or--no-codefor the failures that reported none, shows that code's top exit reasons and messages.failure-eventslists the single events of one code, a page at a time with--limitand--cursor. cmpatch release list --binary-versionlists only the releases that target one binary version (--binary-version 1.2.3), and--binary-version-prefixevery version under a prefix (--binary-version-prefix 1.2), like the binary version filter on the dashboard's deployment page.
Other changes
cmpatch app settingwithout--require-code-signingshows 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 promotewithout--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-percentageand--disableddefault 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 --logsflag, which only ever reported that no log API exists. It now fails as an unknown flag. For failure detail, usedeployment 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
cmpatchcommand, so the CLI prints the remedy itself. For example, an upload rejected for a missing signature still prints the--private-key-pathcommands 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> --waitcommand to run before retrying. - Fixes
cmpatch release-reacton React Native 0.87, which removedreact-native/cli.jsfrom 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
versionNameSuffixand asks you to pass the target explicitly when the project is ambiguous. cmpatch doctorno longer fails the credential check for logins made withcmpatch login --token. Adds--xcode-project-file,--xcode-target-name, and--build-configuration-nameto it.- Prints progress steps in non-interactive output such as CI logs, including during long builds and bundle uploads.
cmpatch debugshows only Patch SDK logs and filters out unrelated system messages.cmpatch release metricslabels its columnsreadyandapplied.
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 metricsbreaks failures down by category (integrity, signature, rollout, or another category) instead of showing a singlefailedcount. See Analytics and metrics.
See the CLI release.