Dashboard › cli › Distillation
70d397a6-a5c9-4e9b-bbf5-7d47bcf8f021["lore_tm_v1_DcQsYUDFVjRTLU4rcwuCKf3U4sTmt3P92YOEzLNZoiY","lore_tm_v1_6ZhFIgsy1sV8KwBHUyE4AabNvgwSiNn4-AqMtO4uXwo","lore_tm_v1_wbwYj2rSMhBmkzl0xoGgfbKpOtPVJHzyv-T8Ks4Smrw","lore_tm_v1_qcTi0U5nHn4Gcf-p-ywYKfhvGTMG2Lr7ZZrqgefC9ao","lore_tm_v1_wryp1hXd5qbG3NwNWQqpgjZEVczv4z4UtgBltCpYciA","lore_tm_v1_yyTFpc5evS7_6XO0cRU0ev6VGQQUzW5y4pVNXo4Etjo","lore_tm_v1_NqCYGqyX-e3LiwyAnAL4e2V8XCoU2DgByOPM01PqNJw","lore_tm_v1_KRYOpDYsyHz20cYrmi-A-E3tX79brhVZQ7wHRtS-H40","lore_tm_v1_G2wkWVZXPK3bsHgY4uiKAY-oOPX-pzOS6_uNA5khmsk","lore_tm_v1_t7Dup_F1Nb8PX_o9Hv-JJtfrjSVQ7AdqhS5ntqiLwcE"]
Date: Sep 8, 2026
packages/cli/test/script/generate-skill-markdown.test.ts:50-52 additionally expects the valid slash-separated example sentry agent-conversation view my-org/conv-123 and the organization-less example sentry agent-conversation view conv-123.CHANGELOG.md records Stricli-related changes: line 259 moved --version/--help into the Stricli scanner and deleted argv-glue via PR #1348; line 260 replaced the argv-hoist preprocessor with a Stricli top-level-flags patch by @jared-outpost via PR #1340.@stricli/core to 1.2.7 rather than ^1.2.8, because the in-repository patch targeting 1.2.7 removes -H from Stricli’s reserved aliases so commands can retain curl-style -H for --header or --host. Never remove -H alias usages from command files. This rule was added in commit 78c9b04a5; Cursor Bugbot and Seer treat -H removal as blocking..lore.md: ContextError maps to 'context_missing' because omitted required context is user state and never a CLI bug; every AuthError reason (not_authenticated, expired, invalid) maps to 'auth_expected' because authentication failures are user/environment state after the CLI-19 fix.classifySilenced() mappings: OutputError → 'output_error'; ContextError → 'context_missing'; any AuthError → 'auth_expected'; ApiError with status >400 && <500 → 'api_user_error'; ApiError satisfying isSearchQueryParseError() → 'api_query_error'; TypeError satisfying isNetworkError() for raw "fetch failed" → 'network_error'; all other errors → null and are captured.recordSilencedError() must be wrapped in try/catch, so metric emission never blocks error handling.packages/cli/src/lib/command.ts:98,841-843 documents that native Stricli help consumes docs.customUsage, but Stricli does not expose it on the built command; the wrapper therefore stores the first custom usage line as a primary usage value.packages/cli/AGENTS.md:425-433 states that pnpm run generate:docs generates command docs and skill files and runs automatically through dev, build, typecheck, and test; command docs under docs/src/content/docs/commands/*.md are gitignored, skill files under plugins/sentry-cli/skills/sentry-cli/ are committed and auto-committed by CI when stale, custom prose belongs in docs/src/fragments/commands/, pnpm run check:fragments validates fragment/route consistency, and positional placeholders must be descriptive such as "org/project/trace-id" rather than "args".packages/cli/src/lib/route-map.ts is the sole wrapper permitted to import Stricli’s buildRouteMap. It auto-injects aliases in this order/mapping: list → ls, view → show, delete → remove and rm, create → new; aliases colliding with actual routes are skipped, and manually supplied args.aliases override generated aliases.packages/cli/plugins/sentry-cli/ contains exactly 2 entries: .claude-plugin/ and skills/.--json always gets structured output.packages/cli/src/commands/help.ts supports: sentry help or bare sentry for branded overview help, sentry help <command> for command-specific help, sentry help --json for the full structured command tree, and sentry help --json <command> for structured metadata about one command or group.packages/cli/src/commands/help.ts:46-61, an empty commandPath yields new CommandOutput(introspectAllCommands()); a nonempty path calls introspectCommand(commandPath), throws new OutputError(result) when the result contains "error", and otherwise yields new CommandOutput(result). Human output is rendered by formatHelpHuman.packages/cli/script/check-patches.ts validates patched Stricli behavior for both ESM and CJS: the top-level-flags scanner allow-list must support global flags before a subcommand such as sentry --verbose issue list; built-in -v as a version alias must be removed so sentry -v <command> runs verbosely rather than printing the version; and scanner versionRequested state must make sentry cli --version print the version.packages/cli/script/check-fragments.ts performs 5 checks. Check 5 validates subcommand coverage for routes with multiple commands by accepting either a full sentry <route> <subcommand> reference or a Markdown heading containing the leaf subcommand outside fenced code blocks; for a default command, bare sentry <route> also counts. Missing coverage is warning-only by default and becomes an error with --strict.packages/cli/test/lib/introspect.property.test.ts:139-172 property-tests getPositionalString(): tuple positionals with at least one parameter must contain angle brackets, while array positionals must always contain an ellipsis. Both use { numRuns: DEFAULT_NUM_RUNS }.packages/cli/test/lib/introspect.property.test.ts:175-195 property-tests that extractAllRoutes() never includes names belonging only to hidden entries; it first constructs visibleNames, derives onlyHiddenNames, and verifies no extracted route name appears in onlyHiddenNames, using { numRuns: DEFAULT_NUM_RUNS }.parameters.positional; displayed signatures use docs.customUsage with fallback synthesis from positional placeholders; native-help examples use docs.fullDescription; website and skill examples come from hand-written Markdown fragments; runtime recovery text comes from independent ContextError strings.agent-conversation route sources: /home/byk/Code/getsentry/cli-pr-1558/packages/cli/src/app.ts:111 registers "agent-conversation": conversationRoute, while hidden legacy "agent-conversations" points directly to conversationListCommand and is omitted from generated docs; /home/byk/Code/getsentry/cli-pr-1558/packages/cli/src/commands/agent-conversation/index.ts:11 registers listCommand and viewCommand, with group docs.brief feeding website and skill descriptions./home/byk/Code/getsentry/cli-pr-1558/packages/cli/src/commands/agent-conversation/list.ts: listCommand is at line 98; docs.customUsage at line 101 is "[<org>]"; examples are in docs.fullDescription at lines 102-109; lines 116-127 declare one optional tuple positional with placeholder "org"; lines 149-155 accept no argument and call resolveOrg; line 154 independently suggests sentry agent-conversation list <org> after auto-detection fails.ContextError recovery hint defensible despite differing from the optional canonical heading, because it tells the user how to recover after organization auto-detection fails; Copilot had flagged the discrepancy./home/byk/Code/getsentry/cli-pr-1558/packages/cli/src/commands/agent-conversation/view.ts: parseConversationTarget() at lines 42-57 consumes exactly one positional token and splits an optional organization prefix at /; viewCommand is at line 59; docs.customUsage at line 62 is "[<org>/]<conversation-id>"; docs.fullDescription at lines 63-70 uses conv-123 and my-org/conv-123; lines 75-86 declare one required tuple item with placeholder "org/conversation-id"; USAGE_HINT is used by ContextError at lines 54, 97, and 103.sentry agent-conversation view my-org conv-123 was always invalid because Stricli receives 2 positional tokens while the command declares exactly 1; valid forms are sentry agent-conversation view conv-123 and sentry agent-conversation view my-org/conv-123./home/byk/Code/getsentry/cli-pr-1558/packages/cli/src/lib/command.ts:492 passes docs.customUsage to Stricli and lines 841-847 preserve its first line in private __primaryUsage; /home/byk/Code/getsentry/cli-pr-1558/packages/cli/src/lib/introspect.ts:57-61 declares Command.__primaryUsage, lines 192-209 implement getPositionalString(), and lines 280-300 choose __primaryUsage ?? getPositionalString(parameters.positional).CommandInfo.positional consumers: website headings use generateCommandSection() in /home/byk/Code/getsentry/cli-pr-1558/packages/cli/script/generate-command-docs.ts:188; skill reference headings use generateFullCommandDoc() in /home/byk/Code/getsentry/cli-pr-1558/packages/cli/script/generate-skill.ts:565; compact skill entries use generateCompactCommandLine() at line 681; JSON/custom help uses formatCommandHuman() and introspection functions in /home/byk/Code/getsentry/cli-pr-1558/packages/cli/src/lib/help.ts:342-380,691-720.getPositionalString() always wraps tuple placeholders in <...> and ignores PositionalParam.optional, so the optional list argument previously rendered as <org>. extractPositionals() preserves optionality, but formatPositionalsTable() in generate-command-docs.ts:145 does not display it.view requires customUsage because tuple metadata can express that the physical positional token is required but cannot express the nested grammar where only the organization prefix within [<org>/]<conversation-id> is optional.docs.fullDescription survives as CommandInfo.fullDescription through /home/byk/Code/getsentry/cli-pr-1558/packages/cli/src/lib/introspect.ts:291-299, but neither documentation generator reads it. Instead, /home/byk/Code/getsentry/cli-pr-1558/packages/cli/script/generate-command-docs.ts builds generated sections, readCustomContent() at line 371 reads the fragment, and lines 413-423 append the fragment unchanged./home/byk/Code/getsentry/cli-pr-1558/apps/cli-docs/src/fragments/commands/agent-conversation.md as the effective example source and /home/byk/Code/getsentry/cli-pr-1558/apps/cli-docs/src/content/docs/commands/agent-conversation.md as the generated, gitignored website page; current headings are at lines 10 and 30 and fragment-derived examples begin at line 51./home/byk/Code/getsentry/cli-pr-1558/packages/cli/script/generate-skill.ts: loadCommandExamples() at line 416 reads the generated website page; collectCommandPaths() and associateCodeBlocks() infer examples from headings and bash blocks; extractRoutes() at line 476 stores them in CommandInfo.examples; generateFullCommandDoc() emits them into the skill reference./home/byk/Code/getsentry/cli-pr-1558/packages/cli/plugins/sentry-cli/skills/sentry-cli/references/agent-conversation.md and /home/byk/Code/getsentry/cli-pr-1558/packages/cli/plugins/sentry-cli/skills/sentry-cli/SKILL.md. Additional mirrors are /home/byk/Code/getsentry/cli-pr-1558/packages/cli/src/generated/skill-content.ts, which embeds both for installAgentSkills(), and /home/byk/Code/getsentry/cli-pr-1558/apps/cli-docs/public/.well-known/skills/index.json, generated by generateIndexJson() and listing references/agent-conversation.md; public SKILL.md and references paths are symlinks to tracked plugin files.7cf6483be: runtime parsing and fullDescription already described one positional correctly, but the hand-written fragment introduced the invalid two-token invocation; the generated website page incorporated the fragment; the skill generator copied it by reverse-parsing the website page; check-fragments.ts validates route/subcommand coverage but not invocation grammar.getPositionalString() discarded optionality and could not model an optional prefix within one required token. PR #1558 therefore needed to add customUsage, correct the committed fragment, and regenerate the committed skill reference and compact skill index.viewCommand directly uses buildCommand(), whose docs type supports customUsage, but listCommand uses buildListCommand(), whose duplicated docs type in /home/byk/Code/getsentry/cli-pr-1558/packages/cli/src/lib/list-command.ts:546-552 allows only brief and fullDescription. buildDeleteCommand() and OrgListCommandDocs duplicate the same narrowed shape.pnpm exec tsc --noEmit run reported list.ts(101,5): TS2353: 'customUsage' does not exist in type .... Generation nevertheless works because tsx transpiles without type-checking and buildListCommand() spreads the docs object into buildCommand() at /home/byk/Code/getsentry/cli-pr-1558/packages/cli/src/lib/list-command.ts:617-622./home/byk/Code/getsentry/cli-pr-1558/packages/cli/test/script/generate-skill-markdown.test.ts:28-53 as insufficient: they assert already-generated Markdown rather than proving command metadata produced it, and they do not cover the list command’s ContextError hint.CommandDocumentation from command.ts and reuse it in buildListCommand(), OrgListCommandDocs, and buildDeleteCommand() so wrappers retain Stricli fields. 2. Add structured examples to buildCommand() metadata, retain them alongside __primaryUsage, expose them through buildCommandInfo(), and optionally render them into native fullDescription. 3. Make both generate-command-docs.ts and generate-skill.ts consume the same CommandInfo.examples, remove generated-Markdown reverse parsing, keep fragments for prose/guides, and temporarily support fragment examples as a migration fallback. 4. Make getPositionalString() honor optionality and formatPositionalsTable() display it, reserving customUsage for compound grammar. 5. Define each complex usage suffix once and derive both docs.customUsage and full runtime hints from it, e.g. const USAGE = "[<org>/]<conversation-id>"; const USAGE_HINT = \sentry agent-conversation view ${USAGE}`;`.generate:docs runs command-doc generation before skill generation as configured in /home/byk/Code/getsentry/cli-pr-1558/packages/cli/package.json:71, and that the worktree remained clean after the read-only investigation.