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

.github/workflows/ci.yml

@@ -42,8 +42,8 @@ jobs:
             skill:
               - 'src/**'
               - 'docs/**'
-              - 'plugins/**'
               - 'script/generate-skill.ts'
+              - 'script/generate-command-docs.ts'
               - 'script/eval-skill.ts'
               - 'test/skill-eval/**'
             code:
@@ -88,8 +88,8 @@ jobs:
           echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
           echo "Nightly version: ${VERSION}"
 
-  check-skill:
-    name: Check skill files
+  check-generated:
+    name: Validate generated files
     needs: [changes]
     if: needs.changes.outputs.skill == 'true'
     runs-on: ubuntu-latest
@@ -116,25 +116,30 @@ jobs:
         run: bun install --frozen-lockfile
       - name: Generate API Schema
         run: bun run generate:schema
+      - name: Generate docs and skill files
+        run: bun run generate:docs
+      - name: Validate fragments
+        run: bun run check:fragments
       - name: Check skill files
         id: check-skill
-        run: bun run check:skill
-        continue-on-error: true
-      - name: Check command docs
-        id: check-docs
-        run: bun run check:command-docs
-        continue-on-error: true
-      - name: Auto-commit regenerated files
-        if: (steps.check-skill.outcome == 'failure' || steps.check-docs.outcome == 'failure') && steps.token.outcome == 'success'
+        run: |
+          if git diff --quiet plugins/sentry-cli/skills/sentry-cli/; then
+            echo "Skill files are up to date"
+          else
+            echo "stale=true" >> "$GITHUB_OUTPUT"
+            echo "Skill files are out of date"
+          fi
+      - name: Auto-commit regenerated skill files
+        if: steps.check-skill.outputs.stale == 'true' && steps.token.outcome == 'success'
         run: |
           git config user.name "github-actions[bot]"
           git config user.email "github-actions[bot]@users.noreply.github.com"
-          git add plugins/sentry-cli/skills/sentry-cli/ docs/public/.well-known/skills/index.json docs/src/content/docs/commands/
-          git diff --cached --quiet || (git commit -m "chore: regenerate skill files and command docs" && git push)
-      - name: Fail for fork PRs with stale generated files
-        if: (steps.check-skill.outcome == 'failure' || steps.check-docs.outcome == 'failure') && steps.token.outcome != 'success'
+          git add plugins/sentry-cli/skills/sentry-cli/
+          git diff --cached --quiet || (git commit -m "chore: regenerate skill files" && git push)
+      - name: Fail for fork PRs with stale skill files
+        if: steps.check-skill.outputs.stale == 'true' && steps.token.outcome != 'success'
         run: |
-          echo "::error::Generated files are out of date. Run 'bun run generate:skill' and 'bun run generate:command-docs' locally and commit the result."
+          echo "::error::Skill files are out of date. Run 'bun run generate:docs' locally and commit the result."
           exit 1
 
   eval-skill:
@@ -177,6 +182,9 @@ jobs:
           key: node-modules-${{ hashFiles('bun.lock', 'patches/**') }}
       - if: steps.detect-fork.outputs.is_fork != 'true' && steps.cache.outputs.cache-hit != 'true'
         run: bun install --frozen-lockfile
+      - name: Generate docs and skill files
+        if: steps.detect-fork.outputs.is_fork != 'true'
+        run: bun run generate:schema && bun run generate:docs
       - name: Eval SKILL.md
         if: steps.detect-fork.outputs.is_fork != 'true'
         run: bun run eval:skill
@@ -659,6 +667,15 @@ jobs:
     steps:
       - uses: actions/checkout@v6
       - uses: oven-sh/setup-bun@v2
+      - uses: actions/cache@v5
+        id: cache
+        with:
+          path: node_modules
+          key: node-modules-${{ hashFiles('bun.lock', 'patches/**') }}
+      - if: steps.cache.outputs.cache-hit != 'true'
+        run: bun install --frozen-lockfile
+      - name: Generate docs content
+        run: bun run generate:schema && bun run generate:docs
       - name: Build Docs
         working-directory: docs
         run: |
@@ -677,15 +694,15 @@ jobs:
   ci-status:
     name: CI Status
     if: always()
-    needs: [changes, check-skill, eval-skill, build-binary, build-npm, build-docs, test-e2e, generate-patches, publish-nightly]
+    needs: [changes, check-generated, eval-skill, build-binary, build-npm, build-docs, test-e2e, generate-patches, publish-nightly]
     runs-on: ubuntu-latest
     permissions: {}
     steps:
       - name: Check CI status
         run: |
           # Check for explicit failures or cancellations in all jobs
           # generate-patches and publish-nightly are skipped on PRs — that's expected
