fix(init): refresh iOS run device selection

README.md

@@ -24,6 +24,8 @@ Follow the documentation here: https://capacitorjs.com/docs/getting-started/
 ## 📋 Table of Contents
 
 - 🚀 [Init](#init)
+- 📱 [Run](#run)
+  - [Device](#run-device)
 - 🔹 [Star](#star)
 - 🔹 [Star-all](#star-all)
 - 👨‍⚕️ [Doctor](#doctor)
@@ -86,14 +88,15 @@ npx @capgo/cli@latest init
 🚀 Initialize a new app in Capgo Cloud with step-by-step guidance.
 This includes adding code for updates, building, uploading your app, and verifying update functionality.
 Capgo bundles are web assets and can be fetched by anyone who knows the URL. Use encryption for banking, regulated, or other high-security apps.
+During the iOS run-on-device step, choose a physical iPhone/iPad or simulator. If you choose a physical device, the CLI lets you connect, unlock, and check again before it launches the app.
 
 **Example:**
 
 ```bash
 npx @capgo/cli@latest init YOUR_API_KEY com.example.app
 ```
 
-## <a id="options"></a> Options
+### <a id="init-options"></a> Options
 
 | Param          | Type          | Description          |
 | -------------- | ------------- | -------------------- |
@@ -103,6 +106,35 @@ npx @capgo/cli@latest init YOUR_API_KEY com.example.app
 | **--supa-anon** | <code>string</code> | Custom Supabase anon key (for self-hosting) |
 
 
+## <a id="run"></a> 📱 **Run**
+
+📱 Run Capacitor apps on devices from the CLI.
+
+### <a id="run-device"></a> 🔹 **Device**
+
+```bash
+npx @capgo/cli@latest run device
+```
+
+📱 Run your Capacitor app on a connected device or simulator.
+If you omit the platform in an interactive terminal, the command asks whether to start on iOS or Android.
+The command lists available devices and simulators, lets you reload the list, and runs with your selection.
+For iOS, this asks whether to use a physical iPhone/iPad or simulator before showing devices.
+Use --no-launch to print the resolved command without starting the app.
+
+**Example:**
+
+```bash
+npx @capgo/cli@latest run device ios --no-launch
+```
+
+**Options:**
+
+| Param          | Type          | Description          |
+| -------------- | ------------- | -------------------- |
+| **--no-launch** | <code>boolean</code> | Resolve and print the run command without starting the app |
+
+
 ## <a id="star"></a> 🔹 **Star**
 
 ```bash
@@ -122,7 +154,7 @@ npx @capgo/cli@latest star-all
 ⭐ Star all Capgo GitHub repositories with a small random delay between each request.
 If you do not pass repositories, this defaults to all Cap-go repositories whose name starts with `capacitor-`.
 
-## <a id="options"></a> Options
+### <a id="star-all-options"></a> Options
 
 | Param          | Type          | Description          |
 | -------------- | ------------- | -------------------- |
@@ -146,7 +178,7 @@ This command helps diagnose issues with your setup.
 npx @capgo/cli@latest doctor
 ```
 
-## <a id="options"></a> Options
+### <a id="doctor-options"></a> Options
 
 | Param          | Type          | Description          |
 | -------------- | ------------- | -------------------- |
@@ -170,7 +202,7 @@ Use --apikey=******** in any command to override it.
 npx @capgo/cli@latest login YOUR_API_KEY
 ```
 
-## <a id="options"></a> Options
+### <a id="login-options"></a> Options
 
 | Param          | Type          | Description          |
 | -------------- | ------------- | -------------------- |
@@ -1223,7 +1255,7 @@ and reports whether an update would be delivered, or explains why not.
 npx @capgo/cli@latest probe --platform ios
 ```
 
-## <a id="options"></a> Options
+### <a id="probe-options"></a> Options
 
 | Param          | Type          | Description          |
 | -------------- | ------------- | -------------------- |

package.json

@@ -73,6 +73,8 @@
     "test:checksum": "bun test/test-checksum-algorithm.mjs",
     "test:ci-prompts": "bun test/test-ci-prompts.mjs",
     "test:onboarding-recovery": "bun test/test-onboarding-recovery.mjs",
+    "test:onboarding-run-targets": "bun test/test-onboarding-run-targets.mjs",
+    "test:run-device-command": "bun test/test-run-device-command.mjs",
     "test:init-app-conflict": "bun test/test-init-app-conflict.mjs",
     "test:prompt-preferences": "bun test/test-prompt-preferences.mjs",
     "test:esm-sdk": "node test/test-sdk-esm.mjs",
@@ -81,7 +83,7 @@
     "test:version-detection:setup": "./test/fixtures/setup-test-projects.sh",
     "test:platform-paths": "bun test/test-platform-paths.mjs",
     "test:payload-split": "bun test/test-payload-split.mjs",
-    "test": "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:credentials && bun run test:credentials-validation && bun run test:build-zip-filter && bun run test:checksum && bun run test:ci-prompts && bun run test:onboarding-recovery && bun run test:init-app-conflict && bun run test:prompt-preferences && bun run test:esm-sdk && bun run test:mcp && bun run test:version-detection && bun run test:platform-paths && bun run test:payload-split"
+    "test": "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:credentials && bun run test:credentials-validation && bun run test:build-zip-filter && bun run test:checksum && bun run test:ci-prompts && bun run test:onboarding-recovery && bun run test:onboarding-run-targets && bun run test:run-device-command && bun run test:init-app-conflict && bun run test:prompt-preferences && bun run test:esm-sdk && bun run test:mcp && bun run test:version-detection && bun run test:platform-paths && bun run test:payload-split"
   },
   "devDependencies": {
     "@antfu/eslint-config": "^7.0.0",

skills/usage/SKILL.md

@@ -24,7 +24,8 @@ TanStack Intent skills should stay focused and under the validator line limit, s
 
 ### Project setup and diagnostics
 
-- `init [apikey] [appId]`: guided first-time setup for Capgo in a Capacitor app. The interactive flow now runs as a real Ink-based fullscreen onboarding so it uses the same UI stack as `build init` (alias: `build onboarding`), with a persistent dashboard, phase roadmap, progress cards, shared log area, and resume support. When dependency auto-detection fails on macOS, the flow opens a native file picker for `package.json` before falling back to manual path entry. If the local bundle ID already exists in the selected Capgo account, onboarding offers to reuse that app, then offers to delete and recreate it, then falls back to alternate bundle ID suggestions. If the user reuses a pending app that was already created in the web onboarding flow, the CLI syncs that selected dashboard app ID back into `capacitor.config.*` before the remaining steps continue. Outside that reused pending-app path, the CLI keeps using the local Capacitor app ID. It can also offer a final `npx skills add https://github.com/Cap-go/capgo-skills -g -y` install step before the GitHub support prompt; if accepted, the support menu includes `Cap-go/capgo-skills` alongside the updater-only and all-Capgo choices. If native platforms are missing, the onboarding can offer to run `cap add` for you. The updater step now verifies that `@capgo/capacitor-updater` is both declared in the selected `package.json` and resolvable from `node_modules`; if automatic install or later build/sync fails, onboarding prints the manual command, waits for the user to type `ready`, re-checks, and only then continues. If iOS sync validation fails during onboarding, the CLI can offer to run a one-line native reset command, wait for you to type `ready` after a manual fix, surface `doctor`, and save a support bundle before you leave the flow.
+- `init [apikey] [appId]`: guided first-time setup for Capgo in a Capacitor app. The interactive flow now runs as a real Ink-based fullscreen onboarding so it uses the same UI stack as `build init` (alias: `build onboarding`), with a persistent dashboard, phase roadmap, progress cards, shared log area, and resume support. When dependency auto-detection fails on macOS, the flow opens a native file picker for `package.json` before falling back to manual path entry. If the local bundle ID already exists in the selected Capgo account, onboarding offers to reuse that app, then offers to delete and recreate it, then falls back to alternate bundle ID suggestions. If the user reuses a pending app that was already created in the web onboarding flow, the CLI syncs that selected dashboard app ID back into `capacitor.config.*` before the remaining steps continue. Outside that reused pending-app path, the CLI keeps using the local Capacitor app ID. It can also offer a final `npx skills add https://github.com/Cap-go/capgo-skills -g -y` install step before the GitHub support prompt; if accepted, the support menu includes `Cap-go/capgo-skills` alongside the updater-only and all-Capgo choices. If native platforms are missing, the onboarding can offer to run `cap add` for you. The updater step now verifies that `@capgo/capacitor-updater` is both declared in the selected `package.json` and resolvable from `node_modules`; if automatic install or later build/sync fails, onboarding prints the manual command, waits for the user to type `ready`, re-checks, and only then continues. During the iOS run-on-device step, onboarding asks whether to use a physical iPhone/iPad or a simulator; for physical devices, it asks the user to connect and unlock the device, then offers a check-again loop before launching with the detected target. If iOS sync validation fails during onboarding, the CLI can offer to run a one-line native reset command, wait for you to type `ready` after a manual fix, surface `doctor`, and save a support bundle before you leave the flow.
+- `run device [platform]`: run a Capacitor app on a connected device or simulator. In an interactive terminal, omitting `[platform]` asks whether to start on iOS or Android. The command lists available devices and simulators, includes a reload option, and resolves the `cap run` command. Use `npx @capgo/cli@latest run device ios --no-launch` to exercise iOS physical/simulator target selection and print the resolved command without launching the app.
 - `login [apikey]`: store an API key locally.
 - `doctor`: inspect installation health and gather troubleshooting details.
 - `probe`: test whether the update endpoint would deliver an update.
@@ -81,6 +82,7 @@ Load `skills/organization-management/SKILL.md` when working with:
 
 ```bash
 npx @capgo/cli@latest init YOUR_API_KEY com.example.app
+npx @capgo/cli@latest run device ios --no-launch
 npx @capgo/cli@latest login YOUR_API_KEY
 npx @capgo/cli@latest doctor
 npx @capgo/cli@latest probe --platform ios

src/docs.ts

@@ -50,6 +50,8 @@ function getCommandEmoji(cmdName: string): string {
     emoji = '🔓'
   else if (cmdName.includes('debug'))
     emoji = '🐞'
+  else if (cmdName === 'run')
+    emoji = '📱'
   else if (cmdName.includes('doctor'))
     emoji = '👨‍⚕️'
   else if (cmdName.includes('login'))
@@ -195,8 +197,10 @@ export function generateDocs(filePath: string = './README.md', folderPath?: stri
     // Options table - for all commands (even command groups may have global options)
     if (cmd.options.length > 0) {
       if (!isSubcommand) {
-        // Only add the Options title for the main command
-        section += `## <a id="options"></a> Options\n\n`
+        const optionsAnchor = skipMainHeading ? 'options' : `${cmdName}-options`
+        const optionsHeading = skipMainHeading ? '##' : '###'
+        // In README each command is already a top-level section, so options sit underneath it.
+        section += `${optionsHeading} <a id="${optionsAnchor}"></a> Options\n\n`
       }
       else {
         section += `**Options:**\n\n`

src/index.ts

@@ -35,6 +35,7 @@ import { login } from './login'
 import { startMcpServer } from './mcp/server'
 import { addOrganization, deleteOrganization, listMembers, listOrganizations, setOrganization } from './organization'
 import { probe } from './probe'
+import { testRunDeviceCommand } from './run/device'
 import { getUserId } from './user/account'
 import { formatError } from './utils'
 
@@ -65,6 +66,7 @@ program
 
 This includes adding code for updates, building, uploading your app, and verifying update functionality.
 Capgo bundles are web assets and can be fetched by anyone who knows the URL. Use encryption for banking, regulated, or other high-security apps.
+During the iOS run-on-device step, choose a physical iPhone/iPad or simulator. If you choose a physical device, the CLI lets you connect, unlock, and check again before it launches the app.
 
 Example: npx @capgo/cli@latest init YOUR_API_KEY com.example.app`)
   .action(initApp)
@@ -73,6 +75,23 @@ Example: npx @capgo/cli@latest init YOUR_API_KEY com.example.app`)
   .option('--supa-host <supaHost>', optionDescriptions.supaHost)
   .option('--supa-anon <supaAnon>', optionDescriptions.supaAnon)
 
+const run = program
+  .command('run')
+  .description(`📱 Run Capacitor apps on devices from the CLI.`)
+
+run
+  .command('device [platform]')
+  .description(`📱 Run your Capacitor app on a connected device or simulator.
+
+If you omit the platform in an interactive terminal, the command asks whether to start on iOS or Android.
+The command lists available devices and simulators, lets you reload the list, and runs with your selection.
+For iOS, this asks whether to use a physical iPhone/iPad or simulator before showing devices.
+Use --no-launch to print the resolved command without starting the app.
+
+Example: npx @capgo/cli@latest run device ios --no-launch`)
+  .action(testRunDeviceCommand)
+  .option('--no-launch', `Resolve and print the run command without starting the app`)
+
 program
   .command('star [repository]')
   .description(`⭐ Star a Capgo GitHub repository to support the project.