# 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
# or without installing:
npx @inspectdotdev/cli status
```

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 such as `"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
```

## 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` and `skills` — 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.