Capgo CLI Usage#

Use this skill as the entry point for the Capgo CLI skill set.

TanStack Intent skills should stay focused and under the validator line limit, so the Capgo CLI guidance is split into multiple skills:

• usage: high-level command routing, shared invocation rules, and quick command selection.
• observe: Observe query commands and MCP (summary, metrics, events, device, versions, routes).
• release-management: OTA bundle, channel, and encryption-key workflows.
• native-builds: native cloud build request and build-credential workflows.
• organization-management: organization, account, and deprecated organisation-alias workflows.

Shared invocation rules#

• 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.
• Commands inside an identifiable Capacitor project can automatically complete the Add Integration Code onboarding task when a source call to CapacitorUpdater.notifyAppReady() is detected. Detection is best effort and may be abandoned when the command exits. It does not confirm runtime readiness.
• A separate background check can complete Install Updater Plugin when @capgo/capacitor-updater is declared in the selected app's package.json and installed locally, including hoisted or symlinked workspace dependencies. Missing dependencies leave existing progress untouched; detection may be abandoned when the command exits.
• App-specific human-readable commands request the V4 onboarding checklist and optional billing summary alongside both local scans. Successful scanner reports are reconciled before choosing a setup notice; commands that change setup state refresh after success. Notices focus on unfinished work in the started list, with a brief mention of the other available product. Once OTA or either Builder platform is complete, unpaid organizations without credits see their trial expiry and organization plans link, with other setup options mentioned briefly. Exception: direct-offer organizations (created without a free trial, never paid, no credits) cannot upload or build until they subscribe, so their notice puts “Choose a plan to start using Capgo.” and the plans link first, before any checklist is complete, followed by a brief “Then …” setup mention; send these users to the plans link before setup work. Unknown billing never becomes a purchase prompt.
• Setup notices use a standalone rectangular box without a guide, status symbol, or app ID. They explain the next task and show one primary command or organization plans link. A secondary product gets a brief mention without another command. Trial reminders show time remaining without raw timestamps. Terminal colors highlight headings and primary actions, with yellow trial reminders and dim secondary suggestions. NO_COLOR and piped output stay uncolored.
• When the existing agent detector identifies an AI invocation, notices are plain stdout text without a box, guide, colors, or line wrapping, so links stay on one line, including on GitHub Actions. The end-of-command notice is a Capgo — next steps list: the unfinished setup step with its progress command and, while the organization is on an active free trial (billing available, not paying, no credits), one line with the trial end date, days left, and the trial-card plans link (worded for cloud builds when the notice is about Builder, otherwise for live updates) (?trial_card=1, without oid, so the console opens the add-card prompt for the current organization). It shows the trial line whether or not setup is complete, and on its own when no setup notice applies; its billing comes only from that notice's own progress snapshot. Nothing is addressed to the assistant and no secondary product is suggested. The start-of-command plan check prints no trial reminder for agents. After a successful bundle upload, agents get one line with the trial end date and the same link. Plan-required errors keep their existing copy. Output-mode rules still apply.
• Background setup notices appear after a successful command and use the existing five-second shutdown budget in interactive terminals, CI, and detected AI invocations. Otherwise, human-readable piped output only shows already-ready background notices, with no added background wait. Machine modes, account-wide commands, MCP, app todo, init, and build init do not receive background notices. The separate AI-only init completion notice described below can wait up to five seconds for a fresh status request; that request is not gated on TTY status, although init itself requires an interactive terminal. app todo and explicit setup commands retain their own checklist output.
• After supported interactive app, bundle, channel, organization, and key commands, plus build request, login, doctor, and get-qr, finish, pending background checks share a wait of up to five seconds. The CLI displays “Checking your setup...” with “Press Ctrl+C to skip.” and can exit sooner after the checks finish; pressing Ctrl-C during the wait exits immediately. CI and detected AI invocations also wait within the same budget without the banner. JSON, output-text, quiet, piped (outside CI and AI invocations), init, build init, and MCP runs do not add this background wait or banner. The separate AI-only init completion notice has its own five-second request budget. account whoami (and its account id alias) and bundle releaseType also exit without waiting.
• On GitHub Actions (GITHUB_ACTIONS=true), human-facing setup notices and existing preflight trial reminders use ::notice:: annotations and append the same guidance as Markdown to GITHUB_STEP_SUMMARY when available. Summary write failures cannot fail the deployment. A preflight trial reminder suppresses the background setup-notice plan prompt for the same organization during that invocation; preflight reminders themselves are not deduplicated.
• With analytics enabled, source scans emit scan_started and scan_ended events in the notify-app-ready channel with a shared attempt_id. The ended event includes scan duration, result, and todo-report outcome. An abandoned scan may have no ended event.
• With analytics enabled, entering the background-check wait emits background_checks_wait_started in the cli-usage channel. Its event properties include the command path, pending check count, grace period, and pending scan_attempt_ids. Telemetry shares the five-second wait budget and respects CAPGO_DISABLE_TELEMETRY and CAPGO_DISABLE_POSTHOG.
• Updater installation checks use the same scan events and attempt pairing in the updater-installed channel, with a separate attempt ID from the source scan. Telemetry opt-out does not prevent either onboarding check.
• Background onboarding requests trust the default Capgo API origin. For a custom API, explicitly select the self-host with --api-host <url>/functions/v1 where supported, or list trusted URL origins (including scheme and port) in CAPGO_TRUSTED_API_ORIGINS, separated by commas. Remote hosts require HTTPS; HTTP is permitted only for trusted loopback origins. Untrusted destinations and redirects are skipped without sending credentials to another host.
• Set CAPGO_SETUP_DEBUG=1 to diagnose background setup notices. Timing, HTTP status, scanner reports, shutdown deadlines, and suppression reasons go to stderr; credentials and response bodies are omitted. Keep stdout attached to your terminal when investigating the five-second wait: outside CI and AI invocations, piping or redirecting stdout skips it.
• 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#

