Skip to content

Commit 4ed54da

Browse files
BYKBYK
committed
feat(docs): auto-generate command reference pages from route tree
Replace hand-written command doc pages with auto-generated reference sections extracted from Stricli route tree introspection. This fixes pervasive documentation drift: phantom flags (--include, --paginate, --channel), missing flags (--fresh, --fields, --cursor, --period, --spans), and missing aliases across all command pages. Each doc page now has two parts separated by a GENERATED:END marker: 1. Auto-generated reference (args, options tables) — from source code 2. Hand-written custom content (examples, guides) — preserved on regen New infrastructure: - script/generate-command-docs.ts: generates reference sections - script/check-command-docs.ts: CI freshness checker - src/lib/introspect.ts: add extractPositionals() for arg tables - CI auto-commits regenerated docs alongside skill files Also adds extractPositionals() and PositionalInfo type to introspect.ts for structured positional argument metadata.
1 parent 9227999 commit 4ed54da

36 files changed

Lines changed: 1286 additions & 1748 deletions

‎.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: 59 additions & 52 deletions
Large diffs are not rendered by default.

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

Lines changed: 30 additions & 86 deletions
Original file line numberDiff line numberDiff line change
@@ -1,114 +1,58 @@
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 |
33-
34-
## Examples
35-
36-
### GET Request
37-
38-
```bash
39-
# List organizations
40-
sentry api /organizations/
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 |
4133

42-
# Get a specific organization
43-
sentry api /organizations/my-org/
34+
All commands support `--json` for machine-readable output and `--fields` to select specific JSON fields.
4435

45-
# Get project details
46-
sentry api /projects/my-org/my-project/
47-
```
48-
49-
### POST Request
50-
51-
```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
57-
```
58-
59-
### PUT Request
36+
<!-- GENERATED:END -->
6037

61-
```bash
62-
# Update an issue status
63-
sentry api /issues/123456789/ \
64-
--method PUT \
65-
--field status=resolved
66-
67-
# Assign an issue
68-
sentry api /issues/123456789/ \
69-
--method PUT \
70-
--field assignedTo="user@example.com"
71-
```
72-
73-
### DELETE Request
38+
## Examples
7439

7540
```bash
76-
# Delete a project
77-
sentry api /projects/my-org/my-project/ \
78-
--method DELETE
79-
```
80-
81-
### With Headers
41+
# GET request (default)
42+
sentry api /api/0/organizations/
8243

83-
```bash
84-
sentry api /organizations/ \
85-
--header "X-Custom-Header:value"
86-
```
44+
# POST with JSON body
45+
sentry api /api/0/organizations/my-org/issues/ -X POST -d '{"status": "resolved"}'
8746

88-
### Verbose Mode
47+
# Pass individual fields (auto-encoded as JSON body)
48+
sentry api /api/0/projects/my-org/my-project/ -X PUT -F name=new-name
8949

90-
```bash
91-
sentry api /organizations/ --verbose
92-
```
50+
# Add custom headers
51+
sentry api /api/0/organizations/ -H "X-Custom: value"
9352

94-
Request and response metadata is logged to stderr:
53+
# Read body from a file
54+
sentry api /api/0/projects/my-org/my-project/releases/ -X POST -i release.json
9555

56+
# Preview the request without sending
57+
sentry api /api/0/organizations/ --dry-run
9658
```
97-
> GET /api/0/organizations/
98-
>
99-
< HTTP 200
100-
< content-type: application/json
101-
<
102-
[{"slug": "my-org", ...}]
103-
```
104-
105-
### Pagination
106-
107-
```bash
108-
# Get all issues (automatically follows pagination)
109-
sentry api /projects/my-org/my-project/issues/ --paginate
110-
```
111-
112-
## API Documentation
113-
114-
For full API documentation, see the [Sentry API Reference](https://docs.sentry.io/api/).

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

Lines changed: 46 additions & 61 deletions
Original file line numberDiff line numberDiff line change
@@ -1,101 +1,86 @@
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.
13-
14-
```bash
15-
# OAuth device flow (recommended)
16-
sentry auth login
17-
18-
# Using an API token
19-
sentry auth login --token YOUR_TOKEN
20-
```
12+
Authenticate with Sentry
2113

2214
**Options:**
2315

2416
| Option | Description |
2517
|--------|-------------|
26-
| `--token <token>` | Use an API token instead of OAuth |
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 |
2721

28-
**OAuth Flow:**
29-
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
22+
### `sentry auth logout`
3623

37-
**Self-Hosted Sentry (26.1.0+):**
24+
Log out of Sentry
3825

39-
For self-hosted instances, set `SENTRY_URL` and `SENTRY_CLIENT_ID` (from a public OAuth application you create on your instance):
26+
### `sentry auth refresh`
4027

41-
```bash
42-
SENTRY_URL=https://sentry.example.com SENTRY_CLIENT_ID=your-client-id sentry auth login
43-
```
28+
Refresh your authentication token
4429

45-
On older versions or without an OAuth application, use an API token instead:
30+
**Options:**
4631

47-
```bash
48-
SENTRY_URL=https://sentry.example.com sentry auth login --token YOUR_TOKEN
49-
```
32+
| Option | Description |
33+
|--------|-------------|
34+
| `--force` | Force refresh even if token is still valid |
5035

51-
See [Self-Hosted Sentry](../self-hosted/) for full setup details.
36+
### `sentry auth status`
5237

53-
### `sentry auth logout`
38+
View authentication status
5439

55-
Remove stored credentials.
40+
**Options:**
5641

57-
```bash
58-
sentry auth logout
59-
```
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 |
6046

61-
### `sentry auth status`
47+
### `sentry auth token`
6248

63-
Check your authentication status.
49+
Print the stored authentication token
6450

65-
```bash
66-
sentry auth status
67-
```
51+
### `sentry auth whoami`
6852

69-
**Output:**
53+
Show the currently authenticated user
7054

71-
```
72-
Authenticated as: username
73-
Organization: my-org
74-
Token expires: 2024-12-31
75-
```
55+
**Options:**
7656

77-
### `sentry auth refresh`
57+
| Option | Description |
58+
|--------|-------------|
59+
| `-f, --fresh` | Bypass cache, re-detect projects, and fetch fresh data |
7860

79-
Refresh your OAuth token.
61+
All commands support `--json` for machine-readable output and `--fields` to select specific JSON fields.
8062

81-
```bash
82-
sentry auth refresh
83-
```
63+
<!-- GENERATED:END -->
8464

85-
This is typically handled automatically when tokens expire.
65+
## Examples
8666

87-
## Credential Storage
67+
```bash
68+
# OAuth login (recommended)
69+
sentry auth login
8870

89-
Credentials are stored in a SQLite database at `~/.sentry/cli.db` with restricted file permissions (mode 600).
71+
# Login with an API token
72+
sentry auth login --token YOUR_SENTRY_API_TOKEN
9073

91-
Use `sentry auth token` to retrieve your current access token, or `sentry auth status` to check authentication state.
74+
# Check auth status
75+
sentry auth status
9276

93-
### Environment Variable Precedence
77+
# Show the raw token
78+
sentry auth status --show-token
9479

95-
The CLI checks for auth tokens in the following order, using the first one found:
80+
# View current user
81+
sentry auth whoami
82+
```
9683

97-
1. `SENTRY_AUTH_TOKEN` environment variable (legacy)
98-
2. `SENTRY_TOKEN` environment variable
99-
3. The stored token in the SQLite database
84+
## Credential Storage
10085

101-
When a token comes from an environment variable, the CLI skips expiry checks and automatic refresh.
86+
Auth tokens are stored securely in a local SQLite database at `~/.sentry/config.db`.

0 commit comments

Comments
 (0)