fix: improve argument parsing for common user mistakes (#363)

## Fix ResolutionError UX: Argument Swapping + Smarter Fallbacks

Fixes CLI-BG, CLI-BB, CLI-BA, CLI-B9, CLI-B8

Users hit `ResolutionError`s because the CLI misinterprets their input
in several common scenarios:

| Issue | User Input | Root Cause |
|-------|-----------|------------|
| CLI-BG | `sentry log view a9b4ad2c mv-software/mvsoftware` | Args
reversed (ID first, target second) |
| CLI-B8 | `sentry event view CAM-82X 95fd7f5a` | First arg is issue
short ID, not a target |
| CLI-BB | `sentry issue view org/project/101149101` | Multi-slash
parsed incorrectly |
| CLI-BA | `sentry issues techdoctor-inc/selfbase_admin_backend` |
Underscores in project slug |
| CLI-B9 | `sentry issue list kaiko-systems-gmbh` | Bare org slug
misinterpreted as project-search |

### Changes

1. **Argument swap detection** — `detectSwappedViewArgs()` detects when
users reverse `<target> <id>` ordering in view commands. Auto-corrects
with a warning.

2. **Underscore normalization** — `normalizeSlug()` converts underscores
to dashes at the parsing layer since Sentry slugs never contain
underscores.

3. **Multi-slash issue arg** — `parseMultiSlashIssueArg()` correctly
splits `org/project/issueId` instead of producing a broken suffix.

4. **Org-as-project auto-redirect** — When a bare slug matches an
organization (not a project), list commands auto-redirect to org-all
mode. View commands show a clear "is an organization, not a project"
error. Refactored `findProjectsBySlug` to return `{ projects, orgs }` to
avoid double API calls.

5. **Issue short ID detection** — Suggests `sentry issue view X` when
the first arg in event/log/trace view matches the issue short ID pattern
(e.g., `CAM-82X`).

6. **Removed `stderr` threading** — Replaced all `stderr.write()` usage
in resolve-target and view commands with Consola logger (`log.warn()`),
simplifying function signatures.

### Tests

- 35 new unit + property tests for helpers (`normalizeSlug`,
`looksLikeIssueShortId`, `detectSwappedViewArgs`, underscore
normalization, multi-slash parsing)
- Updated 12 existing test files to accommodate return type and
signature changes
- All 2738 unit tests pass

Author: BYK

AGENTS.md

@@ -651,6 +651,15 @@ mock.module("./some-module", () => ({
 
 ### Decision
 
+<!-- lore:019cc2ef-9be5-722d-bc9f-b07a8197eeed -->
+* **All view subcommands should use \<target> \<id> positional pattern**: All \`\* view\` subcommands (\`event view\`, \`log view\`, \`trace view\`, etc.) should follow a consistent \`\<target> \<id>\` positional argument pattern where target is the optional \`org/project\` specifier. During migration, use opportunistic argument swapping with a stderr warning when the user provides args in the wrong order. This follows the CLI UX auto-correction pattern: safe when input is already invalid, no ambiguity, and warning goes to stderr.
+
+<!-- lore:019c99d5-69f2-74eb-8c86-411f8512801d -->
+* **Raw markdown output for non-interactive terminals, rendered for TTY**: Markdown-first output pipeline: custom renderer in \`src/lib/formatters/markdown.ts\` walks \`marked\` tokens to produce ANSI-styled output. Commands build CommonMark using helpers (\`mdKvTable()\`, \`mdRow()\`, \`colorTag()\`, \`escapeMarkdownCell()\`, \`safeCodeSpan()\`) and pass through \`renderMarkdown()\`. \`isPlainOutput()\` precedence: \`SENTRY\_PLAIN\_OUTPUT\` > \`NO\_COLOR\` > \`FORCE\_COLOR\` > \`!isTTY\`. \`--json\` always outputs JSON. Colors defined in \`COLORS\` object in \`colors.ts\`. Tests run non-TTY so assertions match raw CommonMark; use \`stripAnsi()\` helper for rendered-mode assertions.
+
+<!-- lore:00166785-609d-4ab5-911e-ee205d17b90c -->
+* **whoami should be separate from auth status command**: The \`sentry auth whoami\` command should be a dedicated command separate from \`sentry auth status\`. They serve different purposes: \`status\` shows everything about auth state (token, expiry, defaults, org verification), while \`whoami\` just shows user identity (name, email, username, ID) by fetching live from \`/auth/\` endpoint. \`sentry whoami\` should be a top-level alias (like \`sentry issues\` → \`sentry issue list\`). \`whoami\` should support \`--json\` for machine consumption and be lightweight — no credential verification, no defaults listing.
+
 <!-- lore:019c8f3b-84be-79be-9518-e5ecd2ea64b9 -->
 * **Use -t (not -p) as shortcut alias for --period flag**: The --period flag on issue list uses -t (for 'time period') as its short alias, not -p. The rationale: -p could be confused with --platform from other CLI tools/contexts. -t maps naturally to 'time period' and avoids collision. This was a deliberate choice after initial implementation used -p.
 
@@ -676,6 +685,9 @@ mock.module("./some-module", () => ({
 <!-- lore:dbd63348-2049-42b3-bb99-d6a3d64369c7 -->
 * **Branch naming and commit message conventions for Sentry CLI**: Branch naming: \`feat/\<short-description>\` or \`fix/\<issue-number>-\<short-description>\` (e.g., \`feat/ghcr-nightly-distribution\`, \`fix/268-limit-auto-pagination\`). Commit message format: \`type(scope): description (#issue)\` (e.g., \`fix(issue-list): auto-paginate --limit beyond 100 (#268)\`, \`feat(nightly): distribute via GHCR instead of GitHub Releases\`). Types seen: fix, refactor, meta, release, feat. PRs are created as drafts via \`gh pr create --draft\`. Implementation plans are attached to commits via \`git notes add\` rather than in PR body or commit message.
 
+<!-- lore:5ac4e219-ea1f-41cb-8e97-7e946f5848c0 -->
+* **PR workflow: wait for Seer and Cursor BugBot before resolving**: After pushing a PR in the getsentry/cli repo, the CI pipeline includes Seer Code Review and Cursor Bugbot as advisory checks. Both typically take 2-3 minutes but may not trigger on draft PRs — only ready-for-review PRs reliably get bot reviews. The workflow is: push → wait for all CI (including npm build jobs which test the actual bundle) → check for inline review comments from Seer/BugBot → fix if needed → repeat. Use \`gh pr checks \<PR> --watch\` to monitor. Review comments are fetched via \`gh api repos/OWNER/REPO/pulls/NUM/comments\` and \`gh api repos/OWNER/REPO/pulls/NUM/reviews\`.
+
 <!-- lore:019cc3e6-0cf5-720d-beb7-97c9c9901295 -->
 * **Codecov patch coverage only counts test:unit and test:isolated, not E2E**: CI coverage merges \`test:unit\` (\`test/lib test/commands test/types --coverage\`) and \`test:isolated\` (\`test/isolated --coverage\`) into \`coverage/merged.lcov\`. E2E tests (\`test/e2e\`) are NOT included in coverage reports. So func tests that spy on exports (e.g., \`spyOn(apiClient, 'getLogs')\`) give zero coverage to the mocked function's body. To cover \`api-client.ts\` function bodies in unit tests, mock \`globalThis.fetch\` + \`setOrgRegion()\` + \`setAuthToken()\` and call the real function.
 

src/commands/event/view.ts

@@ -12,6 +12,8 @@ import {
   resolveEventInOrg,
 } from "../../lib/api-client.js";
 import {
+  detectSwappedViewArgs,
+  looksLikeIssueShortId,
   ProjectSpecificationType,
   parseOrgProjectArg,
   parseSlashSeparatedArg,
@@ -21,6 +23,7 @@ import { openInBrowser } from "../../lib/browser.js";
 import { buildCommand } from "../../lib/command.js";
 import { ContextError, ResolutionError } from "../../lib/errors.js";
 import { formatEventDetails, writeJson } from "../../lib/formatters/index.js";
+import { logger } from "../../lib/logger.js";
 import { resolveEffectiveOrg } from "../../lib/region.js";
 import {
   resolveOrgAndProject,
@@ -88,6 +91,10 @@ const USAGE_HINT = "sentry event view <org>/<project> <event-id>";
 export function parsePositionalArgs(args: string[]): {
   eventId: string;
   targetArg: string | undefined;
+  /** Warning message if arguments appear to be in the wrong order */
+  warning?: string;
+  /** Suggestion when the user likely meant a different command */
+  suggestion?: string;
 } {
   if (args.length === 0) {
     throw new ContextError("Event ID", USAGE_HINT);
@@ -130,8 +137,19 @@ export function parsePositionalArgs(args: string[]): {
     return { eventId: first, targetArg: undefined };
   }
 
+  // Detect swapped args: user put ID first and target second
+  const swapWarning = detectSwappedViewArgs(first, second);
+  if (swapWarning) {
+    return { eventId: first, targetArg: second, warning: swapWarning };
+  }
+
+  // Detect issue short ID passed as first arg (e.g., "CAM-82X 95fd7f5a")
+  const suggestion = looksLikeIssueShortId(first)
+    ? `Did you mean: sentry issue view ${first}`
+    : undefined;
+
   // Two or more args - first is target, second is event ID
-  return { eventId: second, targetArg: first };
+  return { eventId: second, targetArg: first, suggestion };
 }
 
 /**
@@ -153,7 +171,6 @@ type ResolveTargetOptions = {
   parsed: ReturnType<typeof parseOrgProjectArg>;
   eventId: string;
   cwd: string;
-  stderr: { write(s: string): void };
 };
 
 /**
@@ -166,7 +183,7 @@ type ResolveTargetOptions = {
 export async function resolveEventTarget(
   options: ResolveTargetOptions
 ): Promise<ResolvedEventTarget | null> {
-  const { parsed, eventId, cwd, stderr } = options;
+  const { parsed, eventId, cwd } = options;
 
   switch (parsed.type) {
     case ProjectSpecificationType.Explicit: {
@@ -183,8 +200,7 @@ export async function resolveEventTarget(
       const resolved = await resolveProjectBySlug(
         parsed.projectSlug,
         USAGE_HINT,
-        `sentry event view <org>/${parsed.projectSlug} ${eventId}`,
-        stderr
+        `sentry event view <org>/${parsed.projectSlug} ${eventId}`
       );
       return {
         ...resolved,
@@ -199,7 +215,7 @@ export async function resolveEventTarget(
     }
 
     case ProjectSpecificationType.AutoDetect:
-      return resolveAutoDetectTarget(eventId, cwd, stderr);
+      return resolveAutoDetectTarget(eventId, cwd);
 
     default:
       return null;
@@ -244,8 +260,7 @@ export async function resolveOrgAllTarget(
 /** @internal Exported for testing */
 export async function resolveAutoDetectTarget(
   eventId: string,
-  cwd: string,
-  stderr: { write(s: string): void }
+  cwd: string
 ): Promise<ResolvedEventTarget | null> {
   const autoTarget = await resolveOrgAndProject({ cwd, usageHint: USAGE_HINT });
   if (autoTarget) {
@@ -254,10 +269,12 @@ export async function resolveAutoDetectTarget(
 
   const resolved = await findEventAcrossOrgs(eventId);
   if (resolved) {
-    stderr.write(
-      `Tip: Found event in ${resolved.org}/${resolved.project}. ` +
-        `Use: sentry event view ${resolved.org}/${resolved.project} ${eventId}\n`
-    );
+    logger
+      .withTag("event.view")
+      .warn(
+        `Found event in ${resolved.org}/${resolved.project}. ` +
+          `Use: sentry event view ${resolved.org}/${resolved.project} ${eventId}`
+      );
     return {
       org: resolved.org,
       project: resolved.project,
@@ -311,15 +328,26 @@ export const viewCommand = buildCommand({
   ): Promise<void> {
     const { stdout, cwd } = this;
 
+    const log = logger.withTag("event.view");
+
     // Parse positional args
-    const { eventId, targetArg } = parsePositionalArgs(args);
+    const { eventId, targetArg, warning, suggestion } =
+      parsePositionalArgs(args);
+    if (warning) {
+      log.warn(warning);
+    }
+    if (suggestion) {
+      log.warn(suggestion);
+    }
     const parsed = parseOrgProjectArg(targetArg);
+    if (parsed.type !== "auto-detect" && parsed.normalized) {
+      log.warn("Normalized slug (Sentry slugs use dashes, not underscores)");
+    }
 
     const target = await resolveEventTarget({
       parsed,
       eventId,
       cwd,
-      stderr: this.stderr,
     });
 
     if (!target) {

src/commands/issue/list.ts

@@ -354,9 +354,29 @@ async function resolveTargetsFromParsedArg(
 
     case "project-search": {
       // Find project across all orgs
-      const matches = await findProjectsBySlug(parsed.projectSlug);
+      const { projects: matches, orgs } = await findProjectsBySlug(
+        parsed.projectSlug
+      );
 
       if (matches.length === 0) {
+        // Check if the slug matches an organization — common mistake.
+        // Unlike simpler list commands that auto-redirect via orgAllFallback,
+        // issue list has custom per-project query logic (query rewriting,
+        // budget redistribution) that doesn't support org-all mode here.
+        // Throwing with actionable hints is the correct behavior.
+        const isOrg = orgs.some((o) => o.slug === parsed.projectSlug);
+        if (isOrg) {
+          throw new ResolutionError(
+            `'${parsed.projectSlug}'`,
+            "is an organization, not a project",
+            `sentry issue list ${parsed.projectSlug}/`,
+            [
+              `List projects: sentry project list ${parsed.projectSlug}/`,
+              `Specify a project: sentry issue list ${parsed.projectSlug}/<project>`,
+            ]
+          );
+        }
+
         throw new ResolutionError(
           `Project '${parsed.projectSlug}'`,
           "not found",

src/commands/issue/utils.ts

@@ -140,7 +140,7 @@ async function resolveProjectSearch(
   }
 
   // 2. Search for project across all accessible orgs
-  const projects = await findProjectsBySlug(projectSlug.toLowerCase());
+  const { projects } = await findProjectsBySlug(projectSlug.toLowerCase());
 
   if (projects.length === 0) {
     throw new ResolutionError(

src/commands/log/view.ts

@@ -9,6 +9,7 @@ import { isatty } from "node:tty";
 import type { SentryContext } from "../../context.js";
 import { getLogs } from "../../lib/api-client.js";
 import {
+  looksLikeIssueShortId,
   parseOrgProjectArg,
   parseSlashSeparatedArg,
 } from "../../lib/arg-parsing.js";
@@ -73,6 +74,8 @@ function splitLogIds(arg: string): string[] {
 export function parsePositionalArgs(args: string[]): {
   logIds: string[];
   targetArg: string | undefined;
+  /** Suggestion when first arg looks like an issue short ID */
+  suggestion?: string;
 } {
   if (args.length === 0) {
     throw new ContextError("Log ID", USAGE_HINT);
@@ -105,7 +108,15 @@ export function parsePositionalArgs(args: string[]): {
   if (logIds.length === 0) {
     throw new ContextError("Log ID", USAGE_HINT);
   }
-  return { logIds, targetArg: first };
+  // Swap detection is not useful here: validateHexId above rejects non-hex
+  // log IDs (which include any containing "/"), so detectSwappedViewArgs
+  // (which checks for "/" in the second arg) can never trigger.
+  // We still check for issue short IDs in the first (target) position.
+  const suggestion = looksLikeIssueShortId(first)
+    ? `Did you mean: sentry issue view ${first}`
+    : undefined;
+
+  return { logIds, targetArg: first, suggestion };
 }
 
 /**
@@ -331,10 +342,17 @@ export const viewCommand = buildCommand({
     ...args: string[]
   ): Promise<void> {
     const { stdout, cwd, setContext } = this;
+    const cmdLog = logger.withTag("log.view");
 
     // Parse positional args
-    const { logIds, targetArg } = parsePositionalArgs(args);
+    const { logIds, targetArg, suggestion } = parsePositionalArgs(args);
+    if (suggestion) {
+      cmdLog.warn(suggestion);
+    }
     const parsed = parseOrgProjectArg(targetArg);
+    if (parsed.type !== "auto-detect" && parsed.normalized) {
+      cmdLog.warn("Normalized slug (Sentry slugs use dashes, not underscores)");
+    }
 
     const target = await resolveTarget(parsed, logIds, cwd);
 

src/commands/project/list.ts

@@ -485,7 +485,7 @@ export async function handleProjectSearch(
   projectSlug: string,
   flags: ListFlags
 ): Promise<void> {
-  const projects: ProjectWithOrg[] = await findProjectsBySlug(projectSlug);
+  const { projects } = await findProjectsBySlug(projectSlug);
   const filtered = filterByPlatform(projects, flags.platform);
 
   if (filtered.length === 0) {

src/commands/project/view.ts

@@ -230,8 +230,7 @@ export const viewCommand = buildCommand({
         const resolved = await resolveProjectBySlug(
           parsed.projectSlug,
           USAGE_HINT,
-          `sentry project view <org>/${parsed.projectSlug}`,
-          this.stderr
+          `sentry project view <org>/${parsed.projectSlug}`
         );
         resolvedTargets = [
           {

src/commands/trace/view.ts

@@ -7,6 +7,8 @@
 import type { SentryContext } from "../../context.js";
 import { getDetailedTrace } from "../../lib/api-client.js";
 import {
+  detectSwappedViewArgs,
+  looksLikeIssueShortId,
   parseOrgProjectArg,
   parseSlashSeparatedArg,
   spansFlag,
@@ -21,6 +23,7 @@ import {
   writeFooter,
   writeJson,
 } from "../../lib/formatters/index.js";
+import { logger } from "../../lib/logger.js";
 import {
   resolveOrgAndProject,
   resolveProjectBySlug,
@@ -48,6 +51,10 @@ const USAGE_HINT = "sentry trace view <org>/<project> <trace-id>";
 export function parsePositionalArgs(args: string[]): {
   traceId: string;
   targetArg: string | undefined;
+  /** Warning message if arguments appear to be in the wrong order */
+  warning?: string;
+  /** Suggestion when first arg looks like an issue short ID */
+  suggestion?: string;
 } {
   if (args.length === 0) {
     throw new ContextError("Trace ID", USAGE_HINT);
@@ -72,8 +79,19 @@ export function parsePositionalArgs(args: string[]): {
     return { traceId: first, targetArg: undefined };
   }
 
+  // Detect swapped args: user put ID first and target second
+  const swapWarning = detectSwappedViewArgs(first, second);
+  if (swapWarning) {
+    return { traceId: first, targetArg: second, warning: swapWarning };
+  }
+
+  // Detect issue short ID passed as first arg (e.g., "CAM-82X some-trace-id")
+  const suggestion = looksLikeIssueShortId(first)
+    ? `Did you mean: sentry issue view ${first}`
+    : undefined;
+
   // Two or more args - first is target, second is trace ID
-  return { traceId: second, targetArg: first };
+  return { traceId: second, targetArg: first, suggestion };
 }
 
 /**
@@ -151,10 +169,21 @@ export const viewCommand = buildCommand({
     ...args: string[]
   ): Promise<void> {
     const { stdout, cwd, setContext } = this;
+    const log = logger.withTag("trace.view");
 
     // Parse positional args
-    const { traceId, targetArg } = parsePositionalArgs(args);
+    const { traceId, targetArg, warning, suggestion } =
+      parsePositionalArgs(args);
+    if (warning) {
+      log.warn(warning);
+    }
+    if (suggestion) {
+      log.warn(suggestion);
+    }
     const parsed = parseOrgProjectArg(targetArg);
+    if (parsed.type !== "auto-detect" && parsed.normalized) {
+      log.warn("Normalized slug (Sentry slugs use dashes, not underscores)");
+    }
 
     let target: ResolvedTraceTarget | null = null;
 
@@ -170,8 +199,7 @@ export const viewCommand = buildCommand({
         target = await resolveProjectBySlug(
           parsed.projectSlug,
           USAGE_HINT,
-          `sentry trace view <org>/${parsed.projectSlug} ${traceId}`,
-          this.stderr
+          `sentry trace view <org>/${parsed.projectSlug} ${traceId}`
         );
         break;