Bugsnag Cli

bugsnag-cli

A fast, agent-friendly CLI for the Bugsnag Data Access API. Outputs JSON by default (ideal for agents and scripts), supports --format table for human reading.

When to read which reference

Pick the reference file that matches the user's intent:

If unsure, start with references/command-reference.md — it covers every command.

Quick overview

Authentication

Three methods (checked in this priority order):

1. Flag: --api-token TOKEN or -t TOKEN 2. Env var: BUGSNAG_API_TOKEN 3. Config file: ~/.bugsnag-cli.yaml (created via bugsnag configure --api-token TOKEN)

Available commands

Global flags

Output format

JSON lists return: {"data": [...], "total_count": N, "has_more": bool}

Single items return the object directly. Errors go to stderr as {"error": "..."}.

Exit codes

Common workflows

First setup:

bugsnag configure --api-token TOKEN
bugsnag organizations list
bugsnag projects list --org-id ORG_ID

Investigate an error: read references/investigate-error.md

Project health check: read references/project-health.md

Need exact flag syntax: read references/command-reference.md

bugsnag-cli Command Reference

Complete reference for all commands. All flags verified against actual CLI help output (v0.1.0).

Global Flags

Auth priority: Flag > Env var > Config file.

---

configure

Save configuration to ~/.bugsnag-cli.yaml (permissions 0600).

bugsnag configure --api-token TOKEN [--default-format FORMAT] [--default-per-page N] [--default-base-url URL]

---

organizations list

List organizations for the authenticated user.

bugsnag organizations list

No additional flags.

---

projects list

bugsnag projects list --org-id ORG_ID

projects get

bugsnag projects get --project-id PROJECT_ID

---

errors list

bugsnag errors list --project-id ID [--status STATUS] [--severity SEV] [--sort FIELD] [--direction DIR]

errors get

bugsnag errors get --project-id ID --error-id ERROR_ID

---

events list

bugsnag events list --project-id ID [--error-id ERROR_ID]

events get

bugsnag events get --project-id ID --event-id EVENT_ID

---

trends project

bugsnag trends project --project-id ID [--resolution RES] [--buckets-count N]

trends error

bugsnag trends error --project-id ID --error-id ERROR_ID

Important: trends error does NOT accept --resolution or --buckets-count.

---

collaborators list

bugsnag collaborators list --org-id ORG_ID

---

comments list

bugsnag comments list --project-id ID --error-id ERROR_ID

comments create

bugsnag comments create --project-id ID --error-id ERROR_ID --message "Your comment"

---

releases list

bugsnag releases list --project-id ID

---

stability trend

bugsnag stability trend --project-id ID [--release-stage STAGE]

---

version

bugsnag version

---

Output Format

JSON (default)

Lists: {"data": [...], "total_count": N, "has_more": bool}

Single items: object directly (no envelope).

Errors on stderr: {"error": "API error (401): Bad Credentials"}

Table

Use --format table for human-readable columnar output.

---

Exit Codes

Investigate a Bugsnag Error

Complete error investigation workflow — from "something is broken" to understanding the error's scope, history, and details.

Prerequisites

• bugsnag-cli configured with a valid API token
• A project ID (run bugsnag projects list --org-id ORG_ID to find it)

Investigation Workflow

Step 1: Find the Error

List errors with filters to narrow down what you're looking for:

# All open errors, sorted by most recent
bugsnag errors list --project-id PROJECT_ID --status open --sort last_seen --direction desc

# Only critical errors
bugsnag errors list --project-id PROJECT_ID --severity error --status open

# All errors across every page
bugsnag errors list --project-id PROJECT_ID --all-pages

Available filters:

• --status: open, fixed, snoozed, ignored
• --severity: info, warning, error
• --sort: created_at, last_seen, events, users, unsorted
• --direction: asc, desc

Step 2: Get Error Details

bugsnag errors get --project-id PROJECT_ID --error-id ERROR_ID

Returns full error details: class, message, context, severity, status, metadata.

Step 3: Examine Events (Occurrences)

Each error groups multiple event occurrences. Events contain stack traces, request data, device info, and custom metadata — this is where the actual debugging details live.

# List events for this specific error
bugsnag events list --project-id PROJECT_ID --error-id ERROR_ID

# Get full details of a specific event
bugsnag events get --project-id PROJECT_ID --event-id EVENT_ID

Step 4: Check Error Trends

bugsnag trends error --project-id PROJECT_ID --error-id ERROR_ID

Shows event counts bucketed by time period. Look for:

• Spikes — sudden increase, possibly tied to a deploy
• Sustained increases — growing problem
• Drops — a fix is working

Important: trends error does NOT accept --resolution or --buckets-count (only trends project does).

Step 5: Read Existing Comments

bugsnag comments list --project-id PROJECT_ID --error-id ERROR_ID

Step 6: Document Your Findings

bugsnag comments create --project-id PROJECT_ID --error-id ERROR_ID \
  --message "Investigated: root cause is X. Fix planned in PR #123."

Quick Investigation Script

Gather all info at once:

PROJECT_ID="your-project-id"
ERROR_ID="your-error-id"

