Skip to content

Commit d88e735

Browse files
sergicalsergical
authored
docs: auto-generate command reference pages with CI enforcement (#569)
Replace hand-written command doc pages with auto-generated reference sections extracted from Stricli route tree introspection. Fixes pervasive documentation drift and adds CI enforcement. ## What changed - **New generator**: `script/generate-command-docs.ts` produces reference sections (args, options tables) for all 17 command pages from the live route tree - **CI check**: `script/check-command-docs.ts` validates freshness, auto-commits on PRs - **Skill examples**: Replaced fragile regex parsing in `generate-skill.ts` with `marked.lexer()` AST walking for robust example extraction - **Examples check**: `check-skill.ts` now verifies every reference file has examples - **Descriptive placeholders**: Fixed 7 commands using generic `args` placeholder, banned it in AGENTS.md - **Content preserved**: Hand-written examples, sample output, and guides live below `<!-- GENERATED:END -->` markers ## Fixes - Removes phantom flags (`--include`, `--paginate`, `--channel`, `--force` for init) - Adds missing flags (`--fresh`, `--fields`, `--cursor`, `--period`, `--spans`) to all pages - Adds 6 new doc pages: trace, span, sourcemap, repo, trial, schema - Adds dashboard view/create to shell completion set - Fixes api.md examples to use relative endpoints (no `/api/0/` prefix) - Fixes init.md feature name (`replays` → `replay`) - Fixes log.md jq example (`.data[]` envelope, `.severity` field) - Fixes event.md to use 32-char hex event IDs
1 parent f5e9480 commit d88e735

51 files changed

Lines changed: 2211 additions & 1221 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/ci.yml‎

Lines changed: 12 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -113,21 +113,25 @@ jobs:
113113
- name: Generate API Schema
114114
run: bun run generate:schema
115115
- name: Check skill files
116-
id: check
116+
id: check-skill
117117
run: bun run check:skill
118118
continue-on-error: true
119-
- name: Auto-commit regenerated skill files
120-
if: steps.check.outcome == 'failure' && steps.token.outcome == 'success'
119+
- name: Check command docs
120+
id: check-docs
121+
run: bun run check:command-docs
122+
continue-on-error: true
123+
- name: Auto-commit regenerated files
124+
if: (steps.check-skill.outcome == 'failure' || steps.check-docs.outcome == 'failure') && steps.token.outcome == 'success'
121125
run: |
122126
git config user.name "github-actions[bot]"
123127
git config user.email "github-actions[bot]@users.noreply.github.com"
124-
git add plugins/sentry-cli/skills/sentry-cli/ docs/public/.well-known/skills/index.json
125-
git commit -m "chore: regenerate skill files"
128+
git add plugins/sentry-cli/skills/sentry-cli/ docs/public/.well-known/skills/index.json docs/src/content/docs/commands/
129+
git commit -m "chore: regenerate skill files and command docs"
126130
git push
127-
- name: Fail for fork PRs with stale skill files
128-
if: steps.check.outcome == 'failure' && steps.token.outcome != 'success'
131+
- name: Fail for fork PRs with stale generated files
132+
if: (steps.check-skill.outcome == 'failure' || steps.check-docs.outcome == 'failure') && steps.token.outcome != 'success'
129133
run: |
130-
echo "::error::Skill files are out of date. Run 'bun run generate:skill' locally and commit the result."
134+
echo "::error::Generated files are out of date. Run 'bun run generate:skill' and 'bun run generate:command-docs' locally and commit the result."
131135
exit 1
132136
133137
lint:

‎AGENTS.md‎

Lines changed: 57 additions & 56 deletions
Large diffs are not rendered by default.

‎docs/src/content/docs/commands/api.md‎

Lines changed: 49 additions & 65 deletions
Original file line numberDiff line numberDiff line change
@@ -1,114 +1,98 @@
11
---
22
title: api
3-
description: Direct API access for the Sentry CLI
3+
description: API command for the Sentry CLI
44
---
55

6-
Make direct API calls to Sentry's REST API.
6+
Make an authenticated API request
77

8-
## Commands
8+
## Usage
99

10-
### `sentry api`
10+
### `sentry api <endpoint>`
1111

12-
Execute an API request.
13-
14-
```bash
15-
sentry api <endpoint> [options]
16-
```
12+
Make an authenticated API request
1713

1814
**Arguments:**
1915

2016
| Argument | Description |
2117
|----------|-------------|
22-
| `<endpoint>` | API endpoint path (e.g., `/organizations/`) |
18+
| `<endpoint>` | API endpoint relative to /api/0/ (e.g., organizations/) |
2319

2420
**Options:**
2521

2622
| Option | Description |
2723
|--------|-------------|
28-
| `--method <method>` | HTTP method (GET, POST, PUT, DELETE). Default: GET |
29-
| `--field <key=value>` | Add a field to the request body (can be used multiple times) |
30-
| `--header <key:value>` | Add a custom header (can be used multiple times) |
31-
| `--include` | Include response headers in output |
32-
| `--paginate` | Automatically paginate through all results |
24+
| `-X, --method <method>` | The HTTP method for the request (default: "GET") |
25+
| `-d, --data <data>` | Inline JSON body for the request (like curl -d) |
26+
| `-F, --field <field>...` | Add a typed parameter (key=value, key[sub]=value, key[]=value) |
27+
| `-f, --raw-field <raw-field>...` | Add a string parameter without JSON parsing |
28+
| `-H, --header <header>...` | Add a HTTP request header in key:value format |
29+
| `--input <input>` | The file to use as body for the HTTP request (use "-" to read from standard input) |
30+
| `--silent` | Do not print the response body |
31+
| `--verbose` | Include full HTTP request and response in the output |
32+
| `-n, --dry-run` | Show the resolved request without sending it |
33+
34+
All commands support `--json` for machine-readable output and `--fields` to select specific JSON fields.
35+
36+
<!-- GENERATED:END -->
3337

3438
## Examples
3539

36-
### GET Request
40+
Endpoints are relative to `/api/0/` — the prefix is added automatically.
41+
42+
### GET requests
3743

3844
```bash
3945
# List organizations
40-
sentry api /organizations/
41-
42-
# Get a specific organization
43-
sentry api /organizations/my-org/
46+
sentry api organizations/
4447

45-
# Get project details
46-
sentry api /projects/my-org/my-project/
48+
# Get a specific issue
49+
sentry api issues/123456789/
4750
```
4851

49-
### POST Request
52+
### POST requests
5053

5154
```bash
52-
# Create a new project
53-
sentry api /teams/my-org/my-team/projects/ \
54-
--method POST \
55-
--field name="New Project" \
56-
--field platform=javascript
55+
# Create a release
56+
sentry api organizations/my-org/releases/ \
57+
-X POST -F version=1.0.0
58+
59+
# With inline JSON body
60+
sentry api issues/123456789/ \
61+
-X POST -d '{"status": "resolved"}'
5762
```
5863

59-
### PUT Request
64+
### PUT requests
6065

6166
```bash
6267
# Update an issue status
63-
sentry api /issues/123456789/ \
64-
--method PUT \
65-
--field status=resolved
68+
sentry api issues/123456789/ \
69+
-X PUT -F status=resolved
6670

6771
# Assign an issue
68-
sentry api /issues/123456789/ \
69-
--method PUT \
70-
--field assignedTo="user@example.com"
71-
```
72-
73-
### DELETE Request
74-
75-
```bash
76-
# Delete a project
77-
sentry api /projects/my-org/my-project/ \
78-
--method DELETE
72+
sentry api issues/123456789/ \
73+
-X PUT --field assignedTo="user@example.com"
7974
```
8075

81-
### With Headers
76+
### DELETE requests
8277

8378
```bash
84-
sentry api /organizations/ \
85-
--header "X-Custom-Header:value"
79+
sentry api projects/my-org/my-project/ -X DELETE
8680
```
8781

88-
### Verbose Mode
82+
### Advanced usage
8983

9084
```bash
91-
sentry api /organizations/ --verbose
92-
```
85+
# Add custom headers
86+
sentry api organizations/ -H "X-Custom: value"
9387

94-
Request and response metadata is logged to stderr:
88+
# Read body from a file
89+
sentry api projects/my-org/my-project/releases/ -X POST --input release.json
9590

96-
```
97-
> GET /api/0/organizations/
98-
>
99-
< HTTP 200
100-
< content-type: application/json
101-
<
102-
[{"slug": "my-org", ...}]
103-
```
104-
105-
### Pagination
91+
# Verbose mode (shows full HTTP request/response)
92+
sentry api organizations/ --verbose
10693

107-
```bash
108-
# Get all issues (automatically follows pagination)
109-
sentry api /projects/my-org/my-project/issues/ --paginate
94+
# Preview the request without sending
95+
sentry api organizations/ --dry-run
11096
```
11197

112-
## API Documentation
113-
11498
For full API documentation, see the [Sentry API Reference](https://docs.sentry.io/api/).

‎docs/src/content/docs/commands/auth.md‎

Lines changed: 71 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -1,96 +1,126 @@
11
---
22
title: auth
3-
description: Authentication commands for the Sentry CLI
3+
description: Auth commands for the Sentry CLI
44
---
55

6-
Manage authentication for the Sentry CLI.
6+
Authenticate with Sentry
77

88
## Commands
99

1010
### `sentry auth login`
1111

12-
Authenticate with Sentry.
12+
Authenticate with Sentry
1313

14-
```bash
15-
# OAuth device flow (recommended)
16-
sentry auth login
14+
**Options:**
1715

18-
# Using an API token
19-
sentry auth login --token YOUR_TOKEN
20-
```
16+
| Option | Description |
17+
|--------|-------------|
18+
| `--token <token>` | Authenticate using an API token instead of OAuth |
19+
| `--timeout <timeout>` | Timeout for OAuth flow in seconds (default: 900) |
20+
| `--force` | Re-authenticate without prompting |
21+
22+
### `sentry auth logout`
23+
24+
Log out of Sentry
25+
26+
### `sentry auth refresh`
27+
28+
Refresh your authentication token
29+
30+
**Options:**
31+
32+
| Option | Description |
33+
|--------|-------------|
34+
| `--force` | Force refresh even if token is still valid |
35+
36+
### `sentry auth status`
37+
38+
View authentication status
39+
40+
**Options:**
41+
42+
| Option | Description |
43+
|--------|-------------|
44+
| `--show-token` | Show the stored token (masked by default) |
45+
| `-f, --fresh` | Bypass cache, re-detect projects, and fetch fresh data |
46+
47+
### `sentry auth token`
48+
49+
Print the stored authentication token
50+
51+
### `sentry auth whoami`
52+
53+
Show the currently authenticated user
2154

2255
**Options:**
2356

2457
| Option | Description |
2558
|--------|-------------|
26-
| `--token <token>` | Use an API token instead of OAuth |
59+
| `-f, --fresh` | Bypass cache, re-detect projects, and fetch fresh data |
2760

28-
**OAuth Flow:**
61+
All commands support `--json` for machine-readable output and `--fields` to select specific JSON fields.
2962

30-
1. Run `sentry auth login`
31-
2. A URL and code will be displayed
32-
3. Open the URL in your browser
33-
4. Enter the code when prompted
34-
5. Authorize the application
35-
6. The CLI automatically receives your token
63+
<!-- GENERATED:END -->
3664

37-
**Self-Hosted Sentry (26.1.0+):**
65+
## Examples
3866

39-
For self-hosted instances, set `SENTRY_URL` and `SENTRY_CLIENT_ID` (from a public OAuth application you create on your instance):
67+
### OAuth login (recommended)
4068

4169
```bash
42-
SENTRY_URL=https://sentry.example.com SENTRY_CLIENT_ID=your-client-id sentry auth login
70+
sentry auth login
4371
```
4472

45-
On older versions or without an OAuth application, use an API token instead:
73+
1. A URL and device code will be displayed
74+
2. Open the URL in your browser
75+
3. Enter the code when prompted
76+
4. Authorize the application
77+
5. The CLI automatically receives your token
78+
79+
### Token login
4680

4781
```bash
48-
SENTRY_URL=https://sentry.example.com sentry auth login --token YOUR_TOKEN
82+
sentry auth login --token YOUR_SENTRY_API_TOKEN
4983
```
5084

51-
See [Self-Hosted Sentry](../self-hosted/) for full setup details.
85+
### Self-hosted Sentry
5286

53-
### `sentry auth logout`
87+
```bash
88+
SENTRY_URL=https://sentry.example.com sentry auth login
89+
```
5490

55-
Remove stored credentials.
91+
For token-based auth with self-hosted:
5692

5793
```bash
58-
sentry auth logout
94+
SENTRY_URL=https://sentry.example.com sentry auth login --token YOUR_TOKEN
5995
```
6096

61-
### `sentry auth status`
97+
See [Self-Hosted Sentry](../self-hosted/) for details.
6298

63-
Check your authentication status.
99+
### Check auth status
64100

65101
```bash
66102
sentry auth status
67103
```
68104

69-
**Output:**
70-
71105
```
72106
Authenticated as: username
73107
Organization: my-org
74108
Token expires: 2024-12-31
75109
```
76110

77-
### `sentry auth refresh`
78-
79-
Refresh your OAuth token.
80-
81111
```bash
82-
sentry auth refresh
83-
```
112+
# Show the raw token
113+
sentry auth status --show-token
84114

85-
This is typically handled automatically when tokens expire.
115+
# View current user
116+
sentry auth whoami
117+
```
86118

87119
## Credential Storage
88120

89-
Credentials are stored in a SQLite database at `~/.sentry/cli.db` with restricted file permissions (mode 600).
90-
91-
Use `sentry auth token` to retrieve your current access token, or `sentry auth status` to check authentication state.
121+
Auth tokens are stored in a SQLite database at `~/.sentry/config.db` with restricted file permissions.
92122

93-
### Environment Variable Precedence
123+
## Environment Variable Precedence
94124

95125
The CLI checks for auth tokens in the following order, using the first one found:
96126

0 commit comments

Comments
 (0)