feat(config): support .sentryclirc config file for per-directory defaults

Add backward-compatible support for .sentryclirc INI config files.
The CLI walks up from CWD to find config files, merging them
(closest wins per-field) with ~/.sentryclirc as a global fallback.

Supported fields:
- [defaults] org, project, url
- [auth] token

Token and URL are applied via env shim (SENTRY_AUTH_TOKEN, SENTRY_URL).
Org and project are inserted into the resolution chain between env vars
and SQLite defaults with source tracking.

This enables per-directory project defaults in monorepos and seamless
migration from legacy sentry-cli.

Author: BYK

docs/src/content/docs/agent-guidance.md

@@ -12,7 +12,7 @@ Best practices and operational guidance for AI coding agents using the Sentry CL
 - **Use `sentry schema` to explore the API** — if you need to discover API endpoints, run `sentry schema` to browse interactively or `sentry schema <resource>` to search. This is faster than fetching OpenAPI specs externally.
 - **Use `sentry issue view <id>` to investigate issues** — when asked about a specific issue (e.g., `CLI-G5`, `PROJECT-123`), use `sentry issue view` directly.
 - **Use `--json` for machine-readable output** — pipe through `jq` for filtering. Human-readable output includes formatting that is hard to parse.
-- **The CLI auto-detects org/project** — most commands work without explicit targets by scanning for DSNs in `.env` files, source code, config defaults, and directory names. Only specify `<org>/<project>` when the CLI reports it can't detect the target or detects the wrong one.
+- **The CLI auto-detects org/project** — most commands work without explicit targets by checking `.sentryclirc` config files, scanning for DSNs in `.env` files and source code, and matching directory names. Only specify `<org>/<project>` when the CLI reports it can't detect the target or detects the wrong one.
 
 ## Design Principles
 
@@ -213,7 +213,7 @@ When querying the Events API (directly or via `sentry api`), valid dataset value
 - **Wrong issue ID format**: Use `PROJECT-123` (short ID), not the numeric ID `123456789`. The short ID includes the project prefix.
 - **Pre-authenticating unnecessarily**: Don't run `sentry auth login` before every command. The CLI detects missing/expired auth and prompts automatically. Only run `sentry auth login` if you need to switch accounts.
 - **Missing `--json` for piping**: Human-readable output includes formatting. Use `--json` when parsing output programmatically.
-- **Specifying org/project when not needed**: Auto-detection resolves org/project from DSNs, env vars, config defaults, and directory names. Let it work first — only add `<org>/<project>` if the CLI says it can't detect the target or detects the wrong one.
+- **Specifying org/project when not needed**: Auto-detection resolves org/project from `.sentryclirc` config files, DSNs, env vars, and directory names. Let it work first — only add `<org>/<project>` if the CLI says it can't detect the target or detects the wrong one.
 - **Confusing `--query` syntax**: The `--query` flag uses Sentry search syntax (e.g., `is:unresolved`, `assigned:me`), not free text search.
 - **Not using `--web`**: View commands support `-w`/`--web` to open the resource in the browser — useful for sharing links.
 - **Fetching API schemas instead of using the CLI**: Prefer `sentry schema` to browse the API and `sentry api` to make requests — the CLI handles authentication and endpoint resolution, so there's rarely a need to download OpenAPI specs separately.

docs/src/content/docs/configuration.md

@@ -1,9 +1,67 @@
 ---
 title: Configuration
-description: Environment variables and configuration options for the Sentry CLI
+description: Environment variables, config files, and configuration options for the Sentry CLI
 ---
 
