CLI reference

The dbg CLI queries a running debugger session over IPC. It connects to the dev server's log store via Unix sockets (macOS/Linux) or Windows named pipes.

Usage

npx dbg <scope> <command> [flags]
npx dbg <command> [flags]

Scopes

`browser`

Query browser-side data. All browser commands filter entries where source is browser.

Command	Description
`npx dbg browser console`	Console logs (log, warn, error, debug, info)
`npx dbg browser errors`	Runtime errors and unhandled rejections
`npx dbg browser network`	Network requests (fetch, XHR, WebSocket)
`npx dbg browser cookies`	Document cookies
`npx dbg browser storage`	localStorage and sessionStorage
`npx dbg browser workers`	Service worker registrations
`npx dbg browser cache`	Cache Storage names and entry counts
`npx dbg browser permissions`	Browser permission states
`npx dbg browser quota`	Storage usage and quota

`server`

Query server-side data. All server commands filter entries where source is server.

Command	Description
`npx dbg server console`	Server console logs
`npx dbg server errors`	SSR and runtime errors

Top-level commands

Command	Description
`npx dbg status`	Display session metadata (ID, framework, port, uptime)
`npx dbg all`	Display all entries merged by timestamp (default)
`npx dbg sessions`	List all active debugger sessions

Flags

All flags are optional and can be combined with any command.

Output

Flag	Description
`--json`	Output as JSON instead of formatted text
`--limit <n>`	Maximum number of entries to return (default: 50)

Filtering

Flag	Description
`--last <duration>`	Time window filter. Accepts `30s`, `5m`, `1h`
`--level <level>`	Filter console entries by level (`log`, `warn`, `error`, `debug`, `info`)
`--status <code>`	Filter network entries by HTTP status code
`--failed`	Show only failed network requests

Detail view

Flag	Description
`--id <id>`	Show detail view for a single entry
`--ids <id1> <id2>`	Show detail view for multiple entries
`--headers`	Include request/response headers in network detail
`--body`	Include response body in network detail

Application state filters

Flag	Description
`--name <name>`	Filter cookies by name
`--key <key>`	Filter storage entries by key
`--type <type>`	Filter storage by type (`local` or `session`)

Session targeting

Flag	Description
`--port <port>`	Target a specific session by port number
`--session <id>`	Target a specific session by session ID

Other

Flag	Description
`--cwd <path>`	Override working directory for session discovery
`--help`	Display help text

Examples

View the last 30 seconds of browser console warnings:

npmpnpmbunyarn

npx dbg browser console --level warn --last 30s

pnpm dlx dbg browser console --level warn --last 30s

bun x dbg browser console --level warn --last 30s

yarn dlx dbg browser console --level warn --last 30s

Get failed network requests as JSON:

npmpnpmbunyarn

npx dbg browser network --failed --json

pnpm dlx dbg browser network --failed --json

bun x dbg browser network --failed --json

yarn dlx dbg browser network --failed --json

Inspect a specific network request with headers:

npmpnpmbunyarn

npx dbg browser network --id a1b2c3 --headers --body

pnpm dlx dbg browser network --id a1b2c3 --headers --body

bun x dbg browser network --id a1b2c3 --headers --body

yarn dlx dbg browser network --id a1b2c3 --headers --body

Find a specific cookie:

npmpnpmbunyarn

npx dbg browser cookies --name session_token

pnpm dlx dbg browser cookies --name session_token

bun x dbg browser cookies --name session_token

yarn dlx dbg browser cookies --name session_token

View only localStorage:

npmpnpmbunyarn

npx dbg browser storage --type local

pnpm dlx dbg browser storage --type local

bun x dbg browser storage --type local

yarn dlx dbg browser storage --type local

Look up a specific storage key:

npmpnpmbunyarn

npx dbg browser storage --key user_preferences

pnpm dlx dbg browser storage --key user_preferences

bun x dbg browser storage --key user_preferences

yarn dlx dbg browser storage --key user_preferences

Get everything from the last 5 minutes as JSON:

npmpnpmbunyarn

npx dbg all --last 5m --json

pnpm dlx dbg all --last 5m --json

bun x dbg all --last 5m --json

yarn dlx dbg all --last 5m --json

Multi-session support

When you run multiple dev servers (for example, a frontend, an API, and a docs site), each one gets its own debugger session. You can list all active sessions and target a specific one by port or ID.

List active sessions

npmpnpmbunyarn

npx dbg sessions

pnpm dlx dbg sessions

bun x dbg sessions

yarn dlx dbg sessions

  ID             Framework    Port    PID      Dir
  ────────────── ──────────── ─────── ──────── ────────────────────
  dev-a1b2c3     vite         5173    12345    /project/apps/web
  dev-d4e5f6     hono         3000    12346    /project/apps/api
  dev-g7h8i9     fastapi      8000    12347    /project/apps/py-api

Target by port

npmpnpmbunyarn

npx dbg --port 3000 browser console

pnpm dlx dbg --port 3000 browser console

bun x dbg --port 3000 browser console

yarn dlx dbg --port 3000 browser console

npmpnpmbunyarn

npx dbg --port 5173 browser network

pnpm dlx dbg --port 5173 browser network

bun x dbg --port 5173 browser network

yarn dlx dbg --port 5173 browser network

npmpnpmbunyarn

npx dbg --port 8000 server console

pnpm dlx dbg --port 8000 server console

bun x dbg --port 8000 server console

yarn dlx dbg --port 8000 server console

Target by session ID

npmpnpmbunyarn

npx dbg --session dev-a1b2c3 status

pnpm dlx dbg --session dev-a1b2c3 status

bun x dbg --session dev-a1b2c3 status

yarn dlx dbg --session dev-a1b2c3 status

npmpnpmbunyarn

npx dbg --session dev-d4e5f6 browser errors

pnpm dlx dbg --session dev-d4e5f6 browser errors

bun x dbg --session dev-d4e5f6 browser errors

yarn dlx dbg --session dev-d4e5f6 browser errors

Default behavior

Without --port or --session, the CLI finds the active session by walking parent directories from the current working directory:

macOS/Linux: looks for .debugger/bridge.sock
Windows: probes named pipes matching \\.\pipe\debugger-<hash> where <hash> is derived from the directory path

If your dev server runs in a subdirectory, use --cwd to point to it:

npmpnpmbunyarn

npx dbg status --cwd ./apps/web

pnpm dlx dbg status --cwd ./apps/web

bun x dbg status --cwd ./apps/web

yarn dlx dbg status --cwd ./apps/web

JSON output

When using --json, the CLI outputs structured JSON that AI agents can parse directly:

npmpnpmbunyarn

npx dbg browser console --json --limit 5

pnpm dlx dbg browser console --json --limit 5

bun x dbg browser console --json --limit 5

yarn dlx dbg browser console --json --limit 5

[
  {
    "type": "console",
    "level": "log",
    "args": ["User clicked button"],
    "timestamp": 1710000000000,
    "source": "browser",
    "browser": "Chrome",
    "id": "a1b2c3"
  }
]

The browser field identifies which browser generated the entry (Chrome, Edge, Brave, Firefox, Safari, Arc, and 40+ others).

CLI reference

Usage

Scopes

browser

server

Top-level commands

Flags

Output

Filtering

Detail view

Application state filters

Session targeting

Other

Examples

Multi-session support

List active sessions

Target by port

Target by session ID

Default behavior

JSON output

Search Documentation

`browser`

`server`