sentry-cli

sentry-cli for iOS

Installation

# macOS (recommended)
brew install getsentry/tools/sentry-cli

# npm
npm install -g @sentry/cli

# curl (macOS/Linux)
curl -sL https://sentry.io/get-cli/ | sh

# Pin a specific version
curl -sL https://sentry.io/get-cli/ | SENTRY_CLI_VERSION="3.3.5" sh

Update or uninstall:

sentry-cli update
sentry-cli uninstall

Configuration

sentry-cli loads configuration from multiple sources (in order of precedence): command-line flags, environment variables, .sentryclirc in the current directory (searched upward), and ~/.sentryclirc.

Project config file (.sentryclirc in project root)

[auth]
token=<your-auth-token>

[defaults]
org=<your-org>
project=<your-project>

Environment variables

export SENTRY_AUTH_TOKEN="<your-auth-token>"
export SENTRY_ORG="<your-org>"
export SENTRY_PROJECT="<your-project>"

Interactive login

sentry-cli login

# For self-hosted Sentry
sentry-cli --url https://your-sentry.example.com/ login

Setup verification

Verify auth, org, project, and scopes:

sentry-cli info

If the output shows missing scopes or auth errors, the token may need to be regenerated in Sentry (Settings > Auth Tokens).

Key scopes needed:

• project:read / project:write — releases
• event:read — issues and events
• org:read — org-level queries

Commands

List issues

Basic usage

# Recent unresolved issues
sentry-cli issues list -s unresolved --max-rows 10 --pages 1

# All issues (including ignored/resolved)
sentry-cli issues list --max-rows 10 --pages 1

# A specific issue by ID
sentry-cli issues list -i <ISSUE_ID>

CLI flags

Flag	Description
--max-rows N	Limit output to N rows
--pages N	Max pages to fetch (100 issues/page, default: 5)
-s STATUS	Filter by status: resolved, muted, unresolved
--query QUERY	Sentry search query (see syntax below)
-i ID	Fetch a specific issue by numeric ID

Query syntax (--query)

The --query flag accepts Sentry's structured search syntax. Combine multiple filters — they AND together by default.

By status and severity:

--query "is:unresolved"
--query "is:unresolved level:fatal"
--query "is:unresolved level:error"

is: values: unresolved, resolved, archived, assigned, unassigned, for_review level: values: fatal, error, warning, info

By error type and handling:

--query "error.type:NSInvalidArgumentException"
--query "error.unhandled:true"
--query "error.main_thread:true"

By release and environment:

--query "release:<bundle-id>@<version>+<build>"
--query "release.package:<bundle-id>"

By device and platform:

--query "device.family:iPhone"
--query "os.build:22A3354"
--query "app.in_foreground:true"

By time:

--query "age:-24h"              # first seen in the last 24 hours
--query "lastSeen:-1w"          # seen in the last week
--query "firstSeen:+30d"        # first seen more than 30 days ago
--query "timesSeen:>100"        # seen more than 100 times

Time suffixes: m (minutes), h (hours), d (days), w (weeks). - means "within the last", + means "older than".

By stack trace:

--query "stack.module:<ModuleName>"
--query "stack.function:<functionName>"
--query "stack.filename:<FileName>.swift"

By user:

--query "user.id:<user-id>"
--query "assigned:me"
--query "assigned:#<team-slug>"

Operators:

• Negation: !user.email:[email protected]
• Comparison: timesSeen:>100, timesSeen:<=10
• Wildcards: error.type:NS*Exception
• Lists: release:[1.0, 2.0] (OR)
• Has field: has:user.email

Combining filters:

# Fatal crashes on a specific app in the last 7 days
--query "is:unresolved level:fatal release.package:<bundle-id> lastSeen:-7d"

# Unhandled errors in a specific module
--query "is:unresolved error.unhandled:true stack.module:<ModuleName>"

Sorting by frequency (API only)

The CLI does not support sorting. For frequency-based ranking (most events first), use the Sentry API directly:

# Top 5 unresolved issues by event count
curl -sH "Authorization: Bearer $SENTRY_AUTH_TOKEN" \
  "https://sentry.io/api/0/projects/<org>/<project>/issues/?sort=freq&query=is:unresolved" \
  | jq '.[0:5] | .[] | {id: .id, shortId: .shortId, title: .title, count: .count}'