Project setup and diagnostics#

• init [apikey] [appId]: when the app has a supported Builder-only checklist assigned by Capgo, continues with build init and its existing credential/resume flow before OTA setup. OTA-only and dual-assigned apps retain the existing setup flow. For other assignments, provides 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. At startup, onboarding still recommends a clean git worktree before file edits; dirty repos show Check again first and also offer a non-recommended Continue anyway override. 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 onboarding bundle upload fails, recovery can retry immediately or ask for the app's package.json and optional installed-dependency paths (app-local or hoisted node_modules) and then retry. 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 writes the new autoUpdate policy modes into config: "atBackground" for the default flow and "always" for instant updates. 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 the user enables instant updates, onboarding requires @capacitor/splash-screen for autoSplashscreen, offers to install it with the same auto-install/retry flow, and waits until it is declared and resolvable before writing config. 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.
• When init enters OTA setup, it enables the app's missing OTA dashboard checklist without resetting existing progress or removing Builder tasks. Checklist activation is independent of analytics; Builder-only handoffs do not activate OTA.
• init --no-analytics: disables init onboarding analytics and terminal replay for that run.
• After successful OTA init, detected AI sessions receive the plain next-steps notice (or the trial line alone) after the terminal UI closes. It uses the final selected app and authenticated API client, waits at most five seconds, and remains visible even if a trial warning appeared earlier. Ordinary terminal sessions receive no additional footer; analytics opt-out does not suppress it.
• init detects npm, npx, pnpm, and Yarn 2+ on Windows through their command shims and uses the selected package manager for installation, build, and sync steps. Yarn Classic is unsupported because the runner requires yarn dlx. Ensure the package manager is installed and available on PATH before starting.
• When init finds an existing app channel, it asks Yes, use it or No, create a new one before creating anything. It prefers the saved/production channel, then a default download channel, then another existing channel. Reusing continues onboarding with that channel; declining lets the user choose a new name.
• 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.
• observe summary|metrics|events|device|versions|routes: query Observe findings, timings, device timelines, and per-screen routes. Start with observe summary. Use observe device DEVICE_ID as the session timeline. Navigation uses app_nav + metadata.route (history/popstate/hashchange/appUrlOpen, no Expo Router). Pass --json for agents.

App-level operations#

