docs: fix documentation gaps and embed skill files at build time (#606)

cursor[bot] · BYK · web-flow · commit e97249fbb9de · 2026-03-30T19:21:22.000+01:00
## Summary Fix genuine documentation gaps not covered by the auto-generation infrastructure in #569, and eliminate the CLI → GitHub → CLI roundtrip for skill file installation. ## Documentation fixes - **Add `SENTRY_AUTH_TOKEN` and `SENTRY_TOKEN` to `configuration.md`** — primary CI/CD auth variables were missing from the env vars reference - **Add `SENTRY_INSTALL_DIR` and `SENTRY_NO_CACHE` to `configuration.md`** — undocumented env vars - **Add `project:admin` to OAuth scopes** in `DEVELOPMENT.md` and `self-hosted.md` — code requests 8 scopes but docs listed only 7; self-hosted users creating API tokens with the documented scopes would get permission errors - **Expand README commands table** from 6 to 14 entries - **Add missing examples** for `auth logout`, `auth refresh`, `auth token`, `project create`, `project delete`, `cli setup` - **Fix `config.db` → `cli.db`** in auth credential storage docs - **Fix `SENTRY_AUTH_TOKEN` priority label** — was incorrectly marked "legacy"; it is the primary env var - **Align curl install flags** (`-fsS`) between README and docs site ## Embed skill files at build time Previously, `sentry cli setup` fetched skill files from GitHub at runtime — fetching content that was generated from the CLI's own source code. This was a roundtrip: the CLI generates skill files from Stricli introspection, they live in the repo, and then the CLI fetches them back from GitHub by URL, using a hardcoded `REFERENCE_FILES` array that required codegen to keep in sync. Now: - `generate-skill.ts` produces `src/generated/skill-content.ts` that inlines all skill file contents (~47KB) as a `Map<string, string>` - `agent-skills.ts` imports the embedded content and writes it directly to `~/.claude/skills/` — no network fetch, no URL construction, no version-pinning logic - `REFERENCE_FILES` array, `getSkillUrl()`, `fetchSingleFile()`, `fetchAllSkillFiles()`, `fetchSkillContent()` — all removed - `generate:skill` is chained before `build`/`dev`/`typecheck`/`test` in `package.json` (like `generate:sdk`) - `check-skill.ts` verifies `skill-content.ts` stays in sync with generated markdown files Co-authored-by: Burak Yigit Kaya <byk@sentry.io>
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -126,8 +126,7 @@ jobs:
           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 commit -m "chore: regenerate skill files and command docs"
-          git push
+          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'
         run: |
diff --git a/AGENTS.md b/AGENTS.md
diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
@@ -59,7 +59,7 @@ When creating your Sentry OAuth application:
 
 - **Redirect URI**: Not required for device flow
 - **Scopes**: The CLI requests these scopes:
-  - `project:read`, `project:write`
+  - `project:read`, `project:write`, `project:admin`
   - `org:read`
   - `event:read`, `event:write`
   - `member:read`
diff --git a/README.md b/README.md
@@ -19,7 +19,7 @@
 ### Install Script (Recommended)
 
 ```bash
-curl -fsSL https://cli.sentry.dev/install | bash
+curl https://cli.sentry.dev/install -fsS | bash
 ```
 
 ### Homebrew
@@ -72,10 +72,18 @@ sentry issue plan PROJ-ABC
 |---------|-------------|
 | `sentry auth` | Login, logout, check authentication status |
 | `sentry org` | List and view organizations |
-| `sentry project` | List and view projects |
+| `sentry project` | List, view, create, and delete projects |
 | `sentry issue` | List, view, explain, and plan issues |
 | `sentry event` | View event details |
+| `sentry trace` | List and view distributed traces |
+| `sentry span` | List and view spans |
+| `sentry log` | List and view logs (with streaming) |
+| `sentry dashboard` | List, view, and create dashboards with widgets |
+| `sentry sourcemap` | Inject debug IDs and upload sourcemaps |
+| `sentry init` | Initialize Sentry in your project |
+| `sentry schema` | Browse the Sentry API schema |
 | `sentry api` | Make direct API requests |
+| `sentry cli` | Upgrade, setup, fix, and send feedback |
 
 For detailed documentation, visit [cli.sentry.dev](https://cli.sentry.dev).
 
diff --git a/docs/src/content/docs/commands/auth.md b/docs/src/content/docs/commands/auth.md
@@ -96,6 +96,24 @@ SENTRY_URL=https://sentry.example.com sentry auth login --token YOUR_TOKEN
 
 See [Self-Hosted Sentry](../self-hosted/) for details.
 
+### Logout
+
+```bash
+sentry auth logout
+```
+
+### Refresh token
+
+```bash
+sentry auth refresh
+```
+
+### Print stored token
+
+```bash
+sentry auth token
+```
+
 ### Check auth status
 
 ```bash
@@ -118,14 +136,14 @@ sentry auth whoami
 
 ## Credential Storage
 
-Auth tokens are stored in a SQLite database at `~/.sentry/config.db` with restricted file permissions.
+Auth tokens are stored in a SQLite database at `~/.sentry/cli.db` with restricted file permissions.
 
 ## Environment Variable Precedence
 
 The CLI checks for auth tokens in the following order, using the first one found:
 
-1. `SENTRY_AUTH_TOKEN` environment variable (legacy)
-2. `SENTRY_TOKEN` environment variable
-3. The stored token in the SQLite database
+1. `SENTRY_AUTH_TOKEN` environment variable
+2. `SENTRY_TOKEN` environment variable (legacy alias)
+3. The stored OAuth token in the SQLite database
 
 When a token comes from an environment variable, the CLI skips expiry checks and automatic refresh.
diff --git a/docs/src/content/docs/commands/cli.md b/docs/src/content/docs/commands/cli.md
@@ -144,3 +144,16 @@ Feedback is sent via Sentry's telemetry system. If telemetry is disabled (`SENTR
 ```bash
 sentry cli fix
 ```
+
+### Configure shell integration
+
+```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
+```
diff --git a/docs/src/content/docs/commands/project.md b/docs/src/content/docs/commands/project.md
@@ -117,3 +117,26 @@ DSN: https://abc123@sentry.io/123456
 # Open project in browser
 sentry project view my-org/frontend -w
 ```
+
+### Create a project
+
+```bash
+# Create a new project
+sentry project create my-new-app javascript-nextjs
+
+# Create under a specific org and team
+sentry project create my-org/my-new-app python --team backend-team
+
+# Preview without creating
+sentry project create my-new-app node --dry-run
+```
+
+### Delete a project
+
+```bash
+# Delete a project (will prompt for confirmation)
+sentry project delete my-org/old-project
+
+# Delete without confirmation
+sentry project delete my-org/old-project --yes
+```
diff --git a/docs/src/content/docs/configuration.md b/docs/src/content/docs/configuration.md
@@ -7,6 +7,20 @@ The Sentry CLI can be configured through environment variables and a local datab
 
 ## Environment Variables
 
+### `SENTRY_AUTH_TOKEN`
+
+Authentication token for the Sentry API. This is the primary way to authenticate in CI/CD pipelines and scripts where interactive login is not possible.
+
+```bash
+export SENTRY_AUTH_TOKEN=sntrys_YOUR_TOKEN_HERE
+```
+
+You can create auth tokens in your [Sentry account settings](https://sentry.io/settings/account/api/auth-tokens/). When set, this takes precedence over any stored OAuth token from `sentry auth login`.
+
+### `SENTRY_TOKEN`
+
+Legacy alias for `SENTRY_AUTH_TOKEN`. If both are set, `SENTRY_AUTH_TOKEN` takes precedence.
+
 ### `SENTRY_HOST`
 
 Base URL of your Sentry instance. **Only needed for [self-hosted Sentry](./self-hosted/).** SaaS users (sentry.io) should not set this.
@@ -125,6 +139,22 @@ Disable the automatic update check that runs periodically in the background.
 export SENTRY_CLI_NO_UPDATE_CHECK=1
 ```
 
+### `SENTRY_INSTALL_DIR`
+
+Override the directory where the CLI binary is installed. Used by the install script and `sentry cli upgrade` to control the binary location.
+
+```bash
+export SENTRY_INSTALL_DIR=/usr/local/bin
+```
+
+### `SENTRY_NO_CACHE`
+
+Disable API response caching. When set, the CLI will not cache API responses and will always make fresh requests.
+
+```bash
+export SENTRY_NO_CACHE=1
+```
+
 ## Global Options
 
 These flags are accepted by every command. They are not shown in individual command `--help` output, but are always available.
diff --git a/docs/src/content/docs/self-hosted.md b/docs/src/content/docs/self-hosted.md
@@ -44,7 +44,7 @@ export SENTRY_CLIENT_ID=your-client-id
 If your instance is on an older version or you prefer not to create an OAuth application, you can use an API token instead:
 
 1. Go to **Settings → Developer Settings → Personal Tokens** in your Sentry instance (or visit `https://sentry.example.com/settings/account/api/auth-tokens/new-token/`)
-2. Create a new token with the following scopes: `project:read`, `project:write`, `org:read`, `event:read`, `event:write`, `member:read`, `team:read`
+2. Create a new token with the following scopes: `project:read`, `project:write`, `project:admin`, `org:read`, `event:read`, `event:write`, `member:read`, `team:read`
 3. Pass it to the CLI:
 
 ```bash
diff --git a/package.json b/package.json
@@ -72,17 +72,17 @@
     "@sentry/node-core@10.44.0": "patches/@sentry%2Fnode-core@10.44.0.patch"
   },
   "scripts": {
-    "dev": "bun run generate:schema && bun run generate:sdk && bun run src/bin.ts",
-    "build": "bun run generate:schema && bun run generate:sdk && bun run script/build.ts --single",
-    "build:all": "bun run generate:schema && bun run generate:sdk && bun run script/build.ts",
-    "bundle": "bun run generate:schema && bun run generate:sdk && bun run script/bundle.ts",
-    "typecheck": "bun run generate:sdk && tsc --noEmit",
+    "dev": "bun run generate:schema && bun run generate:skill && bun run generate:sdk && bun run src/bin.ts",
+    "build": "bun run generate:schema && bun run generate:skill && bun run generate:sdk && bun run script/build.ts --single",
+    "build:all": "bun run generate:schema && bun run generate:skill && bun run generate:sdk && bun run script/build.ts",
+    "bundle": "bun run generate:schema && bun run generate:skill && bun run generate:sdk && bun run script/bundle.ts",
+    "typecheck": "bun run generate:skill && bun run generate:sdk && tsc --noEmit",
     "lint": "bunx ultracite check",
     "lint:fix": "bunx ultracite fix",
     "test": "bun run test:unit && bun run test:isolated",
-    "test:unit": "bun run generate:sdk && bun test --timeout 15000 test/lib test/commands test/types --coverage --coverage-reporter=lcov",
-    "test:isolated": "bun run generate:sdk && bun test --timeout 15000 test/isolated",
-    "test:e2e": "bun run generate:sdk && bun test --timeout 15000 test/e2e",
+    "test:unit": "bun run generate:skill && bun run generate:sdk && bun test --timeout 15000 test/lib test/commands test/types --coverage --coverage-reporter=lcov",
+    "test:isolated": "bun run generate:skill && bun run generate:sdk && bun test --timeout 15000 test/isolated",
+    "test:e2e": "bun run generate:skill && bun run generate:sdk && bun test --timeout 15000 test/e2e",
     "test:init-eval": "bun test test/init-eval --timeout 600000 --concurrency 6",
     "generate:sdk": "bun run script/generate-sdk.ts",
     "generate:skill": "bun run script/generate-skill.ts",
diff --git a/plugins/sentry-cli/skills/sentry-cli/references/auth.md b/plugins/sentry-cli/skills/sentry-cli/references/auth.md
@@ -36,13 +36,25 @@ SENTRY_URL=https://sentry.example.com sentry auth login --token YOUR_TOKEN
 
 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
@@ -67,6 +79,12 @@ sentry auth whoami
 
 Print the stored authentication token
 
+**Examples:**
+
+```bash
+sentry auth token
+```
+
 ### `sentry auth whoami`
 
 Show the currently authenticated user
diff --git a/plugins/sentry-cli/skills/sentry-cli/references/projects.md b/plugins/sentry-cli/skills/sentry-cli/references/projects.md
@@ -19,6 +19,19 @@ Create a new project
 - `-t, --team <value> - Team to create the project under`
 - `-n, --dry-run - Validate inputs and show what would be created without creating it`
 
+**Examples:**
+
+```bash
+# Create a new project
+sentry project create my-new-app javascript-nextjs
+
+# Create under a specific org and team
+sentry project create my-org/my-new-app python --team backend-team
+
+# Preview without creating
+sentry project create my-new-app node --dry-run
+```
+
 ### `sentry project delete <org/project>`
 
 Delete a project
@@ -28,6 +41,16 @@ Delete a project
 - `-f, --force - Force deletion without confirmation`
 - `-n, --dry-run - Validate and show what would be deleted without deleting`
 
+**Examples:**
+
+```bash
+# Delete a project (will prompt for confirmation)
+sentry project delete my-org/old-project
+
+# Delete without confirmation
+sentry project delete my-org/old-project --yes
+```
+
 ### `sentry project list <org/project>`
 
 List projects
diff --git a/plugins/sentry-cli/skills/sentry-cli/references/setup.md b/plugins/sentry-cli/skills/sentry-cli/references/setup.md
@@ -55,6 +55,19 @@ 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
diff --git a/script/check-skill.ts b/script/check-skill.ts
@@ -21,6 +21,11 @@ const INDEX_JSON_PATH = "docs/public/.well-known/skills/index.json";
 /**
  * Read all .md files under the skill directory + the index.json.
  * Returns a map of relative path → content.
+ *
+ * Note: src/generated/skill-content.ts is NOT checked here because it is
+ * gitignored (regenerated at build time). The markdown files and index.json
+ * are the committed artifacts; if they are in sync, skill-content.ts will
+ * also be correct since the generator produces both in the same run.
  */
 async function readAllSkillFiles(): Promise<Map<string, string>> {
   const files = new Map<string, string>();
diff --git a/script/generate-skill.ts b/script/generate-skill.ts
@@ -19,10 +19,28 @@
  *   docs/public/.well-known/skills/index.json
  */
 
-import { rmSync } from "node:fs";
+import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
 import type { Token } from "marked";
 import { marked } from "marked";
-import { routes } from "../src/app.js";
+
+// Bootstrap: ensure the generated skill-content module exists before
+// importing the route tree (app.ts → agent-skills.ts → skill-content.ts).
+// On a fresh checkout the file won't exist, causing a module resolution
+// error. Write a minimal stub so the import resolves; the real content
+// is generated at the end of this script.
+// NOTE: This must run before the dynamic import() below because static
+// imports are hoisted by the runtime before any code executes.
+const SKILL_CONTENT_STUB = "src/generated/skill-content.ts";
+if (!existsSync(SKILL_CONTENT_STUB)) {
+  mkdirSync("src/generated", { recursive: true });
+  writeFileSync(
+    SKILL_CONTENT_STUB,
+    "export const SKILL_FILES: ReadonlyMap<string, string> = new Map();\n"
+  );
+}
+
+const { routes } = await import("../src/app.js");
+
 import type {
   CommandInfo,
   FlagInfo,
@@ -911,10 +929,38 @@ for (const [relativePath, content] of files) {
 const indexJson = generateIndexJson(files);
 await Bun.write(INDEX_JSON_PATH, indexJson);
 
+// Generate src/generated/skill-content.ts with inlined file contents.
+// This embeds all skill files into the binary at build time so that
+// agent-skills.ts can install them without any network fetching.
+const SKILL_CONTENT_PATH = "src/generated/skill-content.ts";
+const skillEntries = [...files.entries()]
+  .sort(([a], [b]) => a.localeCompare(b))
+  .map(([path, content]) => {
+    const escaped = content
+      .replaceAll("\\", "\\\\")
+      .replaceAll("`", "\\`")
+      .replaceAll("${", "\\${");
+    return `  ["${path}", \`${escaped}\`],`;
+  })
+  .join("\n");
+
+const skillContentModule = `/**
+ * Embedded skill file contents for agent skill installation.
+ * Auto-generated by script/generate-skill.ts — do not edit manually.
+ */
+
+/** Map of relative path → file content for all skill files */
+export const SKILL_FILES: ReadonlyMap<string, string> = new Map([
+${skillEntries}
+]);
+`;
+
+await Bun.write(SKILL_CONTENT_PATH, skillContentModule);
+
 // Report what was generated
 const refCount = [...files.keys()].filter((k) =>
   k.startsWith("references/")
 ).length;
 console.log(
-  `Generated ${OUTPUT_PATH} + ${refCount} reference files + ${INDEX_JSON_PATH}`
+  `Generated ${OUTPUT_PATH} + ${refCount} reference files + ${INDEX_JSON_PATH} + ${SKILL_CONTENT_PATH}`
 );
diff --git a/src/commands/cli/setup.ts b/src/commands/cli/setup.ts
diff --git a/src/lib/agent-skills.ts b/src/lib/agent-skills.ts
diff --git a/test/commands/cli/setup.test.ts b/test/commands/cli/setup.test.ts
diff --git a/test/lib/agent-skills.test.ts b/test/lib/agent-skills.test.ts
