Sentire

A simple and user-friendly command-line interface for the Sentry API, written in Go.

Overview

Sentire provides an intuitive CLI for interacting with Sentry's API. It covers the essential Sentry operations including managing events, issues, projects, and organizations.

Key Features:

Multiple output formats: JSON, table, text, and markdown
Comprehensive API coverage for debugging workflows
Built-in pagination and rate limiting
Human-readable output for terminal usage
Machine-readable JSON for scripting

Installation

Prerequisites

A Sentry API token with appropriate permissions

Using Homebrew (macOS)

brew install andreagrandi/tap/sentire

Using Go install

go install github.com/andreagrandi/sentire/cmd/sentire@latest

Download pre-built binaries

Download the latest release for your platform from the releases page.

Building from source

Prerequisites: Go 1.26.1 or later

git clone <repository-url>
cd sentire
go build -o sentire ./cmd/sentire

Configuration

Sentire supports two methods for providing your Sentry API token: environment variables and configuration files.

Environment Variable (Recommended)

Set your Sentry API token as an environment variable:

export SENTRY_API_TOKEN=your_sentry_api_token_here

To avoid recording the token in your shell history, prefix the command with a space (when HISTCONTROL includes ignorespace) or load it from a credential manager.

Configuration File

Alternatively, you can create a configuration file at ~/.config/sentire/config.json:

{
  "sentry_api_token": "your_sentry_api_token_here"
}

Restrict access to that file so other users on the system cannot read it:

chmod 600 ~/.config/sentire/config.json

Configuration Precedence

If both are provided, the environment variable takes precedence over the configuration file. This allows you to:

Use a config file for your default token
Override it temporarily with an environment variable when needed

You can obtain an API token from your Sentry organization settings under "Auth Tokens".

API Base URL

By default Sentire targets Sentry's hosted API at https://sentry.io/api/0. To use a self-hosted Sentry instance, point SENTRY_API_BASE_URL at its API root:

export SENTRY_API_BASE_URL=https://sentry.example.com/api/0

When unset, the hosted API is used.

Token Safety in Output

Sentire never prints the configured token in standard, verbose, or error output: the API response body included in error messages and the final CLI error writer both run through a redaction helper that replaces the token with [REDACTED]. Do not share raw command output that contains your token (for example, if you pasted it directly into the URL or another argument), since only the configured token can be redacted automatically.

Usage

Basic Commands

# Show help
sentire --help

# List all your projects
sentire projects list

# Get a specific project
sentire projects get <organization> <project>

# List organization projects
sentire org list-projects <organization>

# Get organization statistics
sentire org stats <organization> --field="sum(quantity)"

Events and Issues

# List events for a project
sentire events list-project <organization> <project> --period=24h

# List events for an issue
sentire events list-issue <organization> <issue-id> --full

# List issues for an organization
sentire events list-issues <organization> --query="is:unresolved"

# Get a specific event
sentire events get-event <organization> <project> <event-id>

# Get a specific issue
sentire events get-issue <organization> <issue-id>

# Get an issue event (latest, oldest, recommended, or specific ID)
sentire events get-issue-event <organization> <issue-id> latest

Workflows and Troubleshooting

For recipe-style guidance — issue triage, URL inspection, reporting, format-by-format examples, and a troubleshooting checklist for auth, permissions, filters, and empty results — see docs/workflows.md.

Agent Workflows

Sentire is designed to be driven by both humans and AI agents. The context command prints an agent-oriented guide (also embedded as CONTEXT.md) covering authentication, output control, query syntax, and end-to-end workflows for issue triage, URL inspection, and release reporting:

# Print the agent guide
sentire context

# Discover commands and their JSON output schema
sentire describe
sentire describe events list-issues

For machine consumption, prefer --format json (default) or --format ndjson together with --fields to keep payloads small. The table, text, and markdown formats are intended for humans and are not stable for parsing.

URL Inspection

Sentire includes a special inspect command that can parse Sentry URLs directly:

# Inspect a Sentry issue URL and get detailed event information
sentire inspect "https://my-org.sentry.io/issues/123456789/"