• app add [appId]: create an app in Capgo Cloud.
• app list: list apps under the current account. Pass --filter-by-org-id <orgId> to list only apps from one organization, --show-org to include organization names, and --show-org-id to include organization IDs. The CLI warns that the filter can hide other accessible apps. Use npx @capgo/cli@latest app list --output-text for plain status text with an embedded CSV app table and no interactive terminal formatting.
• app delete [appId]: remove an app.
• app todo [appId] (alias: app todoList): show the versioned onboarding checklist with done, skipped, and pending tasks, using the same live progress checks as the dashboard. Supports legacy v3 flat steps and v4 OTA steps under setup.steps.ota when setup.ota_todo_list_version is the string "1". For a supported Builder-only V4 assignment, shows independent 🍎 iOS and 🤖 Android tasks, saved selection, timestamps, plain-language explanations of setup choices labeled Note: with each sentence on its own indented line, and actionable Warning: messages. Interactive terminals use colored headings and status markers; redirected output stays plain, and NO_COLOR disables colors. Detected AI invocations get the list as plain text and, during an active free trial, one extra pending item on the OTA or Builder list to add a payment method before the trial end date, worded for that list. Use npx @capgo/cli@latest build init to resume; only a backend-reported successful cloud build completes the final task. OTA-only apps retain the OTA checklist. Supported dual assignments offer OTA/Builder tabs in interactive terminals (Left/Right or Tab to switch, Up/Down or Page Up/Page Down to scroll, q/Esc to close). For scripts and AI agents, pass --list builder or --list ota to print one list and exit; dual non-interactive invocations require this selector. Single-list apps do not need it. Tab navigation does not change saved setup choices or progress. Skipped tasks count toward completed progress. Live checks can refresh saved OTA milestones; a warning means saved progress is shown for checks that failed. Requires app.read; additional checks depend on the key's read permissions. Omit the app ID to infer it from the current Capacitor project. Example: npx @capgo/cli@latest app todo com.example.app. Supports --list builder|ota, -a, --apikey, and --api-host.
• app set [appId]: update app settings such as name, icon, retention, metadata exposure, preview access with --preview or --no-preview, and optional device data collection with --collect-country / --no-collect-country (same pattern for platform, os-version, plugin-version, version-build, is-emulator, is-prod, install-source). Unchecked fields are not stored; /updates still uses the live request.
• app setting [path]: update Capacitor config values programmatically.
• app debug [appId]: listen for live-update debug events, optionally for one device.

Docs and agent integrations#

• MCP live-update onboarding (start_capgo_live_update_onboarding, then capgo_live_update_onboarding_next_step): before the test update it asks who makes the visible change (testChangeChoice). With manual, it waits until the user saved their own change (testChangeReady: true); the agent must not edit app files for them. With agent, the result gives the AI assistant guidelines (one small text or label change on the first screen in the app's own style, no banners, web files only, no cap sync); the assistant reports testChangeReady, testChangeFiles and testChangeDescription, the device check asks the user to look for that description, and completion tells the assistant to revert those files. Devices keep the test bundle until the next upload. A clean git check done before the test change still counts after the edit.
• 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. Observe queries use capgo_observe (start at view=summary). The server resolves the project from the client's MCP roots (the agent's workspace), not the folder it was spawned in, so a user-scoped install works across projects; clients without roots support call capgo_set_project_dir with the absolute app folder. Workspace roots with exactly one Capacitor app automatically select that app, including at startup without roots support. Multiple apps require an explicit app path. Every local MCP tool accepts projectDir or its cwd alias with the absolute app folder, including doctor, bundle/channel operations, builds, credentials, and both onboarding flows; it selects the project for this and subsequent calls. If both are supplied, they must select the same app. Relative tool paths resolve from that app. Calls and project switches are serialized, and nested build operations share the same CWD lock. The server's previous CWD is restored after every call without losing the selected app. All app metadata, scripts, source/config files, and dependency declarations use the selected app's own package.json, while installed dependencies can remain hoisted. Explicit package/dependency paths still override discovery. Hosted MCP tools cannot inspect local files: pass projectDir or cwd to capgo_get_upload_command, and run offline bundle/build packaging from the app directory. If @capacitor/core appears missing, verify the app folder before installing dependencies.

GitHub support commands#

• star [repository]: star one Capgo repository, defaulting to capacitor-updater.
• star-all [repositories...]: star all Capgo repositories matching the default filter, with delay and concurrency controls. The default set includes capacitor-* repositories plus Cap-go/CLI, Cap-go/capgo, and Cap-go/capgo-skills.

Related skills#

observe#

Load skills/observe/SKILL.md when working with:

• observe summary, observe metrics, observe events, observe device, observe versions, observe routes
• MCP capgo_observe

release-management#

Load skills/release-management/SKILL.md when working with:

• bundle upload, bundle list, bundle delete, bundle cleanup
• bundle compatibility, bundle releaseType, bundle zip, bundle encrypt, bundle decrypt
• channel add, channel list, channel delete, channel set, channel promote, channel currentBundle
• get-qr
• key save, key create, key delete_old

native-builds#

Load skills/native-builds/SKILL.md when working with:

• build request
• build needed
• build credentials save
• build credentials list
• build credentials clear
• build credentials update
• build credentials migrate

organization-management#

Load skills/organization-management/SKILL.md when working with:

• account whoami (alias: account id), account get, account set
• organization list, organization add, organization members, organization members-invite, organization members-role, organization members-remove, organization set, organization delete
• deprecated organisation aliases

Common command examples#

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
npx @capgo/cli@latest app add com.example.app --name "My App"
npx @capgo/cli@latest app list --filter-by-org-id YOUR_ORG_ID --show-org --show-org-id
npx @capgo/cli@latest get-qr com.example.app --channel production
npx @capgo/cli@latest star-all