# Top fatal crashes by frequency
curl -sH "Authorization: Bearer $SENTRY_AUTH_TOKEN" \
  "https://sentry.io/api/0/projects/<org>/<project>/issues/?sort=freq&query=is:unresolved+level:fatal" \
  | jq '.[0:5] | .[] | {id: .id, shortId: .shortId, title: .title, count: .count, lastSeen: .lastSeen}'

# Sort options: freq (frequency), date (last seen), new (first seen), priority (Sentry priority)

List releases

sentry-cli releases list

Create and finalize a release

VERSION="<bundle-id>@<version>+<build>"

sentry-cli releases new "$VERSION"
sentry-cli releases set-commits "$VERSION" --local
sentry-cli releases finalize "$VERSION"

Use --auto instead of --local if the GitHub/GitLab repository integration is configured in Sentry.

Upload dSYMs

# From an xcarchive
sentry-cli debug-files upload --include-sources \
  /path/to/App.xcarchive/dSYMs

# With server-side processing wait
sentry-cli debug-files upload --wait /path/to/dsyms

# iOS with BCSymbolMaps (for bitcode builds with hidden symbols)
sentry-cli debug-files upload \
  --symbol-maps /path/to/BCSymbolMaps \
  /path/to/dsyms

# Validate before uploading
sentry-cli debug-files check /path/to/dSYM

# Find missing debug files when crashes show unsymbolicated addresses
sentry-cli debug-files find <debug-identifier>

List events

Events are individual occurrences — more granular than issues (which group related events together).

# Recent events
sentry-cli events list --max-rows 10 --pages 1

# Include user info and tags
sentry-cli events list --max-rows 10 -U -T

Flag	Description
--max-rows N	Limit output rows
--pages N	Max pages (100 events/page, default: 5)
-U / --show-user	Show the user column
-T / --show-tags	Show the tags column

Send a test event

Manually fire an event to verify the pipeline works end-to-end. Useful after setting up auth or changing SDK configuration.

# Simple test error
sentry-cli send-event -m "Test event from sentry-cli"

# With severity level
sentry-cli send-event -m "Test warning" -l warning

# With tags and extra data
sentry-cli send-event -m "Test from CI" -t environment:staging -e build_number:123

# Attach a release
sentry-cli send-event -m "Test event" -r "<bundle-id>@<version>+<build>"

# Send breadcrumbs from a log file (last 100 lines)
sentry-cli send-event -m "Crash context" --logfile /path/to/app.log --with-categories

-l levels: debug, info, warning, error (default), fatal

Logs (beta)

Query structured logs sent by the SDK (requires enableLogs: true in SDK configuration).

# Recent logs
sentry-cli logs list --max-rows 20

# Filter by level
sentry-cli logs list --query "level:error" --max-rows 50

# Live tail (streams new logs every 2 seconds)
sentry-cli logs list --live

# Live tail with custom interval
sentry-cli logs list --live --poll-interval 5

Flag	Description
--max-rows N	Max entries to fetch (default: 100, max: 1000)
--query QUERY	Filter with Sentry search syntax (e.g. level:error)
--live	Stream logs continuously
--poll-interval N	Seconds between polls in live mode (default: 2)

Monitors (cron)

Track scheduled jobs — Sentry alerts if a job doesn't check in on time or fails.

# List configured monitors
sentry-cli monitors list

# Wrap a command so Sentry tracks its execution
sentry-cli monitors run <monitor-slug> -- ./run-job.sh

# With schedule (creates the monitor if it doesn't exist)
sentry-cli monitors run <monitor-slug> \
  --schedule "0 3 * * *" \
  --timezone "Europe/London" \
  --checkin-margin 5 \
  --max-runtime 30 \
  -- ./run-job.sh

Flag	Description
--schedule CRON	Crontab schedule (creates monitor if needed)
--timezone TZ	tz database string (e.g. Europe/London)
--checkin-margin N	Minutes after expected time before marking missed
--max-runtime N	Minutes before marking timed out
-e ENV	Environment (default: production)

Create a deploy record

sentry-cli deploys new --release "$VERSION" -e production

List projects and repos

# List all projects in the org
sentry-cli projects list

# List linked repositories
sentry-cli repos list

Useful for verifying which projects and repos the token has access to, or checking if the repository integration is connected (needed for releases set-commits --auto).

Common iOS release workflow

VERSION=$(sentry-cli releases propose-version)
sentry-cli releases new "$VERSION"
sentry-cli debug-files upload --wait "$DWARF_DSYM_FOLDER_PATH"
sentry-cli releases set-commits "$VERSION" --local
sentry-cli releases finalize "$VERSION"
sentry-cli deploys new --release "$VERSION" -e production