# Inspect — mobile web debugging for coding agents

You are reading the canonical agent setup instructions for Inspect
(https://inspect.dev): debug iOS Safari, Android Chrome, and
WebViews on real devices, simulators, and emulators from any machine.

## Install

```bash
npm install -g @inspectdotdev/cli@latest
inspect --version                  # simulator creation requires 3.2.0+
# or without installing:
npx @inspectdotdev/cli status
```

The workflow below targets CLI 3.2.0 or newer. If `devices create` is not
listed by `inspect agent-context`, update the CLI before provisioning. Typed
commands start and reuse their own daemon; do not also run the foreground
`inspect` server on the same ports.

Optional, if your environment supports agent skills:

```bash
npx skills add inspectdev/skills --skill mobile-debugging
```

## When to use Inspect

Use Inspect when a coding agent needs to reproduce, diagnose, or verify a
mobile web problem on iOS Safari, Android Chrome, an embedded WebView, a real
phone, or an iOS simulator. Use desktop browser tools instead for
desktop-only bugs, and native platform debuggers for native UI outside a
WebView.

## Quickstart (simulator, zero hardware, macOS)

```bash
inspect devices create "Inspect iPhone" "iPhone 17 Pro" --json
inspect devices boot <created-udid> --json
inspect devices list --json
inspect open http://localhost:3000 --json
inspect snapshot --interactive --json
inspect screenshot --json            # returns a PNG file path
```

`devices create` returns the simulator UDID as `data.created`. Its
optional third argument is an installed runtime name, version, or identifier,
such as `"iOS 26.5"`, `"26.5"`, or
`com.apple.CoreSimulator.SimRuntime.iOS-26-5`;
when omitted, Xcode chooses the newest compatible runtime. Creation is
available only on macOS with Xcode. Inspect does not create Android
emulators; Linux, Windows, and Android device types fail early with
`UNSUPPORTED_CAPABILITY`.

## Quickstart (physical iPhone or Android)

1. iPhone: connect via USB, unlock, tap "Trust This Computer", and
   enable Web Inspector (Settings → Safari → Advanced → Web Inspector).
   Android: enable USB debugging (Developer options) and accept the
   ADB prompt.
2. `inspect devices list --json` — if the device is missing, run
   `inspect doctor --json` and follow the suggestions in the output.

## The debugging loop

```bash
inspect open <url> --json
inspect snapshot --interactive --json      # WHAT is on screen (@eN refs)
inspect console list --types error --json  # WHY it is broken
inspect network list --failed --json       # failed requests
# ...edit the project code...
inspect reload --json
inspect console list --after <lastEventId> --json   # only what's new
```

Full workflow guidance ships with the CLI and always matches the
installed version:

```bash
inspect skills get mobile-debugging
```

If Inspect itself behaves incorrectly, is hard to use, or is missing a useful
capability, sign in and send a concise product report:

```bash
inspect login
inspect feedback "Snapshot refs need clearer recovery guidance" --category friction --json
```

The explicit submission works with `--no-telemetry`. It sends only that
message, its category, a generated receipt ID, the server-verified Inspect user
ID, and basic CLI/runtime metadata; it never attaches logs, page data, device
identifiers, URLs, or command history. The OAuth token remains in the Bearer
authorization header. Do not include secrets, and do not use it for bugs in
the website being debugged.

## Machine discovery

- Skill index (Agent Skills discovery v0.2.0):
  https://inspect.dev/.well-known/agent-skills/index.json
- Hosted skill: /.well-known/agent-skills/mobile-debugging/SKILL.md
- Pricing: https://inspect.dev/pricing.md · Auth:
  https://docs.inspect.dev/developers/authentication
- Once installed, prefer the CLI's own guidance: `inspect skills get
mobile-debugging` and `inspect agent-context` (version-matched).
- Chrome DevTools MCP and raw CDP capability matrix:
  https://docs.inspect.dev/developers/mcp

## Contract

- Every command supports `--json`: `{ok, command, data|error}` envelopes.
- Errors carry machine-readable codes and recovery suggestions.
- Exit codes: 0 ok, 2 bad arguments, 3 auth/entitlement, 4 device,
  5 target, 6 timeout, 7 unsupported capability.
- Free tier: every command works — the limit is time, not capability.
  Two 15-minute debug sessions a day, no login required. Talking to the
  device opens a session: `open`, `reload`, `navigate`, `snapshot`,
  `screenshot`, `attach`, `launch`, `console`, `network`, `issues`,
  `evaluate`, `dom`, `styles`, `devtools` and raw CDP traffic.
  Always free, never opens a session: `devices list`, `devices create`,
  `devices boot`, `devices shutdown`, `targets list`, `doctor`, `status`,
  `login`, `account`, `upgrade`, `agent-context`, `skills` and `feedback` — finding,
  provisioning, and diagnosing a device costs no budget, so a bad cable
  is free to discover. Everything inside an open session is unmetered.
- When the daily limit is reached you get `SUBSCRIPTION_REQUIRED` with
  `reason: "session-limit"`, the time the next session opens, and counts of
  what was captured. Run `inspect upgrade --json` for a checkout link to
  hand to your user ($29 one-week Pass: `inspect upgrade pass`, $79/yr Pro:
  `inspect upgrade pro`); entitlement refreshes automatically after
  payment. `inspect status --json` reports sessions used and remaining.

## Human handoff

`inspect devtools` opens Chrome DevTools for the current target without
disconnecting you. Humans who prefer a visual app can download Inspect
for desktop at https://inspect.dev/download.