-The Sentry CLI can be configured through environment variables and a local database. Most users don't need to set any of these — the CLI auto-detects your project from your codebase and stores credentials locally after `sentry auth login`.
+The Sentry CLI can be configured through config files, environment variables, and a local database. Most users don't need to set any of these — the CLI auto-detects your project from your codebase and stores credentials locally after `sentry auth login`.
+
+## Configuration File (`.sentryclirc`)
+
+The CLI supports a `.sentryclirc` config file using standard INI syntax. This is the same format used by the legacy `sentry-cli` tool, so existing config files are automatically picked up.
+
+### How It Works
+
+The CLI looks for `.sentryclirc` files by walking up from your current directory toward the filesystem root. If multiple files are found, values from the closest file take priority, with `~/.sentryclirc` serving as a global fallback.
+
+```ini
+[defaults]
+org = my-org
+project = my-project
+
+[auth]
+token = sntrys_...
+```
+
+### Supported Fields
+
+| Section | Key | Description |
+|---------|-----|-------------|
+| `[defaults]` | `org` | Default organization slug |
+| `[defaults]` | `project` | Default project slug |
+| `[defaults]` | `url` | Sentry base URL (for self-hosted) |
+| `[auth]` | `token` | Auth token (mapped to `SENTRY_AUTH_TOKEN`) |
+
+### Monorepo Setup
+
+In monorepos, place a `.sentryclirc` at the repo root with your org, then add per-package configs with just the project:
+
+```
+my-monorepo/
+  .sentryclirc              # [defaults] org = my-company
+  packages/
+    frontend/
+      .sentryclirc          # [defaults] project = frontend-web
+    backend/
+      .sentryclirc          # [defaults] project = backend-api
+```
+
+When you run a command from `packages/frontend/`, the CLI resolves `org = my-company` from the root and `project = frontend-web` from the closest file.
+
+### Resolution Priority
+
+When the CLI needs to determine your org and project, it checks these sources in order:
+
+1. **Explicit CLI arguments** — `sentry issue list my-org/my-project`
+2. **Environment variables** — `SENTRY_ORG` / `SENTRY_PROJECT`
+3. **`.sentryclirc` config file** — walked up from CWD, merged with `~/.sentryclirc`
+4. **DSN auto-detection** — scans source code and `.env` files
+5. **Directory name inference** — matches your directory name against project slugs
+
+The first source that provides both org and project wins. For org-only commands, only the org is needed.
+
+### Backward Compatibility
+
+If you previously used the legacy `sentry-cli` and have a `~/.sentryclirc` file, the new CLI reads it automatically. The `[defaults]` and `[auth]` sections are fully compatible. The `[auth] token` value is mapped to the `SENTRY_AUTH_TOKEN` environment variable internally (only if the env var is not already set).
 
 ## Environment Variables
 

docs/src/content/docs/features.md

@@ -7,7 +7,7 @@ The Sentry CLI includes several features designed to streamline your workflow, e
 
 ## DSN Auto-Detection
 