# Get inspection results in table format
sentire inspect "https://my-org.sentry.io/issues/123456789/" --format table

# Get inspection results in markdown for documentation
sentire inspect "https://my-org.sentry.io/issues/123456789/" --format markdown

This command automatically extracts the organization and issue ID from the URL and fetches the most relevant debugging information.

Command Options

Most list commands support these common options:

--all: Fetch all pages of results (default: single page)
--format <format>: Output format (json, table, text, markdown) - default: json
--verbose: Enable verbose output

Output Formats

Sentire supports multiple output formats to suit different use cases:

json (default): Machine-readable JSON format, ideal for scripting and automation
table: Human-readable table format with borders, perfect for terminal viewing
text: Clean plain text format, great for simple parsing and readability
markdown: Documentation-friendly markdown format, useful for reports and documentation

Format Examples:

# Default JSON output
sentire events list-issues my-org

# Human-readable table format
sentire events list-issues my-org --format table

# Simple text format
sentire projects list --format text

# Markdown for documentation
sentire org stats my-org --format markdown

Time-based Filtering

Many commands support time filtering options:

--period <period>: Relative time period (e.g., "1h", "24h", "7d", "30d")
--start <iso-date>: Start time in ISO-8601 format
--end <iso-date>: End time in ISO-8601 format

Environment and Project Filtering

--environment <env>: Filter by environment (can be specified multiple times)
--project <id>: Filter by project ID (can be specified multiple times)

Examples

List recent high-priority issues

# JSON output (default)
sentire events list-issues my-org --query="is:unresolved issue.priority:[high,medium]" --period=7d

# Table format for better readability
sentire events list-issues my-org --query="is:unresolved issue.priority:[high,medium]" --period=7d --format table

Get all events for a project in the last 24 hours

# Get all events with table format
sentire events list-project my-org my-project --period=24h --all --full --format table

Get organization statistics for the last week

# Statistics in markdown format for reports
sentire org stats my-org --field="sum(quantity)" --period=7d --project=123 --project=456 --format markdown

List issues in production environment

# Production issues in text format
sentire events list-issues my-org --environment=production --period=24h --format text

Incident triage workflow

The table, text, and markdown formats are tuned for scanning incidents in a terminal. Issue lists surface status, priority, event/user counts, and a relative last seen time (e.g. 3h ago); single issue and event views keep the absolute timestamp and add the relative time in parentheses.

# Scan unresolved high/medium priority issues from the last 7 days
sentire events list-issues my-org \
  --query="is:unresolved issue.priority:[high,medium]" --period=7d --format table

# Drill into one issue with full timestamps
sentire events get-issue my-org 123456789 --format text

Output Format Comparison

Table format (great for terminal viewing):

┌───────────┬──────────────────────────────┬─────────┬────────────┬──────────┬────────┬───────┬───────────┬─────────────┐
│    ID     │            TITLE             │  LEVEL  │   STATUS   │ PRIORITY │ EVENTS │ USERS │ LAST SEEN │   PROJECT   │
├───────────┼──────────────────────────────┼─────────┼────────────┼──────────┼────────┼───────┼───────────┼─────────────┤
│ SENTIRE-1 │ TypeError in login component │ error   │ unresolved │ high     │ 45     │ 23    │ 3h ago    │ web-app     │
│ SENTIRE-2 │ API timeout on user endpoint │ warning │ resolved   │ medium   │ 12     │ 8     │ 2d ago    │ api-service │
└───────────┴──────────────────────────────┴─────────┴────────────┴──────────┴────────┴───────┴───────────┴─────────────┘

Text format (simple and scriptable):

Issues (2 total):

1. TypeError in login component
   ID: SENTIRE-1 | Status: unresolved | Level: error | Priority: high
   Events: 45 | Users: 23 | Last seen: 3h ago
   Project: web-app

2. API timeout on user endpoint
   ID: SENTIRE-2 | Status: resolved | Level: warning | Priority: medium
   Events: 12 | Users: 8 | Last seen: 2d ago
   Project: api-service

Markdown format (documentation-ready):

# Issues (2 total)

| ID | Title | Level | Status | Priority | Events | Users | Last Seen | Project |
|----|-------|-------|--------|----------|--------|-------|-----------|---------|
| SENTIRE-1 | TypeError in login component | error | unresolved | high | 45 | 23 | 3h ago | web-app |
| SENTIRE-2 | API timeout on user endpoint | warning | resolved | medium | 12 | 8 | 2d ago | api-service |

API Coverage

Sentire currently supports the following Sentry API endpoints:

Events

✅ List project events (/projects/{org}/{project}/events/)
✅ List issue events (/organizations/{org}/issues/{issue}/events/)
✅ List organization issues (/organizations/{org}/issues/)
✅ Get project event (/projects/{org}/{project}/events/{event}/)
✅ Get issue (/organizations/{org}/issues/{issue}/)
✅ Get issue event (/organizations/{org}/issues/{issue}/events/{event}/)

Organizations

✅ List organization projects (/organizations/{org}/projects/)
✅ Get organization statistics (/organizations/{org}/stats-summary/)

Projects

✅ List all projects (/projects/)
✅ Get project (/projects/{org}/{project}/)

Rate Limiting

Sentire automatically handles Sentry's rate limiting by:

Tracking rate limit headers from API responses
Displaying current rate limit status in verbose mode
Implementing proper error handling for rate limit exceeded scenarios

Error Handling

The CLI provides clear error messages for common scenarios:

Missing or invalid API token
API authentication failures
Resource not found errors
Network connectivity issues
Rate limiting

Development Setup

Git Hooks

To prevent formatting issues and ensure code quality, install the Git hooks:

# Install pre-commit hook for automatic Go formatting
./scripts/install-hooks.sh

The pre-commit hook will automatically format Go files using gofmt -s before each commit, ensuring consistency with CI requirements.

To format all Go files manually:

make fmt

To bypass the hook temporarily (not recommended):

git commit --no-verify

Changelog

User-visible changes are tracked in CHANGELOG.md. When you open a PR, add an entry under ## [Unreleased] for any change that affects commands, flags, output, packaging, configuration, dependencies that ship in the binary, or the agent-facing describe / context contracts. Pure internal refactors, tests, and CI tweaks do not need an entry.

Use the existing Added / Changed / Fixed / Technical subsections and keep each entry to a single line that leads with the user-facing effect. See AGENTS.md for the full workflow.

Testing

Run the test suite:

go test ./tests/ -v

The tests include:

Unit tests for the HTTP client
Integration tests for all API methods
Mock server tests for CLI commands

License

Licensed under the MIT License. See LICENSE for details.

Roadmap

Future enhancements may include:

✅ Multiple output formats (JSON, table, text, markdown) - COMPLETED
✅ Configuration file support - COMPLETED
Additional Sentry API endpoints
Export functionality (CSV, JSON files)

Name		Name	Last commit message	Last commit date
Latest commit History 70 Commits
.github		.github
.opencode/agent		.opencode/agent
cmd/sentire		cmd/sentire
docs		docs
internal		internal
pkg/models		pkg/models
scripts		scripts
tests		tests
.gitignore		.gitignore
.goreleaser.yaml		.goreleaser.yaml
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CONTEXT.md		CONTEXT.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
go.mod		go.mod
go.sum		go.sum
sentire_logo.png		sentire_logo.png

Folders and files

Latest commit

History

Repository files navigation

Sentire

Overview

Installation

Prerequisites

Using Homebrew (macOS)

Using Go install

Download pre-built binaries

Building from source

Configuration

Environment Variable (Recommended)

Configuration File

Configuration Precedence

API Base URL

Token Safety in Output

Usage

Basic Commands

Events and Issues

Workflows and Troubleshooting

Agent Workflows

URL Inspection

Command Options

Output Formats

Time-based Filtering

Environment and Project Filtering

Examples

List recent high-priority issues

Get all events for a project in the last 24 hours

Get organization statistics for the last week

List issues in production environment

Incident triage workflow

Output Format Comparison

API Coverage

Events

Organizations

Projects

Rate Limiting

Error Handling

Development Setup

Git Hooks

Changelog

Testing

License

Roadmap

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 3

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages