refactor(cli): Centralize target syntax and lint free-text help examples

packages/cli/AGENTS.md

@@ -509,7 +509,8 @@ All command docs and skill files are generated via `pnpm run generate:docs` (whi
 
 - **Command docs** (`apps/cli-docs/src/content/docs/commands/*.md`) and the configuration page (`apps/cli-docs/src/content/docs/configuration.md`) are **gitignored** and generated from CLI metadata + hand-written fragments in `apps/cli-docs/src/fragments/` (paths live in `script/paths.ts`).
 - **Skill files** (`plugins/sentry-cli/skills/sentry-cli/`) are **committed** (consumed by external plugin systems) and auto-committed by CI when stale.
-- **Examples belong to the command**: add them to `docs.examples` (`{ description, command }[]`, see `src/commands/agent-conversation/list.ts`). They render in `--help`, the generated docs, and the skill references. Don't hand-write an `Examples:` block in `fullDescription` or an Examples heading in a fragment; the `sentry-cli/no-examples-in-full-description` lint rule and `pnpm run check:fragments` reject both.
+- **Examples belong to the command**: add them to `docs.examples` (`{ description, command }[]`, see `src/commands/agent-conversation/list.ts`). They render in `--help`, the generated docs, and the skill references. Don't hand-write examples in `fullDescription` (an `Examples:` block, or indented `sentry …` lines under any label) or an Examples heading in a fragment; the `sentry-cli/no-examples-in-full-description` lint rule and `pnpm run check:fragments` reject both.
+- **Target syntax belongs to the positional**: describe accepted target forms in the positional `brief` (use `ORG_ALL_TARGET_BRIEF` or `PROJECT_TARGET_BRIEF` from `src/lib/list-command.ts` for `[<org>/][<project>]` targets), not in a `Target patterns:` block. The brief renders in `--help`, the generated docs, and the skill references.
 - Use fragments in `apps/cli-docs/src/fragments/commands/` only for prose the command metadata can't carry: guides, permissions, caveats.
 - `pnpm run check:fragments` also rejects any shell code block in a fragment that runs a `sentry` command, whatever its heading. For a real workflow, sample output, or cross-command guide, put `<!-- allow-commands: <reason> -->` on the line directly above the block.
 - `pnpm run check:fragments` validates fragment ↔ route consistency.

packages/cli/lint-rules/cli-oxlint-plugin.js

@@ -106,8 +106,14 @@ function staticText(node) {
 /** Matches a heading or label line that opens an Examples section. */
 const EXAMPLES_LABEL_RE = /^examples?:?$/i;
 
-/** Whether help text has an Examples heading or an `Examples:` label line. */
+/** Matches an indented `sentry …` usage line, whatever label sits above it. */
+const EXAMPLE_LINE_RE = /^[ \t]+sentry\s/;
+
+/** Whether help text has an Examples section or free-text example lines. */
 function hasExamplesSection(text) {
+  if (text.split("\n").some((line) => EXAMPLE_LINE_RE.test(line))) {
+    return true;
+  }
   return marked
     .lexer(text)
     .some((token) =>

packages/cli/plugins/sentry-cli/skills/sentry-cli/references/agent-conversation.md

@@ -15,6 +15,12 @@ List and view agent conversations
 
 List recent agent conversations
 
+**Arguments:**
+
+| Argument | Description |
+|----------|-------------|
+| `[<org/project>]` | &lt;org&gt;/ (all projects), &lt;org&gt;/&lt;project&gt;, or &lt;project&gt; (search) |
+
 **Flags:**
 - `-n, --limit <value> - Number of conversations (1-1000) - (default: "25")`
 - `-q, --query <value> - Any matching span selects its conversation; totals include all spans in selected projects and time range`
@@ -90,6 +96,12 @@ sentry agent-conversation list my-org/my-project -c next
 
 View an agent conversation transcript
 
+**Arguments:**
+
+| Argument | Description |
+|----------|-------------|
+| `[<org>/]<conversation-id>` | Organization slug (optional) and conversation ID |
+
 **Flags:**
 - `-f, --fresh - Bypass cache, re-detect projects, and fetch fresh data`
 

packages/cli/plugins/sentry-cli/skills/sentry-cli/references/alert.md

@@ -15,6 +15,12 @@ Manage Sentry alert rules
 
 List issue alert rules
 
+**Arguments:**
+
+| Argument | Description |
+|----------|-------------|
+| `[<org/project>]` | &lt;org&gt;/ (all projects), &lt;org&gt;/&lt;project&gt;, or &lt;project&gt; (search) |
+
 **Flags:**
 - `-w, --web - Open in browser`
 - `-n, --limit <value> - Maximum number of issue alert rules to list - (default: "25")`
@@ -25,17 +31,32 @@ List issue alert rules
 **Examples:**
 
 ```bash
+# List issue alert rules (project auto-detected)
+sentry alert issues list
+
 # List issue alert rules for a project
 sentry alert issues list my-org/my-project
 
 # Filter rules by name
 sentry alert issues list my-org/my-project --query "spike"
+
+# List issue alert rules for all projects in an organization
+sentry alert issues list my-org/
+
+# Find a project across organizations
+sentry alert issues list frontend
 ```
 
 ### `sentry alert issues view <org/project/rule-id-or-name>`
 
 View an issue alert rule
 
+**Arguments:**
+
+| Argument | Description |
+|----------|-------------|
+| `<org/project/rule-id-or-name>` | Issue alert rule ID or name |
+
 **Flags:**
 - `-w, --web - Open issue alert rules page in browser`
 
@@ -56,6 +77,12 @@ sentry alert issues view my-org/my-project/'Error Spike'
 
 Create an issue alert rule
 
+**Arguments:**
+
+| Argument | Description |
+|----------|-------------|
+| `[<target>]` | &lt;org&gt;/&lt;project&gt;, auto-detected project, or &lt;project&gt; (search) |
+
 **Flags:**
 - `--name <value> - Rule name`
 - `-c, --condition <value>... - Condition object JSON (repeatable, or pass one JSON array)`
@@ -83,6 +110,12 @@ Delete an issue alert rule
 
 **Destructive:** This command deletes data or makes changes that can't easily be undone. Use `--dry-run` to preview the changes first. Confirm with the user before running it.
 
+**Arguments:**
+
+| Argument | Description |
+|----------|-------------|
+| `<org/project/rule-id-or-name>` | Rule id or name (same as view) |
+
 **Flags:**
 - `-y, --yes - Skip confirmation prompt`
 - `-f, --force - Force the operation without confirmation`
@@ -105,6 +138,12 @@ sentry alert issues delete my-org/my-project/12345 --dry-run
 
 Edit an issue alert rule
 
+**Arguments:**
+
+| Argument | Description |
+|----------|-------------|
+| `<org/project/rule-id-or-name>` | Rule id or name (same as view) |
+
 **Flags:**
 - `--name <value> - New rule name`
 - `--status <value> - Rule status: active or disabled`
@@ -136,6 +175,12 @@ sentry alert issues edit my-org/my-project/12345 --condition '{"type":"first_see
 
 List metric alert rules
 
+**Arguments:**
+
+| Argument | Description |
+|----------|-------------|
+| `[<target>]` | &lt;org&gt;/, &lt;org&gt;/&lt;project&gt; (project ignored), or &lt;project&gt; (search) |
+
 **Flags:**
 - `-w, --web - Open in browser`
 - `-n, --limit <value> - Maximum number of metric alert rules to list - (default: "25")`
@@ -146,14 +191,26 @@ List metric alert rules
 **Examples:**
 
 ```bash
+# List metric alert rules (organization auto-detected)
+sentry alert metrics list
+
 # List metric alert rules for an organization
 sentry alert metrics list my-org/
+
+# Fetch the next page
+sentry alert metrics list my-org/ -c next
 ```
 
 ### `sentry alert metrics view <org/rule-id-or-name>`
 
 View a metric alert rule
 
+**Arguments:**
+
+| Argument | Description |
+|----------|-------------|
+| `<org/rule-id-or-name>` | Metric alert rule ID or name |
+
 **Flags:**
 - `-w, --web - Open metric alert rules page in browser`
 
@@ -174,6 +231,12 @@ sentry alert metrics view my-org/'P95 latency alert'
 
 Create a metric alert rule
 
+**Arguments:**
+
+| Argument | Description |
+|----------|-------------|
+| `<target>` | Target project or organization |
+
 **Flags:**
 - `--name <value> - Rule name`
 - `--query <value> - Metric query filter string`
@@ -203,6 +266,12 @@ Delete a metric alert rule
 
 **Destructive:** This command deletes data or makes changes that can't easily be undone. Use `--dry-run` to preview the changes first. Confirm with the user before running it.
 
+**Arguments:**
+
+| Argument | Description |
+|----------|-------------|
+| `<org/rule-id-or-name>` | Rule id or name (same as view) |
+
 **Flags:**
 - `-y, --yes - Skip confirmation prompt`
 - `-f, --force - Force the operation without confirmation`
@@ -222,6 +291,12 @@ sentry alert metrics delete my-org/'P95 alert' --yes
 
 Edit a metric alert rule
 
+**Arguments:**
+
+| Argument | Description |
+|----------|-------------|
+| `<org/rule-id-or-name>` | Rule id or name (same as view) |
+
 **Flags:**
 - `--name <value> - New rule name`
 - `--status <value> - active or disabled`

packages/cli/plugins/sentry-cli/skills/sentry-cli/references/api.md

@@ -15,6 +15,12 @@ Make an authenticated API request
 
 Make an authenticated API request
 
+**Arguments:**
+
+| Argument | Description |
+|----------|-------------|
+| `<endpoint>` | API endpoint relative to /api/0/, or an absolute HTTP(S) URL |
+
 **Flags:**
 - `-X, --method <value> - The HTTP method for the request - (default: "GET")`
 - `-d, --data <value> - Inline JSON body for the request (like curl -d)`

packages/cli/plugins/sentry-cli/skills/sentry-cli/references/auth.md

@@ -26,6 +26,12 @@ sentry auth list
 
 Authenticate with Sentry
 
+**Arguments:**
+
+| Argument | Description |
+|----------|-------------|
+| `[<email>]` | Email of the account to add or log in to again (&lt;email&gt;:&lt;server&gt; also sets --url); the login is refused if you approve it as someone else |
+
 **Flags:**
 - `--token <value> - Authenticate using an API token instead of OAuth`
 - `--timeout <value> - Timeout for OAuth flow in seconds (default: 900) - (default: "900")`
@@ -69,6 +75,12 @@ sentry auth login jane@example.com:sentry.example.com
 
 Log out of Sentry
 
+**Arguments:**
+
+| Argument | Description |
+|----------|-------------|
+| `<account...>` | Accounts to log out of (email, username, user ID, or account ID; comma-separated), or 'all' |
+
 **Flags:**
 - `--url <value> - Only match accounts on this server (disambiguates the same email on several servers)`
 
@@ -141,6 +153,12 @@ sentry auth status --show-token
 
 Switch the active account
 
+**Arguments:**
+
+| Argument | Description |
+|----------|-------------|
+| `[<account>]` | Email, username, user ID, or account ID to switch to |
+
 **Flags:**
 - `--url <value> - Only consider accounts on this server (disambiguates the same email on several servers)`
 

packages/cli/plugins/sentry-cli/skills/sentry-cli/references/build.md

@@ -15,6 +15,12 @@ Manage mobile build artifacts
 
 Upload builds to a project
 
+**Arguments:**
+
+| Argument | Description |
+|----------|-------------|
+| `<path...>` | Path(s) to the build(s) to upload (APK, AAB, IPA, or XCArchive) |
+
 **Flags:**
 - `--build-configuration <value> - Build configuration for the upload (defaults to the current version)`
 - `--release-notes <value> - Release notes for the build`
@@ -60,6 +66,12 @@ sentry build upload ./app.aab --head-sha "$GIT_SHA" --pr-number 42 --base-ref ma
 
 Download a build artifact
 
+**Arguments:**
+
+| Argument | Description |
+|----------|-------------|
+| `<build-id>` | ID of the build to download |
+
 **Flags:**
 - `-o, --output <value> - Output path (default: preprod_artifact_<build-id>.<ext> in the current directory)`
 

packages/cli/plugins/sentry-cli/skills/sentry-cli/references/cli.md

@@ -15,6 +15,12 @@ CLI-related commands
 
 Print the shell completion script
 
+**Arguments:**
+
+| Argument | Description |
+|----------|-------------|
+| `[<shell>]` | Shell to generate completions for (bash, zsh, or fish) |
+
 **Examples:**
 
 ```bash
@@ -35,6 +41,12 @@ sentry cli completion fish > ~/.config/fish/completions/sentry.fish
 
 View and manage default settings
 
+**Arguments:**
+
+| Argument | Description |
+|----------|-------------|
+| `<key value...>` | Setting key and optional value |
+
 **Flags:**
 - `--clear - Clear the specified default, or all defaults if no key is given`
 - `-y, --yes - Skip confirmation prompt`
@@ -87,6 +99,12 @@ sentry cli defaults --clear --yes
 
 Send feedback about the CLI
 
+**Arguments:**
+
+| Argument | Description |
+|----------|-------------|
+| `<message...>` | Your feedback message |
+
 **Examples:**
 
 ```bash
@@ -210,6 +228,12 @@ sentry cli uninstall
 
 Update the Sentry CLI to the latest version
 
+**Arguments:**
+
+| Argument | Description |
+|----------|-------------|
+| `[<version>]` | Specific version (e.g. 0.5.0), or "nightly"/"stable" to switch channel; omit to update within current channel |
+
 **Flags:**
 - `--check - Check for updates without installing`
 - `--force - Force upgrade even if already on the latest version`

packages/cli/plugins/sentry-cli/skills/sentry-cli/references/code-mappings.md

@@ -15,6 +15,12 @@ Manage code mappings for stack trace linking
 
 Upload code mappings for stack trace linking
 
+**Arguments:**
+
+| Argument | Description |
+|----------|-------------|
+| `<path>` | Path to the code mappings JSON file |
+
 **Flags:**
 - `--repo <value> - Repository name (e.g., owner/repo). Auto-detected from git remote if omitted.`
 - `--default-branch <value> - Default branch name. Auto-detected from git remote HEAD if omitted.`

packages/cli/plugins/sentry-cli/skills/sentry-cli/references/dart-symbol-map.md

@@ -15,6 +15,12 @@ Work with Dart/Flutter symbol maps
 
 Upload a Dart/Flutter symbol map to Sentry
 
+**Arguments:**
+
+| Argument | Description |
+|----------|-------------|
+| `<path>` | Path to the dart symbol map JSON file |
+
 **Flags:**
 - `-d, --debug-id <value> - Debug ID (UUID) from the companion native debug file`
 - `--no-upload - Validate the file without uploading (dry-run)`