-The CLI automatically detects your Sentry project from your codebase, eliminating the need to specify the target for every command.
+The CLI automatically detects your Sentry project from your codebase, eliminating the need to specify the target for every command. DSN detection is one part of the [resolution priority chain](./configuration/#resolution-priority) — it runs after checking for explicit arguments, environment variables, and `.sentryclirc` config files.
 
 ### How It Works
 
@@ -19,6 +19,10 @@ DSN detection follows this priority order (highest first):
 
 When a DSN is found, the CLI resolves it to your organization and project, then caches the result for fast subsequent lookups.
 
+:::tip
+For monorepos or when DSN detection picks up the wrong project, use a [`.sentryclirc` config file](./configuration/#configuration-file-sentryclirc) to pin your org/project explicitly.
+:::
+
 ### Supported Languages
 
 The CLI can detect DSNs from source code in these languages:

plugins/sentry-cli/skills/sentry-cli/SKILL.md

@@ -22,7 +22,7 @@ Best practices and operational guidance for AI coding agents using the Sentry CL
 - **Use `sentry schema` to explore the API** — if you need to discover API endpoints, run `sentry schema` to browse interactively or `sentry schema <resource>` to search. This is faster than fetching OpenAPI specs externally.
 - **Use `sentry issue view <id>` to investigate issues** — when asked about a specific issue (e.g., `CLI-G5`, `PROJECT-123`), use `sentry issue view` directly.
 - **Use `--json` for machine-readable output** — pipe through `jq` for filtering. Human-readable output includes formatting that is hard to parse.
-- **The CLI auto-detects org/project** — most commands work without explicit targets by scanning for DSNs in `.env` files, source code, config defaults, and directory names. Only specify `<org>/<project>` when the CLI reports it can't detect the target or detects the wrong one.
+- **The CLI auto-detects org/project** — most commands work without explicit targets by checking `.sentryclirc` config files, scanning for DSNs in `.env` files and source code, and matching directory names. Only specify `<org>/<project>` when the CLI reports it can't detect the target or detects the wrong one.
 
 ### Design Principles
 
@@ -223,7 +223,7 @@ When querying the Events API (directly or via `sentry api`), valid dataset value
 - **Wrong issue ID format**: Use `PROJECT-123` (short ID), not the numeric ID `123456789`. The short ID includes the project prefix.
 - **Pre-authenticating unnecessarily**: Don't run `sentry auth login` before every command. The CLI detects missing/expired auth and prompts automatically. Only run `sentry auth login` if you need to switch accounts.
 - **Missing `--json` for piping**: Human-readable output includes formatting. Use `--json` when parsing output programmatically.
-- **Specifying org/project when not needed**: Auto-detection resolves org/project from DSNs, env vars, config defaults, and directory names. Let it work first — only add `<org>/<project>` if the CLI says it can't detect the target or detects the wrong one.
+- **Specifying org/project when not needed**: Auto-detection resolves org/project from `.sentryclirc` config files, DSNs, env vars, and directory names. Let it work first — only add `<org>/<project>` if the CLI says it can't detect the target or detects the wrong one.
 - **Confusing `--query` syntax**: The `--query` flag uses Sentry search syntax (e.g., `is:unresolved`, `assigned:me`), not free text search.
 - **Not using `--web`**: View commands support `-w`/`--web` to open the resource in the browser — useful for sharing links.
 - **Fetching API schemas instead of using the CLI**: Prefer `sentry schema` to browse the API and `sentry api` to make requests — the CLI handles authentication and endpoint resolution, so there's rarely a need to download OpenAPI specs separately.
@@ -436,29 +436,8 @@ Browse the Sentry API schema
 
 → Full flags and examples: `references/schema.md`
 
-## Global Options
-
-All commands support the following global options:
-
-- `--help` - Show help for the command
-- `--version` - Show CLI version
-- `--log-level <level>` - Set log verbosity (`error`, `warn`, `log`, `info`, `debug`, `trace`). Overrides `SENTRY_LOG_LEVEL`
-- `--verbose` - Shorthand for `--log-level debug`
-
 ## Output Formats
 
-### JSON Output
+Most commands support `--json` flag for JSON output, making it easy to integrate with other tools.
 
-Most list and view commands support `--json` flag for JSON output, making it easy to integrate with other tools:
-
-```bash
-sentry org list --json | jq '.[] | .slug'
-```
-
-### Opening in Browser
-
-View commands support `-w` or `--web` flag to open the resource in your browser:
-
-```bash
-sentry issue view PROJ-123 -w
-```
+View commands support `-w` or `--web` flag to open the resource in your browser.

plugins/sentry-cli/skills/sentry-cli/references/api.md

@@ -26,44 +26,4 @@ Make an authenticated API request
 - `--verbose - Include full HTTP request and response in the output`
 - `-n, --dry-run - Show the resolved request without sending it`
 
-**Examples:**
-
-```bash
-# List organizations
-sentry api organizations/
-
-# Get a specific issue
-sentry api issues/123456789/
-
-# Create a release
-sentry api organizations/my-org/releases/ \
-  -X POST -F version=1.0.0
-
-# With inline JSON body
-sentry api issues/123456789/ \
-  -X POST -d '{"status": "resolved"}'
-
-# Update an issue status
-sentry api issues/123456789/ \
-  -X PUT -F status=resolved
-
-# Assign an issue
-sentry api issues/123456789/ \
-  -X PUT --field assignedTo="user@example.com"
-
-sentry api projects/my-org/my-project/ -X DELETE
-
-# Add custom headers
-sentry api organizations/ -H "X-Custom: value"
-
-# Read body from a file
-sentry api projects/my-org/my-project/releases/ -X POST --input release.json
-
-# Verbose mode (shows full HTTP request/response)
-sentry api organizations/ --verbose
-
-# Preview the request without sending
-sentry api organizations/ --dry-run
-```
-
 All commands also support `--json`, `--fields`, `--help`, `--log-level`, and `--verbose` flags.

plugins/sentry-cli/skills/sentry-cli/references/auth.md

@@ -20,41 +20,17 @@ Authenticate with Sentry
 - `--timeout <value> - Timeout for OAuth flow in seconds (default: 900) - (default: "900")`
 - `--force - Re-authenticate without prompting`
 
-**Examples:**
-
-```bash
-sentry auth login
-
-sentry auth login --token YOUR_SENTRY_API_TOKEN
-
-SENTRY_URL=https://sentry.example.com sentry auth login
-
-SENTRY_URL=https://sentry.example.com sentry auth login --token YOUR_TOKEN
-```
-
 ### `sentry auth logout`
 
 Log out of Sentry
 
-**Examples:**
-
-```bash
-sentry auth logout
-```
-
 ### `sentry auth refresh`
 
 Refresh your authentication token
 
 **Flags:**
 - `--force - Force refresh even if token is still valid`
 
-**Examples:**
-
-```bash
-sentry auth refresh
-```
-
 ### `sentry auth status`
 
 View authentication status
@@ -63,28 +39,10 @@ View authentication status
 - `--show-token - Show the stored token (masked by default)`
 - `-f, --fresh - Bypass cache, re-detect projects, and fetch fresh data`
 
-**Examples:**
-
-```bash
-sentry auth status
-
-# Show the raw token
-sentry auth status --show-token
-
-# View current user
-sentry auth whoami
-```
-
 ### `sentry auth token`
 
 Print the stored authentication token
 
-**Examples:**
-
-```bash
-sentry auth token
-```
-
 ### `sentry auth whoami`
 
 Show the currently authenticated user

plugins/sentry-cli/skills/sentry-cli/references/cli.md

@@ -15,29 +15,13 @@ CLI-related commands
 
 Send feedback about the CLI
 
-**Examples:**
-
-```bash
-# Send positive feedback
-sentry cli feedback i love this tool
-
-# Report an issue
-sentry cli feedback the issue view is confusing
-```
-
 ### `sentry cli fix`
 
 Diagnose and repair CLI database issues
 
 **Flags:**
 - `--dry-run - Show what would be fixed without making changes`
 
-**Examples:**
-
-```bash
-sentry cli fix
-```
-
 ### `sentry cli setup`
 
 Configure shell integration
@@ -51,19 +35,6 @@ Configure shell integration
 - `--no-agent-skills - Skip agent skill installation for AI coding assistants`
 - `--quiet - Suppress output (for scripted usage)`
 
-**Examples:**
-
-```bash
-# Run full setup (PATH, completions, agent skills)
-sentry cli setup
-
-# Skip agent skill installation
-sentry cli setup --no-agent-skills
-
-# Skip PATH and completion modifications
-sentry cli setup --no-modify-path --no-completions
-```
-
 ### `sentry cli upgrade <version>`
 
 Update the Sentry CLI to the latest version
@@ -74,25 +45,4 @@ Update the Sentry CLI to the latest version
 - `--offline - Upgrade using only cached version info and patches (no network)`
 - `--method <value> - Installation method to use (curl, brew, npm, pnpm, bun, yarn)`
 
-**Examples:**
-
-```bash
-sentry cli upgrade --check
-
-# Upgrade to latest stable
-sentry cli upgrade
-
-# Upgrade to a specific version
-sentry cli upgrade 0.5.0
-
-# Force re-download
-sentry cli upgrade --force
-
-# Switch to nightly builds
-sentry cli upgrade nightly
-
-# Switch back to stable
-sentry cli upgrade stable
-```
-
 All commands also support `--json`, `--fields`, `--help`, `--log-level`, and `--verbose` flags.