Skip to content
Honeybadger Docs

Honeybadger CLI

The Honeybadger CLI gives you command-line access to the Honeybadger API for check-ins, deployments, metrics collection, and data queries. If you’ve been using our MCP server to integrate Honeybadger with AI agents, the CLI offers a similar feature set for direct terminal use.

Installation

Section titled “Installation”

The quickest way to install is via Homebrew:

Terminal window
brew install honeybadger-io/tap/honeybadger

You can also download binaries directly from the GitHub releases page or install with Go:

Terminal window
go install github.com/honeybadger-io/cli/cmd/hb@latest

This installs the hb command.

Authentication

Section titled “Authentication”

The CLI uses two types of credentials depending on which commands you’re running:

  • Project API key — For Reporting API commands (deploy, agent). Find your key in your project settings.
  • Personal auth token — For Data API commands (everything else). Find your token under the “Authentication” tab in your user settings.

You can provide credentials via environment variables, a configuration file, or command-line flags:

Environment Variables

Section titled “Environment Variables”
Terminal window
export HONEYBADGER_API_KEY=your-project-api-key       # For Reporting API
export HONEYBADGER_AUTH_TOKEN=your-personal-token     # For Data API
export HONEYBADGER_ENDPOINT=https://eu-api.honeybadger.io  # Optional, for EU region

Configuration File

Section titled “Configuration File”

Create a file at ~/.honeybadger-cli.yaml:

api_key: your-project-api-key
auth_token: your-personal-auth-token
endpoint: https://api.honeybadger.io

Command-line Flags

Section titled “Command-line Flags”
  • --api-key — Project API key (for Reporting API)
  • --auth-token — Personal auth token (for Data API)
  • --endpoint — API endpoint (default: https://api.honeybadger.io)
  • --config — Path to configuration file

Reporting API Commands

Section titled “Reporting API Commands”

These commands use your project API key (--api-key or HONEYBADGER_API_KEY).

agent

Section titled “agent”

Start a metrics reporting agent that collects system metrics and reports them to Honeybadger Insights.

Terminal window
hb agent --api-key PROJECT_API_KEY

Or with an environment variable:

Terminal window
export HONEYBADGER_API_KEY=PROJECT_API_KEY
hb agent

Metrics collected:

  • CPU — Usage percentages and load averages
  • Memory — Total, used, free, and available memory
  • Disk — Usage for all mounted filesystems

Optional flags:

  • -i, --interval — Reporting interval in seconds (default: 60)

See Host metrics for query examples and alternative collection methods.

deploy

Section titled “deploy”

Report a deployment to Honeybadger.

Terminal window
hb deploy --environment production --repository github.com/org/repo --revision abc123 --user johndoe

Required flags:

  • -e, --environment — Environment being deployed to (e.g., production)

Optional flags:

  • -r, --repository — Repository being deployed
  • -v, --revision — Revision or commit SHA being deployed
  • -u, --user — Local username of the person deploying

run

Section titled “run”

Run a command and report its status to Honeybadger’s check-in API. This wraps your command, captures its output and execution time, and reports the results.

Terminal window
hb run --id XyZZy -- /usr/local/bin/backup.sh

Or using a slug (requires API key):

Terminal window
hb run --slug daily-backup --api-key PROJECT_API_KEY -- pg_dump -U postgres mydb > backup.sql

The command will:

  • Execute your command and stream its output in real-time
  • Capture stdout, stderr, duration, and exit code
  • Report success or error status to Honeybadger
  • Exit with the same exit code as your command

Required flags (one of):

  • -i, --id — Check-in ID to report
  • -s, --slug — Check-in slug to report (requires API key)

Shell operators such as > are interpreted by your shell before hb runs, so redirection works as usual. If you need more complex shell features, wrap them in a shell script and invoke that script with hb run.

check-in

Section titled “check-in”

Report a simple check-in to Honeybadger without running a command. Use this when you want to signal that a task completed successfully from your own scripts.

Terminal window
hb check-in --id XyZZy

Or using a slug (requires API key):

Terminal window
hb check-in --slug daily-backup --api-key PROJECT_API_KEY

Required flags (one of):

  • -i, --id — Check-in ID to report
  • -s, --slug — Check-in slug to report (requires API key)

See Check-ins for more information on setting up check-ins in Honeybadger.

Data API Commands

Section titled “Data API Commands”

These commands use your personal auth token (--auth-token or HONEYBADGER_AUTH_TOKEN).

CommandDescription
accountsManage accounts, users, and invitations
check-insManage check-ins for cron job monitoring
commentsManage comments on faults
deploymentsView and manage deployment history
environmentsManage project environments
faultsView and manage faults (errors)
insightsExecute BadgerQL queries
projectsManage projects and view reports
statuspagesManage status pages
teamsManage teams and memberships
uptimeManage uptime monitoring

Output Formats

Section titled “Output Formats”

Most commands support the -o, --output flag:

  • table — Human-readable table format (default for list commands)
  • json — JSON output for scripting and automation
  • text — Plain text output (default for get commands)

JSON Input

Section titled “JSON Input”

Commands that accept --cli-input-json can receive input as:

  • Inline JSON: --cli-input-json '{"key": "value"}'
  • File path: --cli-input-json file:///path/to/file.json

Additional resources

Section titled “Additional resources”