appsignal-cli

A command-line interface for AppSignal error monitoring. Designed for AI coding agents to fetch and analyze error incidents with token-efficient output.

Installation

Arch Linux (AUR)

yay -S appsignal-cli

macOS/Linux (Homebrew)

brew install robzolkos/tap/appsignal-cli

Debian/Ubuntu

# Download the .deb for your architecture (amd64 or arm64)
curl -LO https://github.com/robzolkos/appsignal-cli/releases/latest/download/appsignal-cli_VERSION_amd64.deb
sudo dpkg -i appsignal-cli_VERSION_amd64.deb

Fedora/RHEL

# Download the .rpm for your architecture (x86_64 or aarch64)
curl -LO https://github.com/robzolkos/appsignal-cli/releases/latest/download/appsignal-cli-VERSION-1.x86_64.rpm
sudo rpm -i appsignal-cli-VERSION-1.x86_64.rpm

Windows

Download appsignal-cli-windows-amd64.exe from GitHub Releases and add it to your PATH.

With Go

go install github.com/robzolkos/appsignal-cli/cmd/appsignal@latest

From binary

Download the latest release for your platform from GitHub Releases and add it to your PATH.

From source

git clone https://github.com/robzolkos/appsignal-cli.git
cd appsignal-cli
go build -o appsignal-cli ./cmd/appsignal
./appsignal-cli --help

Configuration

Environment Variables

export APPSIGNAL_TOKEN=your-api-token
export APPSIGNAL_APP_ID=your-app-id

Config File

Create .appsignal-cli.yaml in your project root:

token: your-api-token
app_id: your-app-id
default_namespace: web
default_state: open
output:
  format: human  # human, json, compact
  compact: false
  no_color: false

Or initialize with:

# Create config in current directory
appsignal-cli config init

# Create config in ~/.config/appsignal-cli/
appsignal-cli config init --global

# Show current configuration
appsignal-cli config show

# Set a configuration value
appsignal-cli config set token your-api-token
appsignal-cli config set app_id your-app-id
appsignal-cli config set default_namespace web
appsignal-cli config set output.format compact

Config file locations (checked in order):

1. --config flag
2. .appsignal-cli.yaml in current directory (walks up to git root)
3. ~/.config/appsignal-cli/config.yaml

Usage

List Applications

# List all applications you have access to
appsignal-cli apps

List Incidents

# List open incidents
appsignal-cli incidents list

# Filter by state
appsignal-cli incidents list --state closed

# Filter by namespace
appsignal-cli incidents list --namespace background

# Filter by date (ISO 8601)
appsignal-cli incidents list --since 2024-01-15

# Filter by minimum occurrences
appsignal-cli incidents list --min-occurrences 10

# Pagination
appsignal-cli incidents list --limit 50 --offset 25

Get Incident Details

# Get incident with sample/backtrace
appsignal-cli incidents get 123

# With verbose output (includes params, session data)
appsignal-cli --verbose incidents get 123

Manage Incidents

# Close an incident
appsignal-cli incidents close 123

# Reopen an incident
appsignal-cli incidents reopen 123

Export to Markdown

# Export incident as markdown for AI bug fixing
appsignal-cli incidents export 123 -o bug-report.md

View Error Samples

# List recent error samples
appsignal-cli samples list

# Limit results
appsignal-cli samples list --limit 10

# Get detailed sample information
appsignal-cli samples get <sample-id>

Output Formats

# Human-readable (default)
appsignal-cli incidents list

# JSON (for scripting)
appsignal-cli --json incidents list

# Compact (minimal tokens for LLMs)
appsignal-cli --compact incidents list

Output Examples

Human Format (default)

INCIDENT #12345 [OPEN]
Exception: NoMethodError
Action: UsersController#show
Namespace: web
Last occurred: 2024-01-15 14:32:00 UTC
Occurrences: 147

Message:
undefined method `name' for nil:NilClass

Backtrace:
  app/controllers/users_controller.rb:42 in `show`
  app/models/user.rb:15 in `display_name`

Compact Format

#12345 NoMethodError: undefined method `name' for nil:NilClass
  UsersController#show (web) - 147 occurrences
  app/controllers/users_controller.rb:42
  app/models/user.rb:15

JSON Format

{
  "number": 12345,
  "state": "open",
  "exception_name": "NoMethodError",
  "action_names": ["UsersController#show"],
  "namespace": "web",
  "count": 147,
  "sample": {
    "exception": {
      "message": "undefined method `name' for nil:NilClass",
      "backtrace": [...]
    }
  }
}

Global Flags

Flag	Description
--json	JSON output
--compact	Minimal output for LLMs
--app-id	Override app ID
--token	Override API token
--config	Use specific config file
--no-color	Disable colors
-q, --quiet	Suppress non-error output
--verbose	Include params/session data
--timeout	HTTP timeout in seconds (default: 30)

Exit Codes

Code	Meaning
0	Success
1	General error
2	Authentication failed
3	Resource not found
4	API error

AI Agent Skill

This CLI includes a skill for AI coding agents (Claude Code, Cursor, etc.) that teaches them how to fetch and analyze AppSignal errors.

Install the Skill

npx skills add robzolkos/appsignal-cli

Once installed, your AI agent can automatically use the CLI to investigate errors, fetch incident details, and help debug issues in your codebase.

See skills/appsignal/SKILL.md for the full skill definition.

Development

# Build
make build

# Test
make test

# E2E tests (requires credentials)
export APPSIGNAL_TOKEN=...
export APPSIGNAL_APP_ID=...
make e2e

# Lint
make lint

License

MIT - see LICENSE