@capgo/cli 8.50.2 → 8.50.3

package/README.md

@@ -1356,21 +1356,12 @@ npx @capgo/cli@latest organisation delete
 
 ## <a id="build"></a> 🔹 **Build**
 
-🏗️  Manage native iOS/Android builds through Capgo Cloud.
-⚠️ Native cloud build requests are currently in LIMITED BETA. Access is restricted.
- 🔒 SECURITY GUARANTEE:
-    Build credentials are NEVER stored on Capgo servers.
-    They are used only during the build and auto-deleted after.
-    Build outputs may optionally be uploaded for time-limited download links.
-📋 BEFORE BUILDING:
-   Save your credentials first:
-   npx @capgo/cli build credentials save --appId <your-app-id> --platform ios
-   npx @capgo/cli build credentials save --appId <your-app-id> --platform android
-📤 CAPTURE THE OUTPUT URL FROM CI:
-   Pass --output-record to persist the download URL + QR code, then read it
-   back with `build last-output`:
-   npx @capgo/cli build request <appId> --platform android --output-upload --output-record /tmp/build.json
-   URL=$(npx @capgo/cli build last-output --path /tmp/build.json --field outputUrl)
+Build native iOS and Android apps with Capgo Cloud.
+Native cloud builds are currently in limited beta.
+Quick start:
+  npx @capgo/cli@latest build init
+  npx @capgo/cli@latest build request <app-id> --platform <ios|android>
+Run npx @capgo/cli@latest build <command> --help for command-specific options.
 
 ### <a id="build-needed"></a> 🔹 **Needed**
 
@@ -1378,12 +1369,13 @@ npx @capgo/cli@latest organisation delete
 npx @capgo/cli@latest build needed
 ```
 
-🧭 Print "yes" and exit with code 1 if a native build is required; otherwise print "no" and exit with code 0. Command failures exit with code 2.
+Print "yes" and exit with code 1 if a native build is required. Otherwise print "no" and exit with code 0. Command failures exit with code 2.
+  npx @capgo/cli@latest build needed com.example.app --channel production --verbose
 
 **Example:**
 
 ```bash
-npx @capgo/cli@latest build needed com.example.app --channel production --verbose
+Example:
 ```
 
 **Options:**
@@ -1425,23 +1417,26 @@ npx @capgo/cli@latest build request
 ```
 
 Request a native build from Capgo Cloud.
-This command zips your project and uploads it to Capgo for a remote native build.
-By default the finished artifact can go to the app store (when store credentials are saved)
-and/or to Capgo storage as a time-limited download link (--output-upload).
- 🔒 SECURITY: Credentials are never stored on Capgo servers. They are auto-deleted
-    after build completion. Build outputs may optionally be uploaded for time-limited download links.
-📋 PREREQUISITE: Save credentials first with:
-   `npx @capgo/cli@latest build credentials save --appId <app-id> --platform <ios|android>`
-Android AAB only (no Play upload): npx @capgo/cli@latest build request com.example.app --platform android --no-playstore-upload --output-upload
-iOS IPA only (no TestFlight upload): npx @capgo/cli@latest build request com.example.app --platform ios --ios-distribution ad_hoc --output-upload
-Disable Xcode compilation cache: npx @capgo/cli@latest build request com.example.app --platform ios --no-cache
-Separate RC and PROD caches: npx @capgo/cli@latest build request com.example.app --platform ios --cache-key prod
-
-**Example:**
-
-```bash
-npx @capgo/cli@latest build request com.example.app --platform ios --path .
-```
+The project is zipped and uploaded for a remote native build. The finished artifact can be sent to the app store, uploaded to Capgo for a time-limited download, or both.
+Credentials are uploaded only for the build. Their temporary server copies are deleted after it finishes.
+Before your first build:
+  npx @capgo/cli@latest build init
+Examples:
+  iOS build:
+    npx @capgo/cli@latest build request com.example.app \
+      --platform ios --path .
+  Android artifact without Play upload:
+    npx @capgo/cli@latest build request com.example.app \
+      --platform android --no-playstore-upload --output-upload
+  iOS artifact without TestFlight upload:
+    npx @capgo/cli@latest build request com.example.app \
+      --platform ios --ios-distribution ad_hoc --output-upload
+  Disable the Xcode compilation cache:
+    npx @capgo/cli@latest build request com.example.app \
+      --platform ios --no-cache
+  Use a separate compilation cache:
+    npx @capgo/cli@latest build request com.example.app \
+      --platform ios --cache-key prod
 
 **Options:**
 