# Error overview
bugsnag errors get --project-id "$PROJECT_ID" --error-id "$ERROR_ID"

# Recent events (stack traces)
bugsnag events list --project-id "$PROJECT_ID" --error-id "$ERROR_ID"

# Trend
bugsnag trends error --project-id "$PROJECT_ID" --error-id "$ERROR_ID"

# Existing comments
bugsnag comments list --project-id "$PROJECT_ID" --error-id "$ERROR_ID"

Tips

• Use --format table for quick human review during investigation
• Use JSON (default) when parsing results programmatically
• Event details are the most valuable for debugging — they contain stack traces
• --all-pages is useful when an error has many events to review

Bugsnag Project Health Assessment

Assess the overall health of a project — error counts, trends, stability, and release status.

Prerequisites

• bugsnag-cli configured with a valid API token
• A project ID (run bugsnag projects list --org-id ORG_ID to find it)

Health Assessment Workflow

Step 1: Project Overview

bugsnag projects get --project-id PROJECT_ID

Step 2: Error Summary

# Open errors sorted by impact (most events first)
bugsnag errors list --project-id PROJECT_ID --status open --sort events --direction desc

# Critical errors only
bugsnag errors list --project-id PROJECT_ID --status open --severity error

# All open errors across all pages
bugsnag errors list --project-id PROJECT_ID --status open --all-pages

Parse the JSON envelope for total counts:

bugsnag errors list --project-id PROJECT_ID --status open | jq '.total_count'

Step 3: Error Trends

# Daily trend — 2 weeks
bugsnag trends project --project-id PROJECT_ID --resolution 1d --buckets-count 14

# Hourly trend — last 24h
bugsnag trends project --project-id PROJECT_ID --resolution 1h --buckets-count 24

--resolution and --buckets-count are only available on trends project (not trends error).

Look for:

• Spikes — sudden increase, check recent releases
• Sustained increases — growing problem
• Drops after deployments — fixes working

Step 4: Stability Metrics

# Overall stability
bugsnag stability trend --project-id PROJECT_ID

# Production only
bugsnag stability trend --project-id PROJECT_ID --release-stage production

--release-stage is optional and accepts any stage name (production, staging, development, etc.).

Step 5: Recent Releases

bugsnag releases list --project-id PROJECT_ID

Compare release timestamps with error trend spikes to identify regressions.

Step 6: Team Activity

bugsnag organizations list
bugsnag collaborators list --org-id ORG_ID

Quick Health Check Script

PROJECT_ID="your-project-id"

bugsnag projects get --project-id "$PROJECT_ID"
bugsnag errors list --project-id "$PROJECT_ID" --status open | jq '.total_count'
bugsnag errors list --project-id "$PROJECT_ID" --status open --severity error --format table
bugsnag trends project --project-id "$PROJECT_ID" --resolution 1d --buckets-count 14
bugsnag stability trend --project-id "$PROJECT_ID" --release-stage production
bugsnag releases list --project-id "$PROJECT_ID" --format table

Interpreting Results

• Error count trending up — new bugs introduced, check recent releases
• Stability dropping — critical, likely a regression in a recent deploy
• High event count on a single error — one error dominating, prioritize it
• Many open errors with low event count — noise, consider snoozing old low-impact errors

Bugsnag CLI — Quick Start

Prerequisites

The bugsnag binary must be available in PATH. Installation options:

# Via Go
go install github.com/yoanbernabeu/bugsnag-cli@latest

# Or one-liner install script
curl -fsSL https://raw.githubusercontent.com/yoanbernabeu/bugsnag-cli/main/install.sh | sh

Step 1: Get an API Token

1. Log in to https://app.bugsnag.com 2. Go to Settings > My account > Auth tokens 3. Generate a new token (shown only once — store it safely)

Step 2: Configure Authentication

Three ways to authenticate (checked in this priority order):

The recommended approach for persistent use:

bugsnag configure --api-token YOUR_TOKEN

Optional: set defaults for format, pagination, and base URL:

bugsnag configure --api-token YOUR_TOKEN \
  --default-format table \
  --default-per-page 50 \
  --default-base-url https://api.bugsnag.com

The config file is written with mode 0600 (readable only by the owner).

Step 3: Verify Setup

# List organizations — confirms auth works
bugsnag organizations list

# List projects for an org
bugsnag projects list --org-id ORG_ID

Step 4: Explore Your Data

# List errors for a project (JSON)
bugsnag errors list --project-id PROJECT_ID

# Human-readable output
bugsnag errors list --project-id PROJECT_ID --format table

# Fetch all pages at once
bugsnag errors list --project-id PROJECT_ID --all-pages

# Filter to critical open errors
bugsnag errors list --project-id PROJECT_ID --status open --severity error

Typical First Session

1. bugsnag configure --api-token TOKEN — save credentials 2. bugsnag organizations list — find your org ID 3. bugsnag projects list --org-id ORG_ID — find your project ID 4. bugsnag errors list --project-id PROJECT_ID --format table — see recent errors 5. bugsnag errors list --project-id PROJECT_ID --status open --severity error — filter to critical open errors

Environment Variables