Skip to main content
Inspect CLI gives coding agents direct access to mobile browsers on physical devices and iOS simulators. The canonical, copy-pasteable setup guide is inspect.dev/agent.md. Once installed, prefer inspect agent-context and inspect skills get mobile-debugging: both are generated from the installed CLI version and cannot drift from its commands.

​
Install and preflight

The simulator-provisioning workflow below requires CLI 3.2.0 or newer. If inspect devices create is absent, the registry has not supplied that release yet: use an existing simulator or update the CLI before continuing. Do not mix the foreground inspect server with typed commands on the same ports; typed commands start and reuse their own daemon automatically. Every command supports --json. Successful and failed responses use stable {ok, command, data | error} envelopes, and errors include recovery suggestions and meaningful exit codes.

​
Zero-hardware iOS quickstart (macOS)

The optional third devices create argument accepts an installed runtime name, version, or identifier—for example "iOS 26.5", "26.5", or com.apple.CoreSimulator.SimRuntime.iOS-26-5. Omit it to let Xcode choose the newest compatible runtime. Simulator creation requires macOS and Xcode.

​
Physical devices

  • iPhone/iPad: connect over USB, unlock, trust the computer, and enable Settings → Safari → Advanced → Web Inspector.
  • Android: enable Developer options and USB debugging, then accept the ADB authorization prompt.
  • Run inspect devices list --json. If the device is absent or not ready, run inspect doctor --json and follow its suggestions.

​
Agent debugging loop

Use --session <name> to keep an agent’s selected device, target, snapshot references, and evidence checkpoints separate from other concurrent tasks. inspect devtools opens Chrome DevTools for a human handoff without changing the command workflow.

​
Raw CDP and Chrome DevTools MCP

inspect cdp returns browser and page WebSocket URLs for custom CDP scripts. See MCP integrations for the supported iOS/WebKit capability matrix. Inspect returns explicit unsupported-capability errors where Chromium features have no honest WebKit or host equivalent; callers must not treat error text returned as MCP content as success.

​
Attach VS Code to mobile Safari

An agent can get the complete, version-matched setup playbook directly from the installed CLI:
It covers merging existing VS Code configuration, starting the CLI, source maps, and verifying source loading and breakpoints. Both inspect agent-context and inspect cdp point agents to this playbook. Open the page in Safari on your connected iPhone, iPad, or iOS simulator. With the Inspect CLI installed and available on your PATH, add this configuration to your project’s .vscode/launch.json:
Add the matching task to .vscode/tasks.json:
Select Attach to Safari (Inspect) in Run and Debug and press F5. The task starts or reuses the Inspect daemon, then exits so VS Code can attach. It does not need a background-task matcher. The daemon stays available after you stop debugging; run inspect stop when you want to shut it down. Use the port reported by inspect cdp if you configured a different one. Add "urlFilter": "https://your-app.example/*" to select a particular page when multiple targets are available. VS Code connects directly to Inspect’s browser endpoint; no compatibility proxy is needed. Let VS Code attach to the page: running inspect targets use auto beforehand can occupy Safari’s single Web Inspector connection. If another client already owns it, stop that debug session or close its inspector. For a CLI session you previously selected, inspect stop releases it; press F5 again to start Inspect and attach VS Code. Loaded Scripts should show the page’s JavaScript. Breakpoints in workspace TypeScript require the deployed page to serve matching source maps. Without source maps, set breakpoints in generated JavaScript under Loaded Scripts.
CLI 3.3.0 lacks the Target.attachToBrowserTarget handshake required by VS Code. This setup requires a build containing browser-session support. If that method returns an unsupported error, update Inspect before retrying.

​
Current access model

Login is optional for the free tier. Every debugging capability is available inside two free 15-minute sessions per day; device discovery, simulator provisioning, target listing, diagnostics, status, and account commands never open a session. SUBSCRIPTION_REQUIRED reports why access stopped and when a new free session becomes available. Run inspect upgrade --json only when the user wants a checkout link. Sending product feedback is the exception: it requires inspect login so the report can be tied to a real Inspect user.

​
Send feedback from an agent

If Inspect itself behaves incorrectly, is confusing, or is missing a useful capability, a signed-in agent can send a concise report without starting the daemon or opening a debug session:
Use bug, idea, friction, or other (the default). A successful response contains a receipt ID and means the feedback service accepted the message; a delivery failure returns a nonzero, retryable error instead of a false success. The explicit submission works with --no-telemetry and includes only the authored message, category, a generated receipt ID, the server-verified Inspect user ID, and basic CLI/runtime metadata. Inspect does not attach logs, page data, device identifiers, URLs, working-directory paths, or command history. The service derives the user ID from the OAuth bearer token; the token is never included in the body. Do not include secrets. This command is for feedback about Inspect, not for reporting a bug in the website being debugged.

​
Recovery

  • No devices: inspect doctor --json.
  • No targets: inspect launch safari --url <url> --json.
  • Upgrade/daemon mismatch: rerun the command; the CLI follows the daemon sidecar and replaces an older daemon automatically. If a foreground server owns the ports, stop that server first.
  • Stale snapshot ref: rerun inspect snapshot --interactive --json and use the new @eN reference.
  • Need the exact installed contract: inspect agent-context.