CLI

Install and authenticate the DebugBundle CLI. Manage incidents, bundles, tokens, webhooks, alerts, and health checks from the terminal.

What the CLI Does

The DebugBundle CLI is your primary interface for:

Local-first debugging — Setup, capture, process, inspect, and resolve incidents without any cloud account
Cloud management — Connect a project, verify ingestion, manage tokens and webhooks
Agent integration — Every command outputs structured --json for AI-agent consumption via MCP or direct invocation
Log ingestion — Ingest and tail-watch log files with first-party parsers

Installation

Supported Node.js versions: 22.x through 26.x.

npm install -g @debugbundle/cli

Or as a project dev dependency:

npm install --save-dev @debugbundle/cli

Verify installation:

debugbundle --version
debugbundle --help

Update the CLI

To update a global CLI install to the latest version:

npm install -g @debugbundle/cli@latest

Authentication

The CLI uses two authentication modes:

Mode	Token Prefix	Use Case
Local-only	No token needed	`setup`, `process`, `inspect`, `doctor` — everything local
Connected	`dbundle_mem_*`	Cloud retrieval, token management, webhook CRUD, billing

debugbundle login
debugbundle login dbundle_mem_xxxxxxxxxxxx
debugbundle login --github

This saves a normal member token to ~/.debugbundle/auth.json. All subsequent cloud commands use this token automatically. Running debugbundle login with no explicit auth mode opens an interactive chooser in the terminal:

GitHub auto mode: try gh auth token, then fall back to device flow
GitHub device flow: show a GitHub URL plus short code
Existing member token: paste a dbundle_mem_* token created from the web app

--github first tries an existing gh auth token, then falls back to GitHub device flow if needed. Users who prefer the manual path, or who do not have GitHub, can still sign in with email in the web app and paste the resulting dbundle_mem_* token into debugbundle login.

Customize the API base URL:

debugbundle login dbundle_mem_xxxxxxxxxxxx --base-url https://api.self-hosted.example.com

Verify Identity

debugbundle whoami

Global Flags

Every command supports these flags:

Flag	Description
`--json`	Output machine-readable JSON instead of human-readable text
`--auth-file <path>`	Override the default auth file location (cloud commands only)

Exit Codes

Code	Meaning
`0`	Success
`1`	Internal error
`2`	Authentication error
`3`	Resource not found
`4`	Input validation error

Command Index

Local Workflow

Command	Description
`setup`	Initialize the DebugBundle scaffold in your project
`doctor`	Health check: profile, connection, auth, local state
`process`	Process local events into incidents and bundles
`validate`	Check scaffold files exist and are valid
`clean`	Remove local events, bundles, or both
`analyze`	Run analysis recipes on local incidents

Incident Management

Command	Description
`incidents`	List incidents (local, cloud, or both)
`inspect <id>`	View full incident detail
`resolve <id> [id ...]`	Mark one or more incidents as resolved
`reopen <id> [id ...]`	Reopen one or more resolved incidents
`bundle <id>`	Retrieve the debug bundle for an incident
`reproduce <id>`	Get reproduction artifacts (curl, httpie, JSON spec)
`logs <id>`	View event logs for an incident

Ingestion

Command	Description
`ingest <file>`	Ingest a log file as events
`watch`	Tail-watch a log file and continuously ingest

Cloud Operations

Command	Description
`login` / `login <token>` / `login --github`	Authenticate with the interactive chooser, a member token, or GitHub bootstrap
`whoami`	Show current auth identity
`connect`	Link local project to a cloud project
`verify local`	Verify the local scaffold is healthy
`verify cloud`	Verify cloud ingestion, synthetic trigger proofs, and app-event proof paths
`smoke`	End-to-end smoke test for cloud ingestion

Resource Management

Command	Description
`services`	List services for a project
`token project list/create/revoke`	Manage project tokens (SDK write-only)
`token member list/create/revoke`	Manage member tokens (CLI/API/MCP)
`webhook list/create/update/delete/test`	Manage webhooks
`webhook deliveries/retry`	View and retry webhook deliveries
`alert list/create/update/delete`	Manage alert rules
`health checks list/get/create/update/delete/test/results/daily-rollups`	Manage hosted availability checks
`billing get`	View billing summary
`billing trial start`	Start an eligible no-card trial
`billing capacity increase/schedule-reduction/cancel-reduction`	Manage billing capacity
`weekly-report list/create/update/delete`	Manage weekly reports
`capture-policy get/set`	View and update capture policy
`capture-rule list/create/update/delete/suggest/create-from-suggestion`	Manage project capture rules and create rules from noisy incidents
`project list/create/update/delete`	Manage projects
`probe activate/list/deactivate`	Manage debug probes
`project members list/invites/invite/cancel-invite/update-role/remove`	Manage project collaborators
`profile validate`	Validate the local project profile

Next Steps

Setup & Configuration — Initialize your project with debugbundle setup
Local Workflow — The complete offline debugging flow
SDKs Overview — Capture events from your application code

On this page