@@ -1464,6 +1459,8 @@ npx @capgo/cli@latest build request com.example.app --platform ios --path .
 | **--ios-target** | <code>string</code> | iOS: Xcode target for reading build settings (default: same as scheme) |
 | **--ios-distribution** | <code>string</code> | iOS: Distribution mode. app_store (default) uploads to TestFlight/App Store; ad_hoc skips store upload and builds an Ad Hoc IPA for device install. Use ad_hoc with --output-upload when the App Store app does not exist yet or you only need an IPA download. |
 | **--ios-provisioning-profile** | <code>string</code> | iOS: Provisioning profile path or bundleId=path mapping (repeatable) |
+| **--no-cache** | <code>boolean</code> | Disable Xcode compilation cache for this build (default: cache enabled) |
+| **--cache-key** | <code>string</code> | Custom compilation cache key for this build (e.g. rc, prod, feature-branch). Use to share or isolate cache between environments. Precedence over the default appId-only key; ignored when --no-cache is set. |
 | **--android-keystore-file** | <code>string</code> | Android: Base64-encoded keystore file |
 | **--keystore-key-alias** | <code>string</code> | Android: Keystore key alias |
 | **--keystore-key-password** | <code>string</code> | Android: Keystore key password |
@@ -1493,18 +1490,16 @@ npx @capgo/cli@latest build request com.example.app --platform ios --path .
 | **--sync-android-version** | <code>boolean</code> | Android: sync versionName in android/app/build.gradle from package.json before uploading the project. Fails unless versionName is a standalone quoted string literal. |
 | **--ai-analytics** | <code>boolean</code> | On build failure, send logs to Capgo AI for diagnosis. In interactive terminals this skips the upfront confirmation; in CI this auto-uploads and prints the analysis to stderr. |
 | **--no-prescan** | <code>boolean</code> | Skip the automatic pre-build scan |
-| **--no-cache** | <code>boolean</code> | Disable Xcode compilation cache for this build (default: cache enabled) |
-| **--cache-key** | <code>string</code> | Custom compilation cache key for this build (e.g. rc, prod, feature-branch). Use to share or isolate cache between environments. Precedence over the default appId-only key; ignored when --no-cache is set. |
 | **--prescan-ignore-fatal** | <code>boolean</code> | Run the pre-build scan but never block the build (report only) |
 | **--prescan-skip** | <code>string</code> | Skip specific prescan check(s) by id (repeatable or comma-separated). Other checks still run. |
 | **--prescan-warn** | <code>string</code> | Downgrade specific prescan check(s) to warning by id (repeatable or comma-separated). Check still runs. |
 | **--fail-on-warnings** | <code>boolean</code> | Treat prescan warnings as fatal |
 | **--send-logs-to-support** | <code>boolean</code> | On a CI/CD build failure, automatically upload the build logs to Capgo support (no email required). Capgo support is notified and will follow up by email. Additive to --ai-analytics. |
 | **--send-logs** | <code>boolean</code> | Deprecated alias for --send-logs-to-support |
+| **--verbose** | <code>boolean</code> | Enable verbose output with detailed logging |
 | **-a** | <code>string</code> | API key to link to your account |
 | **--supa-host** | <code>string</code> | Custom Supabase host URL (for self-hosting or Capgo development) |
 | **--supa-anon** | <code>string</code> | Custom Supabase anon key (for self-hosting) |
-| **--verbose** | <code>boolean</code> | Enable verbose output with detailed logging |
 
 ### <a id="build-sync-ios-version"></a> 🔹 **Sync-ios-version**
 
@@ -1514,11 +1509,12 @@ npx @capgo/cli@latest build sync-ios-version
 
 Sync the local iOS app version from package.json.
 Updates MARKETING_VERSION or CFBundleShortVersionString based on the Xcode Info.plist configuration.
+  npx @capgo/cli@latest build sync-ios-version --path .
 
 **Example:**
 
 ```bash
-npx @capgo/cli@latest build sync-ios-version --path .
+Example:
 ```
 
 **Options:**
@@ -1535,7 +1531,15 @@ npx @capgo/cli@latest build prescan
 ```
 
 Scan your project and saved credentials for problems that would fail a cloud build — before uploading anything.
-Checks credentials (expiry, passwords, profile pairing), project state (cap sync, node_modules layout), and platform config. Runs automatically inside `build request`; this command runs it standalone (e.g. in CI).
+Checks credentials, project state, and platform configuration. This scan runs
+automatically inside `build request`; use this command to run it separately.
+  npx @capgo/cli@latest build prescan com.example.app --platform ios
+
+**Example:**
+
+```bash
+Example:
+```
 
 **Options:**
 
@@ -1566,9 +1570,9 @@ Prints the full JSON by default, a single field with --field, or the ASCII QR
 code with --qr. Useful in CI to grab the download URL or QR for posting back
 to a PR or issue.
 Examples:
-  npx @capgo/cli build last-output --path /tmp/build.json
-  npx @capgo/cli build last-output --path /tmp/build.json --field outputUrl
-  npx @capgo/cli build last-output --path /tmp/build.json --qr
+  npx @capgo/cli@latest build last-output --path /tmp/build.json
+  npx @capgo/cli@latest build last-output --path /tmp/build.json --field outputUrl
+  npx @capgo/cli@latest build last-output --path /tmp/build.json --qr
 
 **Options:**
 
@@ -1580,15 +1584,14 @@ Examples:
 
 ### <a id="build-credentials"></a> 🔹 **Credentials**
 
-Manage build credentials stored locally on your machine.
-🔒 SECURITY:
-   - Credentials saved to ~/.capgo-credentials/credentials.json (global) or .capgo-credentials.json (local)
-   - When building, sent to Capgo but NEVER stored permanently
-   - Deleted from Capgo immediately after build
-   - Build outputs may optionally be uploaded for time-limited download links
-📚 DOCUMENTATION:
-   iOS setup: https://capgo.app/docs/cli/cloud-build/ios/
-   Android setup: https://capgo.app/docs/cli/cloud-build/android/
+Manage locally saved build credentials.
+Credentials are stored in ~/.capgo-credentials/credentials.json globally, or
+in .capgo-credentials.json for one project. They are uploaded only for a build;
+their temporary server copies are deleted after it finishes.
+Setup guides:
+  iOS: https://capgo.app/docs/cli/cloud-build/ios/
+  Android: https://capgo.app/docs/cli/cloud-build/android/
+Run npx @capgo/cli@latest build credentials <command> --help for command-specific options.
 
 #### <a id="build-credentials-apple-key"></a> 🔹 **Apple-key**
 
@@ -1603,7 +1606,7 @@ Opens a native window that walks you through Apple's App Store Connect UI in an
 embedded browser, auto-captures the Issuer ID + Key ID, intercepts the one-time
 .p8, validates it against Apple, and saves it to ~/.appstoreconnect/private_keys.
 Progress statistics are forwarded to Capgo analytics (disable with CAPGO_DISABLE_TELEMETRY).
-  npx @capgo/cli build credentials apple-key --appId com.example.app
+  npx @capgo/cli@latest build credentials apple-key --appId com.example.app
 
 **Example:**
 
@@ -1650,38 +1653,27 @@ Example:
 npx @capgo/cli@latest build credentials save
 ```
 
-Save build credentials locally for iOS or Android.
-Credentials are stored in:
-  - ~/.capgo-credentials/credentials.json (default, global)
-  - .capgo-credentials.json in project root (with --local flag)
-⚠️  REQUIRED BEFORE BUILDING: You must save credentials before requesting a build.
-🔒 These credentials are NEVER stored on Capgo servers permanently.
-   They are deleted immediately after the build completes.
-📚 Setup guides:
-   iOS: https://capgo.app/docs/cli/cloud-build/ios/
-   Android: https://capgo.app/docs/cli/cloud-build/android/
-  npx @capgo/cli build credentials save --platform ios \
-    --certificate ./cert.p12 --p12-password "password" \
-    --ios-provisioning-profile ./profile.mobileprovision \
-    --apple-key ./AuthKey.p8 --apple-key-id "KEY123" \
-    --apple-issuer-id "issuer-uuid" --apple-team-id "team-id"
-Multi-target Example (app + widget extension):
-  npx @capgo/cli build credentials save --platform ios \
-    --ios-provisioning-profile ./App.mobileprovision \
-    --ios-provisioning-profile com.example.widget=./Widget.mobileprovision \
-    ...
-  npx @capgo/cli build credentials save --platform android \
-    --keystore ./release.keystore --keystore-alias "my-key" \
-    --keystore-key-password "key-pass" \
-    --play-config ./service-account.json
-Local storage (per-project):
-  npx @capgo/cli build credentials save --local --platform ios ...
-
-**Example:**
-
-```bash
-iOS Example:
-```
+Save iOS or Android build credentials on this machine.
+Credentials are stored globally by default. Use --local to store them in the
+current project's .capgo-credentials.json file instead.
+Setup guides:
+  iOS: https://capgo.app/docs/cli/cloud-build/ios/
+  Android: https://capgo.app/docs/cli/cloud-build/android/
+Examples:
+  iOS app with a widget extension:
+    npx @capgo/cli@latest build credentials save \
+      --appId com.example.app --platform ios \
+      --certificate ./cert.p12 --p12-password "password" \
+      --ios-provisioning-profile ./profile.mobileprovision \
+      --ios-provisioning-profile com.example.widget=./Widget.mobileprovision \
+      --apple-key ./AuthKey.p8 --apple-key-id "KEY123" \
+      --apple-issuer-id "issuer-uuid" --apple-team-id "team-id"
+  Android:
+    npx @capgo/cli@latest build credentials save \
+      --appId com.example.app --platform android \
+      --keystore ./release.keystore --keystore-alias "my-key" \
+      --keystore-key-password "key-pass" \
+      --play-config ./service-account.json
 
 **Options:**
 
@@ -1689,6 +1681,7 @@ iOS Example:
 | -------------- | ------------- | -------------------- |
 | **--appId** | <code>string</code> | App ID (e.g., com.example.app) (required) |
 | **--platform** | <code>string</code> | Platform: ios or android (required) |
+| **--local** | <code>boolean</code> | Save to .capgo-credentials.json in project root instead of global ~/.capgo-credentials/ |
 | **--certificate** | <code>string</code> | iOS: Path to .p12 certificate file |
 | **--ios-provisioning-profile** | <code>string</code> | iOS: Provisioning profile path or bundleId=path (repeatable) |
 | **--p12-password** | <code>string</code> | iOS: Certificate password (optional if cert has no password) |
@@ -1707,7 +1700,6 @@ iOS Example:
 | **--play-config** | <code>string</code> | Android: Path to Play Store service account JSON |
 | **--android-flavor** | <code>string</code> | Android: Product flavor to build (e.g. production). Required if your project has multiple flavors. |
 | **--in-app-update-priority** | <code>string</code> | Android: Google Play in-app update priority for future releases (integer 0–5; higher = more urgent). Omit to leave Play’s existing value untouched. |
