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.

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

@@ -42,7 +42,7 @@ View a dashboard
 - `-w, --web - Open in browser`
 - `-f, --fresh - Bypass cache, re-detect projects, and fetch fresh data`
 - `-r, --refresh <value> - Auto-refresh interval in seconds (default: 60, min: 10)`
-- `-t, --period <value> - Time range: "7d", "2026-03-08..2026-04-08", ">=2026-03-08"`
+- `-t, --period <value> - Time range: "7d", "2026-03-09..2026-04-09", ">=2026-03-09"`
 
 **Examples:**
 

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

@@ -28,7 +28,7 @@ List events for an issue
 - `-n, --limit <value> - Number of events (1-1000) - (default: "25")`
 - `-q, --query <value> - Search query (Sentry search syntax)`
 - `--full - Include full event body (stacktraces)`
-- `-t, --period <value> - Time range: "7d", "2026-03-08..2026-04-08", ">=2026-03-08" - (default: "7d")`
+- `-t, --period <value> - Time range: "7d", "2026-03-09..2026-04-09", ">=2026-03-09" - (default: "7d")`
 - `-f, --fresh - Bypass cache, re-detect projects, and fetch fresh data`
 - `-c, --cursor <value> - Navigate pages: "next", "prev", "first" (or raw cursor string)`
 

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

@@ -19,7 +19,7 @@ List issues in a project
 - `-q, --query <value> - Search query (Sentry search syntax)`
 - `-n, --limit <value> - Maximum number of issues to list - (default: "25")`
 - `-s, --sort <value> - Sort by: date, new, freq, user - (default: "date")`
-- `-t, --period <value> - Time range: "7d", "2026-03-08..2026-04-08", ">=2026-03-08" - (default: "90d")`
+- `-t, --period <value> - Time range: "7d", "2026-03-09..2026-04-09", ">=2026-03-09" - (default: "90d")`
 - `-c, --cursor <value> - Pagination cursor (use "next" for next page, "prev" for previous)`
 - `--compact - Single-line rows for compact output (auto-detects if omitted)`
 - `-f, --fresh - Bypass cache, re-detect projects, and fetch fresh data`
@@ -78,7 +78,7 @@ List events for a specific issue
 - `-n, --limit <value> - Number of events (1-1000) - (default: "25")`
 - `-q, --query <value> - Search query (Sentry search syntax)`
 - `--full - Include full event body (stacktraces)`
-- `-t, --period <value> - Time range: "7d", "2026-03-08..2026-04-08", ">=2026-03-08" - (default: "7d")`
+- `-t, --period <value> - Time range: "7d", "2026-03-09..2026-04-09", ">=2026-03-09" - (default: "7d")`
 - `-f, --fresh - Bypass cache, re-detect projects, and fetch fresh data`
 - `-c, --cursor <value> - Navigate pages: "next", "prev", "first" (or raw cursor string)`
 

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

@@ -19,7 +19,7 @@ List logs from a project
 - `-n, --limit <value> - Number of log entries (1-1000) - (default: "100")`
 - `-q, --query <value> - Filter query (Sentry search syntax)`
 - `-f, --follow <value> - Stream logs (optionally specify poll interval in seconds)`
-- `-t, --period <value> - Time range: "7d", "2026-03-08..2026-04-08", ">=2026-03-08"`
+- `-t, --period <value> - Time range: "7d", "2026-03-09..2026-04-09", ">=2026-03-09"`
 - `-s, --sort <value> - Sort order: "newest" (default) or "oldest" - (default: "newest")`
 - `--fresh - Bypass cache, re-detect projects, and fetch fresh data`
 

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

@@ -19,7 +19,7 @@ List spans in a project or trace
 - `-n, --limit <value> - Number of spans (<=1000) - (default: "25")`
 - `-q, --query <value> - Filter spans (e.g., "op:db", "duration:>100ms", "project:backend")`
 - `-s, --sort <value> - Sort order: date, duration - (default: "date")`
-- `-t, --period <value> - Time range: "7d", "2026-03-08..2026-04-08", ">=2026-03-08" - (default: "7d")`
+- `-t, --period <value> - Time range: "7d", "2026-03-09..2026-04-09", ">=2026-03-09" - (default: "7d")`
 - `-f, --fresh - Bypass cache, re-detect projects, and fetch fresh data`
 - `-c, --cursor <value> - Navigate pages: "next", "prev", "first" (or raw cursor string)`
 

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

@@ -19,7 +19,7 @@ List recent traces in a project
 - `-n, --limit <value> - Number of traces (1-1000) - (default: "25")`
 - `-q, --query <value> - Search query (Sentry search syntax)`
 - `-s, --sort <value> - Sort by: date, duration - (default: "date")`
-- `-t, --period <value> - Time range: "7d", "2026-03-08..2026-04-08", ">=2026-03-08" - (default: "7d")`
+- `-t, --period <value> - Time range: "7d", "2026-03-09..2026-04-09", ">=2026-03-09" - (default: "7d")`
 - `-f, --fresh - Bypass cache, re-detect projects, and fetch fresh data`
 - `-c, --cursor <value> - Navigate pages: "next", "prev", "first" (or raw cursor string)`
 
@@ -78,7 +78,7 @@ View logs associated with a trace
 
 **Flags:**
 - `-w, --web - Open trace in browser`
-- `-t, --period <value> - Time range: "7d", "2026-03-08..2026-04-08", ">=2026-03-08" - (default: "14d")`
+- `-t, --period <value> - Time range: "7d", "2026-03-09..2026-04-09", ">=2026-03-09" - (default: "14d")`
 - `-n, --limit <value> - Number of log entries (<=1000) - (default: "100")`
 - `-q, --query <value> - Additional filter query (Sentry search syntax)`
 - `-s, --sort <value> - Sort order: "newest" (default) or "oldest" - (default: "newest")`