-          results="${{ needs.check-skill.result }} ${{ needs.eval-skill.result }} ${{ needs.build-binary.result }} ${{ needs.build-npm.result }} ${{ needs.build-docs.result }} ${{ needs.test-e2e.result }} ${{ needs.generate-patches.result }} ${{ needs.publish-nightly.result }}"
+          results="${{ needs.check-generated.result }} ${{ needs.eval-skill.result }} ${{ needs.build-binary.result }} ${{ needs.build-npm.result }} ${{ needs.build-docs.result }} ${{ needs.test-e2e.result }} ${{ needs.generate-patches.result }} ${{ needs.publish-nightly.result }}"
           for result in $results; do
             if [[ "$result" == "failure" || "$result" == "cancelled" ]]; then
               echo "::error::CI failed"
@@ -699,8 +716,8 @@ jobs:
             echo "::error::CI failed - upstream job failed causing test-e2e to be skipped"
             exit 1
           fi
-          if [[ "${{ needs.changes.outputs.skill }}" == "true" && "${{ needs.check-skill.result }}" == "skipped" ]]; then
-            echo "::error::CI failed - upstream job failed causing check-skill to be skipped"
+          if [[ "${{ needs.changes.outputs.skill }}" == "true" && "${{ needs.check-generated.result }}" == "skipped" ]]; then
+            echo "::error::CI failed - upstream job failed causing check-generated to be skipped"
             exit 1
           fi
           if [[ "${{ needs.changes.outputs.skill }}" == "true" && "${{ needs.eval-skill.result }}" == "skipped" ]]; then

.github/workflows/docs-preview.yml

@@ -4,6 +4,9 @@ on:
   pull_request:
     paths:
       - 'docs/**'
+      - 'src/**'
+      - 'script/generate-command-docs.ts'
+      - 'script/generate-skill.ts'
       - '.github/workflows/docs-preview.yml'
 
 permissions:
@@ -18,6 +21,18 @@ jobs:
 
       - uses: oven-sh/setup-bun@v2
 
+      - uses: actions/cache@v5
+        id: cache
+        with:
+          path: node_modules
+          key: node-modules-${{ hashFiles('bun.lock', 'patches/**') }}
+
+      - if: steps.cache.outputs.cache-hit != 'true'
+        run: bun install --frozen-lockfile
+
+      - name: Generate docs content
+        run: bun run generate:schema && bun run generate:docs
+
       - name: Build Docs for Preview
         working-directory: docs
         env:

.github/workflows/generate-skill.yml

@@ -58,6 +58,12 @@ src/generated/
 src/sdk.generated.ts
 src/sdk.generated.d.cts
 
+# Generated command docs (rebuilt from fragments + CLI introspection)
+docs/src/content/docs/commands/
+
+# Generated discovery manifest (rebuilt by generate:skill, served via symlinked skill files)
+docs/public/.well-known/skills/index.json
+
 # OpenCode
 .opencode/
 opencode.json*

.gitignore

@@ -489,10 +489,14 @@ All normalize to lowercase. Throw `ValidationError` on invalid input.
 
 Use `"date"` for timestamp-based sort (not `"time"`). Export sort types from the API layer (e.g., `SpanSortValue` from `api/traces.ts`), import in commands. This matches `issue list`, `trace list`, and `span list`.
 
-### SKILL.md
+### Generated Docs & Skills
 
-- Run `bun run generate:skill` after changing any command parameters, flags, or docs.
-- CI check `bun run check:skill` will fail if SKILL.md is stale.
+All command docs and skill files are generated via `bun run generate:docs` (which runs `generate:command-docs` then `generate:skill`). This runs automatically as part of `dev`, `build`, `typecheck`, and `test` scripts.
+
+- **Command docs** (`docs/src/content/docs/commands/*.md`) are **gitignored** and generated from CLI metadata + hand-written fragments in `docs/src/fragments/commands/`.
+- **Skill files** (`plugins/sentry-cli/skills/sentry-cli/`) are **committed** (consumed by external plugin systems) and auto-committed by CI when stale.
+- Edit fragments in `docs/src/fragments/commands/` for custom examples and guides.
+- `bun run check:fragments` validates fragment ↔ route consistency.
 - Positional `placeholder` values must be descriptive: `"org/project/trace-id"` not `"args"`.
 
 ### Zod Schemas for Validation
