Skip to main content
Inspect a page or content DOM through the agent bridge, without CDP and without opening DevTools. inspect asks a running dev session what a document looks like right now. It can list open tabs, return a structural summary or raw HTML, and attach the last console lines for the same target. The session must run with the control channel unlocked: start it with extension dev --allow-control. A refusal names the missing flag, so a denied call tells you exactly how to restart the session.

​
When to use inspect

  • You want to confirm what your content script actually rendered into a page.
  • An agent needs tab ids to target eval or inspect calls precisely.
  • You want DOM state and the matching console tail in one machine-readable result.

​
Usage

​
Arguments and flags

There is no --deep-dom flag. Deep DOM support is a bridge capability the session reports internally, not something you toggle per call.

​
The discovery loop

Numeric tab ids make targeting deterministic. The intended flow is list first, then inspect:
--list-tabs needs the unlocked control channel but no eval token, so it works in any --allow-control session. The result is an array of {id, url, title, active, windowId} objects. Feed the id value straight into --tab here or in eval.

​
Console augmentation

--with-console merges a console array into the result: the last n log records for the same context and tab, read from the session’s logs.ndjson. This gives an agent DOM state and console evidence in a single round trip. The augmentation is best effort and never fails the command. Both output modes show it. Pretty mode prints the console lines after the DOM summary in the same [seq] LEVEL (context) message format logs uses, or (no console lines captured) when the tail is empty. --output json carries the raw records in the envelope’s console array.

​
Truncation

HTML larger than --max-bytes comes back truncated. Pretty mode prints a truncation notice on stderr, and --output json sets truncated: true in the envelope (see Result envelope).

​
Failure modes

  • No session found for the browser: E_SESSION_NOT_FOUND, with the exact extension dev command to run.
  • Session running without --allow-control: the connection is refused and the error names the flag.
  • Target surface not open, or a --tab id that no longer exists: E_TARGET_NOT_FOUND.
  • The target took longer than --timeout: E_TIMEOUT.
Run doctor when the same session refuses every verb and you want the first broken leg named.

​
Next steps

  • Run an expression in the page that you just inspected with eval.
  • Stream the same session’s logs continuously with logs.
  • Read the wider debugging workflow in Debugging.