Skip to main content
Print or stream logs from every context of a running dev session. logs reads the log records that a dev session collects from your extension: background, content scripts, popup, options, and the rest. One command shows them all, merged in order, without opening a single DevTools window.

​
When to use logs

  • You want console output from the background worker and a content script in one stream.
  • An agent or script needs machine-readable log records instead of screen-scraped terminal text.
  • You want to check what an extension logged earlier without re-triggering the behavior.

​
Usage

By default, logs prints the records already on disk and exits. Add --follow to stay attached and stream new records live.

​
Arguments and flags

Choosing a --level includes that level plus everything more severe. --level warn shows warn and error. Plain console.log records count as info.

​
One-shot mode

Without --follow, the command reads dist/extension-js/<browser>/logs.ndjson directly and needs no live connection. The dev session appends every record to that file, so a one-shot read works even after you close the browser. If the file does not exist, logs prints a hint to start extension dev first and exits with code 1. Machine formats also emit a failure envelope with code E_LOGS_NOT_FOUND (see Result envelope).

​
Follow mode

--follow looks up the session’s readiness contract, connects to the control channel as a log consumer, and streams records as they happen. It needs a running dev session, but no unlock flag: log consumption is always allowed.
If the stream falls behind and the session drops records, logs prints a one-line gap notice on stderr with the drop count and reason. When you stop the stream with Ctrl+C, machine formats print one terminating success envelope with status interrupted, so a consumer can tell a clean stop from a crash. The exit code is 0. If no session is found for the chosen browser, the command fails with E_SESSION_NOT_FOUND and names the extension dev command to run.

​
Output formats

Pretty mode prints one line per record:
ndjson prints one raw JSON record per line, ideal for jq and log shippers. json pretty-prints each record over multiple lines. When stdout is not a TTY, ndjson is already the default, so piping needs no extra flag:

​
Examples

Show only errors and warnings from content scripts on a specific site:
Resume reading after a known record, useful for polling agents:

​
Next steps

  • Diagnose a session that logs --follow cannot reach with doctor.
  • Grab a DOM snapshot with the recent console tail in one call with inspect.
  • Read the wider debugging workflow in Debugging.
  • Review the machine failure format in Result envelope.