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.
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 an RN 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 |
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 RN/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.