getsentry · BYK · Mar 27, 2026 · Mar 26, 2026 · Mar 27, 2026 · Mar 27, 2026
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -113,21 +113,25 @@ jobs:
       - name: Generate API Schema
         run: bun run generate:schema
       - name: Check skill files
-        id: check
+        id: check-skill
         run: bun run check:skill
         continue-on-error: true
-      - name: Auto-commit regenerated skill files
-        if: steps.check.outcome == 'failure' && steps.token.outcome == 'success'
+      - 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: |
           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
-          git commit -m "chore: regenerate skill files"
+          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
-      - name: Fail for fork PRs with stale skill files
-        if: steps.check.outcome == 'failure' && steps.token.outcome != 'success'
+      - 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: |
-          echo "::error::Skill files are out of date. Run 'bun run generate:skill' locally and commit the result."
+          echo "::error::Generated files are out of date. Run 'bun run generate:skill' and 'bun run generate:command-docs' locally and commit the result."
           exit 1
 
   lint:

diff --git a/AGENTS.md b/AGENTS.md
diff --git a/docs/src/content/docs/commands/api.md b/docs/src/content/docs/commands/api.md
@@ -1,114 +1,98 @@
 ---
 title: api
-description: Direct API access for the Sentry CLI
+description: API command for the Sentry CLI
 ---
 
-Make direct API calls to Sentry's REST API.
+Make an authenticated API request
 
-## Commands
+## Usage
 
-### `sentry api`
+### `sentry api <endpoint>`
 
-Execute an API request.
-
-```bash
-sentry api <endpoint> [options]
-```
+Make an authenticated API request
 
 **Arguments:**
 
 | Argument | Description |
 |----------|-------------|
-| `<endpoint>` | API endpoint path (e.g., `/organizations/`) |
+| `<endpoint>` | API endpoint relative to /api/0/ (e.g., organizations/) |
 
 **Options:**
 
 | Option | Description |
 |--------|-------------|
-| `--method <method>` | HTTP method (GET, POST, PUT, DELETE). Default: GET |
-| `--field <key=value>` | Add a field to the request body (can be used multiple times) |
-| `--header <key:value>` | Add a custom header (can be used multiple times) |
-| `--include` | Include response headers in output |
-| `--paginate` | Automatically paginate through all results |
+| `-X, --method <method>` | The HTTP method for the request (default: "GET") |
+| `-d, --data <data>` | Inline JSON body for the request (like curl -d) |
+| `-F, --field <field>...` | Add a typed parameter (key=value, key[sub]=value, key[]=value) |
+| `-f, --raw-field <raw-field>...` | Add a string parameter without JSON parsing |
+| `-H, --header <header>...` | Add a HTTP request header in key:value format |
+| `--input <input>` | The file to use as body for the HTTP request (use "-" to read from standard input) |
+| `--silent` | Do not print the response body |
+| `--verbose` | Include full HTTP request and response in the output |
+| `-n, --dry-run` | Show the resolved request without sending it |
+
+All commands support `--json` for machine-readable output and `--fields` to select specific JSON fields.
+
+<!-- GENERATED:END -->
 
 ## Examples
 
-### GET Request
+Endpoints are relative to `/api/0/` — the prefix is added automatically.
+
+### GET requests
 
 ```bash
 # List organizations
-sentry api /organizations/
-
-# Get a specific organization
-sentry api /organizations/my-org/
+sentry api organizations/
 
-# Get project details
-sentry api /projects/my-org/my-project/
+# Get a specific issue
+sentry api issues/123456789/
 ```
 
-### POST Request
+### POST requests
 
 ```bash
-# Create a new project
-sentry api /teams/my-org/my-team/projects/ \
-  --method POST \
-  --field name="New Project" \
-  --field platform=javascript
+# 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"}'
 ```
 
-### PUT Request
+### PUT requests
 
 ```bash
 # Update an issue status
-sentry api /issues/123456789/ \
-  --method PUT \
-  --field status=resolved
+sentry api issues/123456789/ \
+  -X PUT -F status=resolved
 
 # Assign an issue
-sentry api /issues/123456789/ \
-  --method PUT \
-  --field assignedTo="user@example.com"
-```
-
-### DELETE Request
-
-```bash
-# Delete a project
-sentry api /projects/my-org/my-project/ \
-  --method DELETE
+sentry api issues/123456789/ \
+  -X PUT --field assignedTo="user@example.com"
 ```
 
-### With Headers
+### DELETE requests
 
 ```bash
-sentry api /organizations/ \
-  --header "X-Custom-Header:value"
+sentry api projects/my-org/my-project/ -X DELETE
 ```
 
-### Verbose Mode
+### Advanced usage
 
 ```bash
-sentry api /organizations/ --verbose
-```
+# Add custom headers
+sentry api organizations/ -H "X-Custom: value"
 
-Request and response metadata is logged to stderr:
+# Read body from a file
+sentry api projects/my-org/my-project/releases/ -X POST --input release.json
 
-```
-> GET /api/0/organizations/
->
-< HTTP 200
-< content-type: application/json
-<
-[{"slug": "my-org", ...}]
-```
-
-### Pagination
+# Verbose mode (shows full HTTP request/response)
+sentry api organizations/ --verbose
 
-```bash
-# Get all issues (automatically follows pagination)
-sentry api /projects/my-org/my-project/issues/ --paginate
+# Preview the request without sending
+sentry api organizations/ --dry-run
 ```
 
-## API Documentation
-
 For full API documentation, see the [Sentry API Reference](https://docs.sentry.io/api/).
diff --git a/docs/src/content/docs/commands/auth.md b/docs/src/content/docs/commands/auth.md
@@ -1,96 +1,126 @@
 ---
 title: auth
-description: Authentication commands for the Sentry CLI
+description: Auth commands for the Sentry CLI
 ---
 
-Manage authentication for the Sentry CLI.
+Authenticate with Sentry
 
 ## Commands
 
 ### `sentry auth login`
 
-Authenticate with Sentry.
+Authenticate with Sentry
 
-```bash
-# OAuth device flow (recommended)
-sentry auth login
+**Options:**
 
-# Using an API token
-sentry auth login --token YOUR_TOKEN
-```
+| Option | Description |
+|--------|-------------|
+| `--token <token>` | Authenticate using an API token instead of OAuth |
+| `--timeout <timeout>` | Timeout for OAuth flow in seconds (default: 900) |
+| `--force` | Re-authenticate without prompting |
+
+### `sentry auth logout`
+
+Log out of Sentry
+
+### `sentry auth refresh`
+
+Refresh your authentication token
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `--force` | Force refresh even if token is still valid |
+
+### `sentry auth status`
+
+View authentication status
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `--show-token` | Show the stored token (masked by default) |
+| `-f, --fresh` | Bypass cache, re-detect projects, and fetch fresh data |
+
+### `sentry auth token`
+
+Print the stored authentication token
+
+### `sentry auth whoami`
+
+Show the currently authenticated user
 
 **Options:**
 
 | Option | Description |
 |--------|-------------|
-| `--token <token>` | Use an API token instead of OAuth |
+| `-f, --fresh` | Bypass cache, re-detect projects, and fetch fresh data |
 
-**OAuth Flow:**
+All commands support `--json` for machine-readable output and `--fields` to select specific JSON fields.
 
-1. Run `sentry auth login`
-2. A URL and code will be displayed
-3. Open the URL in your browser
-4. Enter the code when prompted
-5. Authorize the application
-6. The CLI automatically receives your token
+<!-- GENERATED:END -->
 
-**Self-Hosted Sentry (26.1.0+):**
+## Examples
 
-For self-hosted instances, set `SENTRY_URL` and `SENTRY_CLIENT_ID` (from a public OAuth application you create on your instance):
+### OAuth login (recommended)
 
 ```bash
-SENTRY_URL=https://sentry.example.com SENTRY_CLIENT_ID=your-client-id sentry auth login
+sentry auth login
 ```
 
-On older versions or without an OAuth application, use an API token instead:
+1. A URL and device code will be displayed
+2. Open the URL in your browser
+3. Enter the code when prompted
+4. Authorize the application
+5. The CLI automatically receives your token
+
+### Token login
 
 ```bash
-SENTRY_URL=https://sentry.example.com sentry auth login --token YOUR_TOKEN
+sentry auth login --token YOUR_SENTRY_API_TOKEN
 ```
 
-See [Self-Hosted Sentry](../self-hosted/) for full setup details.
+### Self-hosted Sentry
 
-### `sentry auth logout`
+```bash
+SENTRY_URL=https://sentry.example.com sentry auth login
+```
 
-Remove stored credentials.
+For token-based auth with self-hosted:
 
 ```bash
-sentry auth logout
+SENTRY_URL=https://sentry.example.com sentry auth login --token YOUR_TOKEN
 ```
 
-### `sentry auth status`
+See [Self-Hosted Sentry](../self-hosted/) for details.
 
-Check your authentication status.
+### Check auth status
 
 ```bash
 sentry auth status
 ```
 
-**Output:**
-
 ```
 Authenticated as: username
 Organization: my-org
 Token expires: 2024-12-31
 ```
 
-### `sentry auth refresh`
-
-Refresh your OAuth token.
-
 ```bash
-sentry auth refresh
-```
+# Show the raw token
+sentry auth status --show-token
 
-This is typically handled automatically when tokens expire.
+# View current user
+sentry auth whoami
+```
 
 ## Credential Storage
 
-Credentials are stored in a SQLite database at `~/.sentry/cli.db` with restricted file permissions (mode 600).
-
-Use `sentry auth token` to retrieve your current access token, or `sentry auth status` to check authentication state.
+Auth tokens are stored in a SQLite database at `~/.sentry/config.db` with restricted file permissions.
 
-### Environment Variable Precedence
+## Environment Variable Precedence
 
 The CLI checks for auth tokens in the following order, using the first one found: