Contributing to Sentry CLI

This guide documents the patterns and conventions used in this CLI for consistency.

Command Patterns

We follow gh CLI conventions for best-in-class developer experience.

List Commands

List commands use optional positional arguments for context with smart auto-detection.

sentry org list [--limit N] [--json]
sentry project list [org] [--limit N] [--json]
sentry issue list [<org>/<project>] [--json]

Target syntax:

• <org>/<project> - Explicit organization and project (e.g., my-org/frontend)
• <org>/ - All projects in the specified organization
• <project> - Search for project by name across all accessible organizations
• (omit) - Auto-detect from DSN or config

Rationale: Positional arguments follow gh CLI conventions and are more concise than flags.

View Commands

View commands use optional positional arguments for the primary identifier, supporting auto-detection when omitted.

sentry org view [org-slug] [--json] [-w]                       # works with DSN if no arg
sentry project view [<org>/<project>] [--json] [-w]            # works with DSN if no arg
sentry issue view <issue-id> [--json] [-w]                     # issue ID required
sentry event view [<org>/<project>] <event-id> [--json] [-w]   # event ID required

Key insight: org view and project view mirror gh repo view - works in context (DSN) or with explicit arg.

Browser flag: All view commands support -w (or --web) to open the resource in your default browser instead of displaying it in the terminal.

Context Resolution

Context (org, project) is resolved in this priority order:

1. Positional arguments (<org>/<project>) - explicit, always wins
2. Config defaults - set via sentry config set
3. DSN auto-detection - from SENTRY_DSN env var or source code

Common Flags

Error Handling

Use ContextError for missing required context. This provides consistent formatting:

import { ContextError } from "../../lib/errors.js";

if (!resolved) {
  throw new ContextError(
    "Organization",                           // What is required
    "sentry org view <org-slug>",            // Primary usage
    ["Set SENTRY_DSN for auto-detection"]    // Alternatives
  );
}

This produces:

Organization is required.

Specify it using:
  sentry org view <org-slug>

Or:
  - Set SENTRY_DSN for auto-detection

Adding New Commands

1. Choose the right pattern: list (flags only) or view (optional positional)
2. Use existing utilities: resolveOrg(), resolveOrgAndProject() from lib/resolve-target.ts
3. Support JSON output: All commands should have --json flag
4. Support browser viewing: View commands should have -w/--web flag
5. Use ContextError: For missing context errors, use ContextError class
6. Add tests: E2E tests in test/e2e/ directory

Code Style

• Use TypeScript strict mode
• Prefer explicit types over inference for public APIs
• Document functions with JSDoc comments
• Keep functions small and focused