feat(cli): support scoped monorepo init

cli/README.md

@@ -98,6 +98,19 @@ The most complete [documentation is here](https://capgo.app/docs/).
 
 Join the [discord](https://discord.gg/VnYRvBfgA6) to get help.
 
+
+## Dynamic monorepos
+
+When a root `capacitor.config.ts` selects an app-specific source through an environment variable, keep that selector active and pass the source to Capgo:
+
+```bash
+CAP_APP=qr-code-reader npx @capgo/cli@latest init \
+  --package-json ./package.json \
+  --main-file ./projects/qr-code-reader/src/main.ts \
+  --capacitor-config ./env-configs/capacitor.config.qr-code-reader.ts
+```
+
+Capgo continues to load the root config while writing only the selected source. Use `--capacitor-config` on every config-changing CLI command, or the matching `capacitorConfig` SDK/MCP option.
 <!-- AUTO-GENERATED-DOCS-START -->
 ## 📑 Capgo CLI Commands
 
@@ -199,6 +212,9 @@ npx @capgo/cli@latest init YOUR_API_KEY com.example.app
 | **-i** | <code>string</code> | App icon path for display in Capgo Cloud |
 | **--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) |
+| **--package-json** | <code>string</code> | Package JSON for the Capacitor app to onboard (useful in monorepos) |
+| **--main-file** | <code>string</code> | Application entry file to update (useful in monorepos) |
+| **--capacitor-config** | <code>string</code> | Capacitor config source to update (useful with dynamic monorepo configs) |
 | **--no-analytics** | <code>boolean</code> | Disable init analytics and terminal replay for this run |
 
 
@@ -405,7 +421,8 @@ npx @capgo/cli@latest bundle upload com.example.app --path ./dist --channel prod
 | **--delta-only** | <code>boolean</code> | Upload only delta updates without full bundle for maximum speed (useful for large apps) |
 | **--no-delta** | <code>boolean</code> | Disable delta updates even if instant updates are enabled |
 | **--encrypted-checksum** | <code>string</code> | An encrypted checksum (signature). Used only when uploading an external bundle. |
-| **--auto-set-bundle** | <code>boolean</code> | Set the bundle in capacitor.config.json |
+| **--auto-set-bundle** | <code>boolean</code> | Set the bundle version in Capacitor config |
+| **--capacitor-config** | <code>string</code> | Capacitor config source to update (useful with dynamic monorepo configs) |
 | **--dry-upload** | <code>boolean</code> | Dry upload the bundle process: add the row in database without uploading files or updating channels (Used by Capgo for internal testing) |
 | **--package-json** | <code>string</code> | Paths to package.json files for monorepos (comma-separated) |
 | **--node-modules** | <code>string</code> | Paths to node_modules directories for monorepos (comma-separated) |
@@ -747,6 +764,7 @@ npx @capgo/cli@latest app setting plugins.CapacitorUpdater.defaultChannel --stri
 | -------------- | ------------- | -------------------- |
 | **--bool** | <code>string</code> | A value for the setting to modify as a boolean, ex: --bool true |
 | **--string** | <code>string</code> | A value for the setting to modify as a string, ex: --string "Production" |
+| **--capacitor-config** | <code>string</code> | Capacitor config source to update (useful with dynamic monorepo configs) |
 
 ### <a id="app-set"></a> ⚙️ **Set**
 
@@ -990,6 +1008,7 @@ npx @capgo/cli@latest key save --key ./path/to/key.pub
 | **-f** | <code>boolean</code> | Force generate a new one |
 | **--key** | <code>string</code> | Key path to save in Capacitor config |
 | **--key-data** | <code>string</code> | Key data to save in Capacitor config |
+| **--capacitor-config** | <code>string</code> | Capacitor config source to update (useful with dynamic monorepo configs) |
 
 ### <a id="key-create"></a> 🔨 **Create**
 
@@ -1013,6 +1032,7 @@ npx @capgo/cli@latest key create
 | Param          | Type          | Description          |
 | -------------- | ------------- | -------------------- |
 | **-f** | <code>boolean</code> | Force generate a new one |
+| **--capacitor-config** | <code>string</code> | Capacitor config source to update (useful with dynamic monorepo configs) |
 
 ### <a id="key-delete_old"></a> 🗑️ **Delete_old**
 
@@ -1028,6 +1048,12 @@ npx @capgo/cli@latest key delete_old
 npx @capgo/cli@latest key delete_old
 ```
 
+**Options:**
+
+| Param          | Type          | Description          |
+| -------------- | ------------- | -------------------- |
+| **--capacitor-config** | <code>string</code> | Capacitor config source to update (useful with dynamic monorepo configs) |
+
 
 ## <a id="account"></a> 👤 **Account**
 
@@ -1789,6 +1815,7 @@ npx @capgo/cli@latest notifications setup com.example.app
 | **--force** | <code>boolean</code> | Overwrite the helper file if it already exists |
 | **--no-install** | <code>boolean</code> | Skip installing the notifications package |
 | **--no-sync** | <code>boolean</code> | Skip Capacitor sync |
+| **--capacitor-config** | <code>string</code> | Capacitor config source to update (useful with dynamic monorepo configs) |
 
 
 ## <a id="probe"></a> 🔹 **Probe**
@@ -1823,7 +1850,7 @@ npx @capgo/cli@latest mcp
 🤖 Start the Capgo MCP (Model Context Protocol) server for AI agent integration.
 This command starts an MCP server that exposes Capgo functionality as tools for AI agents.
 The server communicates via stdio and is designed for non-interactive, programmatic use.
-Available tools exposed via MCP:
+Selected tools exposed via MCP:
   - capgo_list_apps, capgo_add_app, capgo_update_app, capgo_delete_app
   - capgo_upload_bundle, capgo_list_bundles, capgo_delete_bundle, capgo_cleanup_bundles
   - capgo_list_channels, capgo_add_channel, capgo_update_channel, capgo_delete_channel
@@ -1839,17 +1866,23 @@ Example usage with Claude Desktop:
     "mcpServers": {
       "capgo": {
         "command": "npx",
-        "args": ["@capgo/cli", "mcp"]
+        "args": ["@capgo/cli@latest", "mcp"]
       }
     }
   }
 
 **Example:**
 
 ```bash
-npx @capgo/cli mcp
+npx @capgo/cli@latest mcp
 ```
 
+## <a id="options-mcp"></a> Options (Mcp)
+
+| Param          | Type          | Description          |
+| -------------- | ------------- | -------------------- |
+| **--capacitor-config** | <code>string</code> | Capacitor config source to update (useful with dynamic monorepo configs) |
+
 
 
 <!-- AUTO-GENERATED-DOCS-END -->

cli/package.json

@@ -112,6 +112,8 @@
     "test:init-app-conflict": "bun test/test-init-app-conflict.mjs",
     "test:init-guardrails": "bun test/test-init-guardrails.mjs",
     "test:init-replay": "bun test/test-init-replay.mjs",
+    "test:capacitor-config-target": "bun test/test-capacitor-config-target.mjs",
+    "test:init-monorepo-targeting": "bun run test:capacitor-config-target && bun test/test-init-monorepo-targeting.mjs",
     "test:prompt-preferences": "bun test/test-prompt-preferences.mjs",
     "test:esm-sdk": "node test/test-sdk-esm.mjs",
     "test:auth-session": "bun test/test-auth-session.mjs",
@@ -158,7 +160,7 @@
     "test:ios-marketing-version": "bun test/test-ios-marketing-version.mjs",
     "test:platform-flow-contract": "bun test/test-platform-flow-contract.mjs",
     "test:tail-engine-shared": "bun test/test-tail-engine-shared.mjs",
-    "test": "bun run build && bun run test:helper-dce && bun run test:version-detection:setup && bun run test:bundle && bun run test:functional && bun run test:semver && bun run test:version-edge-cases && bun run test:regex && bun run test:upload && bun run test:fail-on-incompatible && bun run test:native-dependencies && bun run test:credentials && bun run test:credentials-validation && bun run test:android-service-account-validation && bun run test:build-zip-filter && bun run test:checksum && bun run test:build-needed && bun run test:ci-prompts && bun run test:ci-secrets && bun run test:android-onboarding-progress && bun run test:onboarding-telemetry && bun run test:v2-event-migration && bun run test:analytics && bun run test:analytics-error-category && bun run test:analytics-org-resolver && bun run test:supabase-perf && bun run test:preview-qr && bun run test:app-set-options && bun run test:mcp-analytics && bun run test:mcp-instructions && bun run test:mcp-live-update-onboarding && bun run test:mcp-stdout-guard && bun run test:mcp-platform-select && bun run test:mcp-explain-scopes && bun run test:mcp-oauth-reopen && bun run test:mcp-broker-oauth && bun run test:mcp-broker-session && bun run test:mcp-credentials-manage && bun run test:mcp-resume-prompt && bun run test:mcp-build-job && bun run test:mcp-build-tools && bun run test:app-created-source && bun run test:doctor-analytics && bun run test:posthog-exception && bun run test:build-platform-selection && bun run test:onboarding-recovery && bun run test:onboarding-progress && bun run test:onboarding-run-targets && bun run test:run-device-command && bun run test:init-app-conflict && bun run test:init-guardrails && bun run test:init-replay && bun run test:prompt-preferences && bun run test:esm-sdk && bun run test:mcp && bun run test:mcp-no-key-handshake && bun run test:auth-session && bun run test:version-detection && bun run test:platform-paths && bun run test:project-type-detection && bun run test:payload-split && bun run test:manifest-path-encoding && bun run test:macos-signing && bun run test:asc-key-protocol && bun run test:apple-api-import-helpers && bun run test:apple-api-verify-key && bun run test:bundle-id-detector && bun run test:apple-api-app-list && bun run test:app-verification && bun run test:pbxproj-parser && bun run test:ai-log-capture && bun run test:ai-analyze-flow && bun run test:cicd-failure-help && bun run test:ai-sse-parser && bun run test:ai-render-markdown && bun run test:ai-stream-markdown && bun run test:ai-onboarding-mode && bun run test:ai-fit && bun run test:platform-layout && bun run test:frame-fit && bun run test:onboarding-min-size && bun run test:min-size-gate && bun run test:shell-size-gate && bun run test:build-log-sanitize && bun run test:build-output-viewport && bun run test:diff-viewer-viewport && bun run test:build-complete-exit && bun run test:ai-analyze-stream && bun run test:support-mailto && bun run test:support-redact && bun run test:support-internal-log && bun run test:support-help-menu && bun run test:support-contact && bun run test:support-upload-prompt && bun run test:support-bundle-files && bun run test:self-update && bun run test:update-prompt && bun run test:apple-api-cert-create && bun run test:android-tail-engine && bun run test:android-tail-render && bun run test:android-tail-routing && bun run test:dev-gate-stripped && bun run test:frame-fit-ios-shared && bun run test:ios-confirm-app-id && bun run test:ios-create-new && bun run test:ios-e2e && bun run test:ios-flow-contract && bun run test:ios-import-discovery && bun run test:ios-import-export && bun run test:ios-import-pickers && bun run test:ios-import-recovery && bun run test:ios-recovery && bun run test:ios-resume && bun run test:ios-tail-handoff && bun run test:ios-tui-render && bun run test:p8-error && bun run test:ios-tui-routing && bun run test:ios-updater-sync-validation && bun run test:ios-verify-app && bun run test:ios-marketing-version && bun run test:platform-flow-contract && bun run test:tail-engine-shared && bun run test:prescan && bun run test:android-reporting-api && bun run test:android-app-verification && bun run test:android-rename && bun run test:appflow-auth && bun run test:appflow-api-map && bun run test:appflow-validate && bun run test:appflow-flow && bun run test:appflow-gapfill && bun run test:appflow-engine && bun run test:appflow-tail && bun run test:appflow-fetch && bun run test:appflow-sa-decode && bun run test:app-permission-helper && bun run test:organization-set-api-host",
+    "test": "bun run build && bun run test:helper-dce && bun run test:version-detection:setup && bun run test:bundle && bun run test:functional && bun run test:semver && bun run test:version-edge-cases && bun run test:regex && bun run test:upload && bun run test:fail-on-incompatible && bun run test:native-dependencies && bun run test:credentials && bun run test:credentials-validation && bun run test:android-service-account-validation && bun run test:build-zip-filter && bun run test:checksum && bun run test:build-needed && bun run test:ci-prompts && bun run test:ci-secrets && bun run test:android-onboarding-progress && bun run test:onboarding-telemetry && bun run test:v2-event-migration && bun run test:analytics && bun run test:analytics-error-category && bun run test:analytics-org-resolver && bun run test:supabase-perf && bun run test:preview-qr && bun run test:app-set-options && bun run test:mcp-analytics && bun run test:mcp-instructions && bun run test:mcp-live-update-onboarding && bun run test:mcp-stdout-guard && bun run test:mcp-platform-select && bun run test:mcp-explain-scopes && bun run test:mcp-oauth-reopen && bun run test:mcp-broker-oauth && bun run test:mcp-broker-session && bun run test:mcp-credentials-manage && bun run test:mcp-resume-prompt && bun run test:mcp-build-job && bun run test:mcp-build-tools && bun run test:app-created-source && bun run test:doctor-analytics && bun run test:posthog-exception && bun run test:build-platform-selection && bun run test:onboarding-recovery && bun run test:onboarding-progress && bun run test:onboarding-run-targets && bun run test:run-device-command && bun run test:init-monorepo-targeting && bun run test:init-app-conflict && bun run test:init-guardrails && bun run test:init-replay && bun run test:prompt-preferences && bun run test:esm-sdk && bun run test:mcp && bun run test:mcp-no-key-handshake && bun run test:auth-session && bun run test:version-detection && bun run test:platform-paths && bun run test:project-type-detection && bun run test:payload-split && bun run test:manifest-path-encoding && bun run test:macos-signing && bun run test:asc-key-protocol && bun run test:apple-api-import-helpers && bun run test:apple-api-verify-key && bun run test:bundle-id-detector && bun run test:apple-api-app-list && bun run test:app-verification && bun run test:pbxproj-parser && bun run test:ai-log-capture && bun run test:ai-analyze-flow && bun run test:cicd-failure-help && bun run test:ai-sse-parser && bun run test:ai-render-markdown && bun run test:ai-stream-markdown && bun run test:ai-onboarding-mode && bun run test:ai-fit && bun run test:platform-layout && bun run test:frame-fit && bun run test:onboarding-min-size && bun run test:min-size-gate && bun run test:shell-size-gate && bun run test:build-log-sanitize && bun run test:build-output-viewport && bun run test:diff-viewer-viewport && bun run test:build-complete-exit && bun run test:ai-analyze-stream && bun run test:support-mailto && bun run test:support-redact && bun run test:support-internal-log && bun run test:support-help-menu && bun run test:support-contact && bun run test:support-upload-prompt && bun run test:support-bundle-files && bun run test:self-update && bun run test:update-prompt && bun run test:apple-api-cert-create && bun run test:android-tail-engine && bun run test:android-tail-render && bun run test:android-tail-routing && bun run test:dev-gate-stripped && bun run test:frame-fit-ios-shared && bun run test:ios-confirm-app-id && bun run test:ios-create-new && bun run test:ios-e2e && bun run test:ios-flow-contract && bun run test:ios-import-discovery && bun run test:ios-import-export && bun run test:ios-import-pickers && bun run test:ios-import-recovery && bun run test:ios-recovery && bun run test:ios-resume && bun run test:ios-tail-handoff && bun run test:ios-tui-render && bun run test:p8-error && bun run test:ios-tui-routing && bun run test:ios-updater-sync-validation && bun run test:ios-verify-app && bun run test:ios-marketing-version && bun run test:platform-flow-contract && bun run test:tail-engine-shared && bun run test:prescan && bun run test:android-reporting-api && bun run test:android-app-verification && bun run test:android-rename && bun run test:appflow-auth && bun run test:appflow-api-map && bun run test:appflow-validate && bun run test:appflow-flow && bun run test:appflow-gapfill && bun run test:appflow-engine && bun run test:appflow-tail && bun run test:appflow-fetch && bun run test:appflow-sa-decode && bun run test:app-permission-helper && bun run test:organization-set-api-host",
     "test:build-platform-selection": "bun test/test-build-platform-selection.mjs",
     "test:ai-log-capture": "bun test/test-ai-log-capture.mjs",
     "test:ai-analyze-flow": "bun test/test-ai-analyze-flow.mjs",

cli/skills/release-management/SKILL.md

@@ -13,6 +13,7 @@ Use this skill for OTA update workflows in Capgo Cloud.
 - `appId` can often be inferred from the current Capacitor project.
 - Shared public flags often include `-a, --apikey`.
 - Preview QR workflows require app preview to be enabled before the QR code can be printed.
+- `--capacitor-config <path>` is global. With a dynamic root config selector such as `CAP_APP`, it keeps loading the root config and writes config changes to the selected app-specific source.
 
 ## Preview QR workflows
 

cli/skills/usage/SKILL.md

@@ -19,6 +19,7 @@ TanStack Intent skills should stay focused and under the validator line limit, s
 - Prefer `npx @capgo/cli@latest ...` in user-facing examples in this repo.
 - Many commands can infer `appId` and related config from the current Capacitor project.
 - Shared public flags commonly include `-a, --apikey <apikey>` and `--verbose` on commands that support verbose output.
+- `--capacitor-config <path>` is a global option for dynamic monorepos: Capacitor still loads the active root config, while config-writing commands update the selected app-specific source file. On `mcp`, the target remains active for the server lifetime so config-writing MCP tools use the same source.
 
 ## Use this skill for quick routing
 
@@ -42,7 +43,7 @@ TanStack Intent skills should stay focused and under the validator line limit, s
 
 ### Docs and agent integrations
 
-- `mcp`: start the Capgo MCP server for AI-agent integrations.
+- `mcp`: start the Capgo MCP server for AI-agent integrations; pass `--capacitor-config <path>` when its config-writing tools should target an app-specific source.
 
 ### GitHub support commands
 

cli/src/app/setting.ts

@@ -1,7 +1,7 @@
 import type { AppSettingOptions } from '../schemas/app'
 import { intro, log, outro } from '@clack/prompts'
 import { writeConfigUpdater } from '../config'
-import { formatError, getConfig } from '../utils'
+import { formatError, getConfigForWrite } from '../utils'
 
 export async function setSettingInternal(setting: string, options: AppSettingOptions, silent = false) {
   if (!silent)
@@ -26,7 +26,7 @@ export async function setSettingInternal(setting: string, options: AppSettingOpt
   }
 
   try {
-    const config = await getConfig()
+    const config = await getConfigForWrite()
     let baseObj = config.config as any
     const pathElements = setting.split('.')
 

cli/src/bundle/upload.ts

@@ -1120,7 +1120,7 @@ export async function uploadBundleInternal(preAppid: string, options: OptionsUpl
   if (options.autoSetBundle) {
     await updateConfigUpdater({ version: bundle })
     if (options.verbose)
-      log.info(`[Verbose] Auto-set bundle version in capacitor.config.json`)
+      log.info(`[Verbose] Auto-set bundle version in ${extConfig.path}`)
   }
 
   checkNotifyAppReady(options, path)