@@ -973,6 +977,7 @@ mock.module("./some-module", () => ({
 | Add E2E tests | `test/e2e/` |
 | Test helpers | `test/model-based/helpers.ts` |
 | Add documentation | `docs/src/content/docs/` |
+| Hand-written command doc content | `docs/src/fragments/commands/` |
 
 <!-- This section is maintained by the coding agent via lore (https://github.com/BYK/opencode-lore) -->
 ## Long-term Knowledge
@@ -1016,7 +1021,7 @@ mock.module("./some-module", () => ({
 * **Sentry trace-logs API is org-scoped, not project-scoped**: The Sentry trace-logs endpoint (\`/organizations/{org}/trace-logs/\`) is org-scoped, so \`trace logs\` uses \`resolveOrg()\` not \`resolveOrgAndProject()\`. The endpoint is PRIVATE in Sentry source, excluded from the public OpenAPI schema — \`@sentry/api\` has no generated types. The hand-written \`TraceLogSchema\` in \`src/types/sentry.ts\` is required until Sentry makes it public.
 
 <!-- lore:019d3ea5-fd4a-75b0-8dab-0b1f1cb96b0e -->
-* **SKILL.md is fully generated — edit source files, not output**: The skill files under \`plugins/sentry-cli/skills/sentry-cli/\` (SKILL.md + references/\*.md) are fully generated by \`bun run generate:skill\` (script/generate-skill.ts). CI runs this after every push via a \`github-actions\[bot]\` commit, overwriting any manual edits. To change skill content, edit the \*\*sources\*\*: (1) \`docs/src/content/docs/agent-guidance.md\` — embedded into SKILL.md's Agent Guidance section with heading levels bumped. (2) \`src/commands/\*/\` flag \`brief\` strings — generate the reference file flag descriptions. (3) \`docs/src/content/docs/commands/\*.md\` — examples extracted per command via marked AST parsing. After editing sources, run \`bun run generate:skill\` locally and commit both source and generated files. CI's \`bun run check:skill\` fails if generated files are stale.
+* **SKILL.md is fully generated — edit fragment files for custom content, not output**: The skill files under \`plugins/sentry-cli/skills/sentry-cli/\` (SKILL.md + references/\*.md) are fully generated by \`bun run generate:skill\` (script/generate-skill.ts). They are rebuilt automatically by \`bun run generate:docs\` which runs as part of \`dev\`, \`build\`, \`typecheck\`, and \`test\` scripts. To change skill content, edit the \*\*sources\*\*: (1) \`docs/src/content/docs/agent-guidance.md\` — embedded into SKILL.md's Agent Guidance section with heading levels bumped. (2) \`src/commands/\*/\` flag \`brief\` strings — generate the reference file flag descriptions. (3) \`docs/src/fragments/commands/\*.md\` — hand-written examples and guides appended to generated command docs. Command docs (\`docs/src/content/docs/commands/\*.md\`) are also gitignored and rebuilt from fragments + CLI metadata by \`generate:command-docs\`. \`bun run check:fragments\` validates fragment ↔ route consistency.
 
 <!-- lore:019d275c-7cf0-7e13-bdc8-10cbbdbda933 -->
 * **Stricli route errors are uninterceptable — only post-run detection works**: Stricli route errors, exit codes, and OutputError — error propagation gaps: (1) Route failures are uninterceptable — Stricli writes to stderr and returns \`ExitCode.UnknownCommand\` internally. Only post-\`run()\` \`process.exitCode\` check works. \`exceptionWhileRunningCommand\` only fires for errors in command \`func()\`. (2) \`ExitCode.UnknownCommand\` is \`-5\`. Bun reads \`251\` (unsigned byte), Node reads \`-5\` — compare both. (3) \`OutputError\` in \`handleOutputError\` calls \`process.exit()\` immediately, bypassing telemetry and \`exceptionWhileRunningCommand\`. Top-level typos via \`defaultCommand:help\` → \`OutputError\` → \`process.exit(1)\` skip all error reporting.

AGENTS.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/agent-guidance.md

@@ -43,7 +43,7 @@ View a dashboard
 | `-w, --web` | Open in browser |
 | `-f, --fresh` | Bypass cache, re-detect projects, and fetch fresh data |
 | `-r, --refresh <refresh>` | Auto-refresh interval in seconds (default: 60, min: 10) |
-| `-t, --period <period>` | Time range: "7d", "2026-03-08..2026-04-08", ">=2026-03-08" |
+| `-t, --period <period>` | Time range: "7d", "2026-03-01..2026-04-01", ">=2026-03-01" |
 
 ### `sentry dashboard create <org/project/title...>`
 

docs/src/content/docs/commands/dashboard.md

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

docs/src/content/docs/commands/event.md

@@ -24,7 +24,7 @@ List issues in a project
 | `-q, --query <query>` | Search query (Sentry search syntax) |
 | `-n, --limit <limit>` | Maximum number of issues to list (default: "25") |
 | `-s, --sort <sort>` | Sort by: date, new, freq, user (default: "date") |
-| `-t, --period <period>` | Time range: "7d", "2026-03-08..2026-04-08", ">=2026-03-08" (default: "90d") |
+| `-t, --period <period>` | Time range: "7d", "2026-03-01..2026-04-01", ">=2026-03-01" (default: "90d") |
 | `-c, --cursor <cursor>` | 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 |
@@ -46,7 +46,7 @@ List events for a specific issue
 | `-n, --limit <limit>` | Number of events (1-1000) (default: "25") |
 | `-q, --query <query>` | Search query (Sentry search syntax) |
 | `--full` | Include full event body (stacktraces) |
-| `-t, --period <period>` | Time range: "7d", "2026-03-08..2026-04-08", ">=2026-03-08" (default: "7d") |
+| `-t, --period <period>` | Time range: "7d", "2026-03-01..2026-04-01", ">=2026-03-01" (default: "7d") |
 | `-f, --fresh` | Bypass cache, re-detect projects, and fetch fresh data |
 | `-c, --cursor <cursor>` | Navigate pages: "next", "prev", "first" (or raw cursor string) |
 

docs/src/content/docs/commands/issue.md

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