-| **--local** | <code>boolean</code> | Save to .capgo-credentials.json in project root instead of global ~/.capgo-credentials/ |
 | **--output-upload** | <code>boolean</code> | Upload build outputs (IPA/APK/AAB) to Capgo storage and print download links |
 | **--no-output-upload** | <code>boolean</code> | Do not upload build outputs (IPA/APK/AAB) to Capgo storage |
 | **--output-retention** | <code>string</code> | Output link TTL: 1h to 7d (default: 1h). Examples: 1h, 6h, 2d |
@@ -1725,8 +1717,9 @@ npx @capgo/cli@latest build credentials list
 List saved build credentials (passwords masked).
 Shows what credentials are currently saved (both global and local).
 Examples:
-  npx @capgo/cli build credentials list  # List all apps
-  npx @capgo/cli build credentials list --appId com.example.app  # List specific app
+  npx @capgo/cli@latest build credentials list
+  npx @capgo/cli@latest build credentials list --appId com.example.app
+  npx @capgo/cli@latest build credentials list --local
 
 **Options:**
 
@@ -1745,9 +1738,9 @@ Clear saved build credentials.
 Remove credentials from storage.
 Use --appId and --platform to target specific credentials.
 Examples:
-  npx @capgo/cli build credentials clear  # Clear all apps (global)
-  npx @capgo/cli build credentials clear --local  # Clear local credentials
-  npx @capgo/cli build credentials clear --appId com.example.app --platform ios
+  npx @capgo/cli@latest build credentials clear
+  npx @capgo/cli@latest build credentials clear --local
+  npx @capgo/cli@latest build credentials clear --appId com.example.app --platform ios
 
 **Options:**
 
@@ -1767,8 +1760,8 @@ Update specific credentials without providing all of them again.
 Update existing credentials by providing only the fields you want to change.
 Platform is auto-detected from the options you provide.
 Examples:
-  npx @capgo/cli build credentials update --ios-provisioning-profile ./new-profile.mobileprovision
-  npx @capgo/cli build credentials update --local --keystore ./new-keystore.jks
+  npx @capgo/cli@latest build credentials update --ios-provisioning-profile ./new-profile.mobileprovision
+  npx @capgo/cli@latest build credentials update --local --keystore ./new-keystore.jks
 
 **Options:**
 
@@ -1814,10 +1807,10 @@ Interactively manage saved build credentials.
 Browse stored credentials, view what's configured, export a CI/CD-ready .env file,
 or delete a platform's credentials. Reuses the same TUI as `capgo init`.
 Examples:
-  npx @capgo/cli build credentials manage
-  npx @capgo/cli build credentials manage --appId com.example.app
-  npx @capgo/cli build credentials manage --appId com.example.app --platform ios
-  npx @capgo/cli build credentials manage --local
+  npx @capgo/cli@latest build credentials manage
+  npx @capgo/cli@latest build credentials manage --appId com.example.app
+  npx @capgo/cli@latest build credentials manage --appId com.example.app --platform ios
+  npx @capgo/cli@latest build credentials manage --local
 
 **Options:**
 
@@ -1837,6 +1830,13 @@ Export one saved Builder credential or configuration value.
 Raw mode prints only the exact stored value to stdout with no trailing newline.
 All failures are written to stderr and exit with status 1. Saved local/global
 configuration is used; environment variables are never exported.
+  npx @capgo/cli@latest build credentials export BUILD_CERTIFICATE_BASE64 --app-id com.example.app --platform ios --raw
+
+**Example:**
+
+```bash
+Example:
+```
 
 **Options:**
 
@@ -1860,7 +1860,7 @@ npx @capgo/cli@latest build credentials migrate
 Migrate legacy provisioning profile to the new multi-target format.
 Converts BUILD_PROVISION_PROFILE_BASE64 to CAPGO_IOS_PROVISIONING_MAP.
 Discovers the main bundle ID from your Xcode project automatically.
-  npx @capgo/cli build credentials migrate --platform ios
+  npx @capgo/cli@latest build credentials migrate --platform ios
 
 **Example:**