fix(help): document target patterns and trailing-slash significance (#267)

Renames the positional placeholder from `<target>` to `<org/project>` so the
usage line is self-documenting. Adds a prose explanation of trailing-slash
semantics to the fullDescription of every command that uses parseOrgProjectArg,
and improves the --cursor rejection error in dispatchOrgScopedList to include a
contextual suggestion when a bare slug was given.

Author: BYK

src/commands/issue/list.ts

@@ -40,6 +40,7 @@ import {
   LIST_BASE_ALIASES,
   LIST_JSON_FLAG,
   LIST_TARGET_POSITIONAL,
+  targetPatternExplanation,
 } from "../../lib/list-command.js";
 import {
   dispatchOrgScopedList,
@@ -657,11 +658,12 @@ export const listCommand = buildCommand({
     brief: "List issues in a project",
     fullDescription:
       "List issues from Sentry projects.\n\n" +
-      "Target specification:\n" +
+      "Target patterns:\n" +
       "  sentry issue list               # auto-detect from DSN or config\n" +
       "  sentry issue list <org>/<proj>  # explicit org and project\n" +
-      "  sentry issue list <org>/        # all projects in org\n" +
+      "  sentry issue list <org>/        # all projects in org (trailing / required)\n" +
       "  sentry issue list <project>     # find project across all orgs\n\n" +
+      `${targetPatternExplanation()}\n\n` +
       "In monorepos with multiple Sentry projects, shows issues from all detected projects.",
   },
   parameters: {

src/commands/log/list.ts

@@ -18,6 +18,7 @@ import {
   writeFooter,
   writeJson,
 } from "../../lib/formatters/index.js";
+import { TARGET_PATTERN_NOTE } from "../../lib/list-command.js";
 import { resolveOrgProjectFromArg } from "../../lib/resolve-target.js";
 import { getUpdateNotification } from "../../lib/version-check.js";
 import type { SentryLog, Writer } from "../../types/index.js";
@@ -232,10 +233,11 @@ export const listCommand = buildCommand({
     brief: "List logs from a project",
     fullDescription:
       "List and stream logs from Sentry projects.\n\n" +
-      "Target specification:\n" +
+      "Target patterns:\n" +
       "  sentry log list               # auto-detect from DSN or config\n" +
       "  sentry log list <org>/<proj>  # explicit org and project\n" +
       "  sentry log list <project>     # find project across all orgs\n\n" +
+      `${TARGET_PATTERN_NOTE}\n\n` +
       "Examples:\n" +
       "  sentry log list                    # List last 100 logs\n" +
       "  sentry log list -f                 # Stream logs (2s poll interval)\n" +
@@ -248,8 +250,8 @@ export const listCommand = buildCommand({
       kind: "tuple",
       parameters: [
         {
-          placeholder: "target",
-          brief: "Target: <org>/<project> or <project>",
+          placeholder: "org/project",
+          brief: "<org>/<project> or <project> (search)",
           parse: String,
           optional: true,
         },

src/commands/project/list.ts

@@ -44,6 +44,7 @@ import {
   LIST_CURSOR_FLAG,
   LIST_JSON_FLAG,
   LIST_TARGET_POSITIONAL,
+  targetPatternExplanation,
 } from "../../lib/list-command.js";
 import {
   dispatchOrgScopedList,
@@ -607,13 +608,14 @@ export const listCommand = buildCommand({
     brief: "List projects",
     fullDescription:
       "List projects in an organization.\n\n" +
-      "Target specification:\n" +
+      "Target patterns:\n" +
       "  sentry project list                # auto-detect from DSN or config\n" +
-      "  sentry project list <org>/         # list all projects in org (paginated)\n" +
+      "  sentry project list <org>/         # all projects in org (paginated)\n" +
       "  sentry project list <org>/<proj>   # show specific project\n" +
       "  sentry project list <project>      # find project across all orgs\n\n" +
+      `${targetPatternExplanation("Cursor pagination (--cursor) requires the <org>/ form.")}\n\n` +
       "Pagination:\n" +
-      "  sentry project list <org>/ -c last  # continue from last page\n" +
+      "  sentry project list <org>/ -c last      # continue from last page\n" +
       "  sentry project list <org>/ -c <cursor>  # resume at specific cursor\n\n" +
       "Filtering and output:\n" +
       "  sentry project list --platform javascript  # filter by platform\n" +

src/commands/project/view.ts

@@ -20,6 +20,7 @@ import {
   writeJson,
   writeOutput,
 } from "../../lib/formatters/index.js";
+import { TARGET_PATTERN_NOTE } from "../../lib/list-command.js";
 import {
   type ResolvedTarget,
   resolveAllTargets,
@@ -201,19 +202,20 @@ export const viewCommand = buildCommand({
     brief: "View details of a project",
     fullDescription:
       "View detailed information about Sentry projects.\n\n" +
-      "Target specification:\n" +
+      "Target patterns:\n" +
       "  sentry project view                       # auto-detect from DSN or config\n" +
       "  sentry project view <org>/<project>       # explicit org and project\n" +
       "  sentry project view <project>             # find project across all orgs\n\n" +
+      `${TARGET_PATTERN_NOTE}\n\n` +
       "In monorepos with multiple Sentry projects, shows details for all detected projects.",
   },
   parameters: {
     positional: {
       kind: "tuple",
       parameters: [
         {
-          placeholder: "target",
-          brief: "Target: <org>/<project>, <project>, or omit for auto-detect",
+          placeholder: "org/project",
+          brief: "<org>/<project>, <project> (search), or omit for auto-detect",
           parse: String,
           optional: true,
         },

src/commands/trace/list.ts

@@ -14,6 +14,7 @@ import {
   writeFooter,
   writeJson,
 } from "../../lib/formatters/index.js";
+import { TARGET_PATTERN_NOTE } from "../../lib/list-command.js";
 import { resolveOrgProjectFromArg } from "../../lib/resolve-target.js";
 
 type ListFlags = {
@@ -67,10 +68,11 @@ export const listCommand = buildCommand({
     brief: "List recent traces in a project",
     fullDescription:
       "List recent traces from Sentry projects.\n\n" +
-      "Target specification:\n" +
+      "Target patterns:\n" +
       "  sentry trace list               # auto-detect from DSN or config\n" +
       "  sentry trace list <org>/<proj>  # explicit org and project\n" +
       "  sentry trace list <project>     # find project across all orgs\n\n" +
+      `${TARGET_PATTERN_NOTE}\n\n` +
       "Examples:\n" +
       "  sentry trace list                     # List last 10 traces\n" +
       "  sentry trace list --limit 50          # Show more traces\n" +
@@ -82,8 +84,8 @@ export const listCommand = buildCommand({
       kind: "tuple",
       parameters: [
         {
-          placeholder: "target",
-          brief: "Target: <org>/<project> or <project>",
+          placeholder: "org/project",
+          brief: "<org>/<project> or <project> (search)",
           parse: String,
           optional: true,
         },

src/lib/list-command.ts

@@ -24,23 +24,49 @@ import { dispatchOrgScopedList, type OrgListConfig } from "./org-list.js";
 // ---------------------------------------------------------------------------
 
 /**
- * Positional `target` parameter shared by all list commands.
+ * Positional `org/project` parameter shared by all list commands.
  *
- * Accepts `<org>/`, `<org>/<project>`, or bare `<org>` / `<project>`.
+ * Accepts `<org>/`, `<org>/<project>`, or bare `<project>` (search).
  * Marked optional so the command falls back to auto-detection when omitted.
  */
 export const LIST_TARGET_POSITIONAL = {
   kind: "tuple" as const,
   parameters: [
     {
-      placeholder: "target",
-      brief: "Target: <org>/, <org>/<project>, or <org>",
+      placeholder: "org/project",
+      brief: "<org>/ (all projects), <org>/<project>, or <project> (search)",
       parse: String,
       optional: true as const,
     },
   ],
 };
 
+/**
+ * Short note for commands that accept a bare project name but do not support
+ * org-all mode (e.g. trace list, log list, project view).
+ *
+ * Explains that a bare name triggers project-search, not org-scoped listing.
+ */
+export const TARGET_PATTERN_NOTE =
+  "A bare name (no slash) is treated as a project search. " +
+  "Use <org>/<project> for an explicit target.";
+
+/**
+ * Full explanation of trailing-slash semantics for commands that support all
+ * four target modes including org-all (e.g. issue list, project list).
+ *
+ * @param cursorNote - Optional sentence appended when the command supports
+ *   cursor pagination (e.g. "Cursor pagination (--cursor) requires the <org>/ form.").
+ */
+export function targetPatternExplanation(cursorNote?: string): string {
+  const base =
+    "The trailing slash on <org>/ is significant — without it, the argument " +
+    "is treated as a project name search (e.g., 'sentry' searches for a " +
+    "project named 'sentry', while 'sentry/' lists all projects in the " +
+    "'sentry' org).";
+  return cursorNote ? `${base} ${cursorNote}` : base;
+}
+
 /**
  * The `--json` flag shared by all list commands.
  * Outputs machine-readable JSON instead of a human-readable table.

src/lib/org-list.ts

@@ -739,10 +739,15 @@ export async function dispatchOrgScopedList<TEntity, TWithOrg>(
 
   // Cursor pagination is only supported in org-all mode
   if (flags.cursor && parsed.type !== "org-all") {
+    const hint =
+      parsed.type === "project-search"
+        ? `\n\nDid you mean '${config.commandPrefix} ${parsed.projectSlug}/'? ` +
+          `A bare name searches for a project — add a trailing slash to list an org's ${config.entityPlural}.`
+        : "";
     throw new ValidationError(
-      `The --cursor flag is only supported when listing ${config.entityPlural} for a specific organization ` +
-        `(e.g., ${config.commandPrefix} <org>/). ` +
-        `Use '${config.commandPrefix} <org>/' for paginated results.`,
+      "The --cursor flag requires the <org>/ pattern " +
+        `(e.g., ${config.commandPrefix} my-org/).` +
+        hint,
       "cursor"
     );
   }

test/lib/list-command.test.ts

@@ -29,7 +29,7 @@ describe("LIST_TARGET_POSITIONAL", () => {
     expect(LIST_TARGET_POSITIONAL.kind).toBe("tuple");
     expect(LIST_TARGET_POSITIONAL.parameters).toHaveLength(1);
     const param = LIST_TARGET_POSITIONAL.parameters[0];
-    expect(param.placeholder).toBe("target");
+    expect(param.placeholder).toBe("org/project");
     expect(param.optional).toBe(true);
     expect(param.parse).toBe(String);
   });

test/lib/org-list.test.ts

@@ -686,7 +686,7 @@ describe("dispatchOrgScopedList", () => {
       expect.unreachable("should have thrown");
     } catch (e) {
       expect(e).toBeInstanceOf(ValidationError);
-      expect((e as ValidationError).message).toContain("widgets");
+      expect((e as ValidationError).message).toContain("<org>/");
     }
   });