@rudderhq/cli 0.3.6-canary.1 → 0.3.6-canary.2

package/dist/index.js

@@ -8423,7 +8423,7 @@ function formatAgentCliCapabilitiesHumanReadable(capabilities = getAgentCliCapab
 function formatExamplesAndCautions(notes) {
   const sections = [];
   if (notes.examples?.length) {
-    sections.push(["Examples:", ...notes.examples.map((example) => `  ${example}`)].join("\n"));
+    sections.push(["Examples:", ...notes.examples.map(formatHelpExample)].join("\n"));
   }
   if (notes.cautions?.length) {
     sections.push(["Cautions:", ...notes.cautions.map((caution) => `  - ${caution}`)].join("\n"));
@@ -8431,6 +8431,13 @@ function formatExamplesAndCautions(notes) {
   return sections.length > 0 ? `
 ${sections.join("\n\n")}` : "";
 }
+function formatHelpExample(example) {
+  if (typeof example === "string") {
+    return `  ${example}`;
+  }
+  return `  ${example.description}
+    ${example.command}`;
+}
 
 // src/commands/client/agent.ts
 var __moduleDir = path10.dirname(fileURLToPath3(import.meta.url));
@@ -8750,8 +8757,14 @@ function registerAgentCommands(program) {
   addCommonClientOptions(
     skills.command("enable").description(getAgentCliCapabilityById("agent.skills.enable").description).argument("<agentId>", "Agent ID").argument("<selectionRefs...>", "Skill selection refs to enable").addHelpText("after", formatExamplesAndCautions({
       examples: [
-        "rudder agent skills enable <agent-id> rudder/rudder local/abc123/custom-skill",
-        "rudder agent skills enable <agent-id> <selection-ref> --json"
+        {
+          description: "Add skills while preserving the agent's existing enabled set:",
+          command: "rudder agent skills enable <agent-id> rudder/rudder local/abc123/custom-skill"
+        },
+        {
+          description: "Enable one newly created private skill and inspect the resulting snapshot:",
+          command: "rudder agent skills enable <agent-id> <selection-ref> --json"
+        }
       ],
       cautions: [
         "This is additive and preserves existing enabled optional skills.",
@@ -8775,8 +8788,14 @@ function registerAgentCommands(program) {
       "Comma-separated desired skill refs (for example rudder/rudder)"
     ).addHelpText("after", formatExamplesAndCautions({
       examples: [
-        'rudder agent skills sync <agent-id> --desired-skills "rudder/rudder,local/abc123/custom-skill"',
-        'rudder agent skills sync <agent-id> --desired-skills "" --json'
+        {
+          description: "Replace the optional enabled set with an explicitly preserved CSV:",
+          command: 'rudder agent skills sync <agent-id> --desired-skills "rudder/rudder,local/abc123/custom-skill"'
+        },
+        {
+          description: "Clear optional skills only when that is the intended final state:",
+          command: 'rudder agent skills sync <agent-id> --desired-skills "" --json'
+        }
       ],
       cautions: [
         "Sync replaces the full optional enabled-skill set; use enable for additive changes.",
@@ -9073,8 +9092,14 @@ function registerApprovalCommands(program) {
   addCommonClientOptions(
     approval.command("approve").description("Approve an approval request").argument("<approvalId>", "Approval ID").option("--decision-note <text>", "Decision note").option("--decided-by-user-id <id>", "Decision actor user ID").addHelpText("after", formatExamplesAndCautions({
       examples: [
-        "rudder approval get <approval-id> --json",
-        'rudder approval approve <approval-id> --decision-note "Approved after reviewing linked issues" --json'
+        {
+          description: "Read the approval payload before deciding:",
+          command: "rudder approval get <approval-id> --json"
+        },
+        {
+          description: "Record the durable approval decision with concise context:",
+          command: 'rudder approval approve <approval-id> --decision-note "Approved after reviewing linked issues" --json'
+        }
       ],
       cautions: [
         "Read the approval and linked issues before approving; this is a governed mutation.",
@@ -9141,8 +9166,14 @@ function registerApprovalCommands(program) {
   addCommonClientOptions(
     approval.command("comment").description(getAgentCliCapabilityById("approval.comment").description).argument("<approvalId>", "Approval ID").option("--body-file <path>", "Read comment body from a file, or '-' for stdin").addHelpText("after", formatExamplesAndCautions({
       examples: [
-        "rudder approval comment <approval-id> --body-file ./approval-note.md --json",
-        "printf '%s\\n' 'Need one more linked issue checked.' | rudder approval comment <approval-id> --body-file -"
+        {
+          description: "Add a longer Markdown discussion note without deciding:",
+          command: "rudder approval comment <approval-id> --body-file ./approval-note.md --json"
+        },
+        {
+          description: "Ask a short follow-up from stdin:",
+          command: "printf '%s\\n' 'Need one more linked issue checked.' | rudder approval comment <approval-id> --body-file -"
+        }
       ],
       cautions: [
         "Comments do not approve or reject; use approve/reject/request-revision for the durable decision.",
@@ -9442,8 +9473,14 @@ function registerAutomationCommands(program) {
   addCommonClientOptions(
     automation.command("run").description(getAgentCliCapabilityById("automation.run").description).argument("<automationId>", "Automation ID").option("--trigger-id <id>", "Trigger ID").option("--payload <json>", "Manual run payload JSON").option("--idempotency-key <key>", "Idempotency key").option("--source <source>", "Run source", "manual").addHelpText("after", formatExamplesAndCautions({
       examples: [
-        `rudder automation run <automation-id> --payload '{"manual":true}' --json`,
-        "rudder automation run <automation-id> --trigger-id <trigger-id> --idempotency-key zst-123-smoke"
+        {
+          description: "Run a verified automation manually with an explicit payload:",
+          command: `rudder automation run <automation-id> --payload '{"manual":true}' --json`
+        },
+        {
+          description: "Retry a trigger-specific smoke run with duplicate protection:",
+          command: "rudder automation run <automation-id> --trigger-id <trigger-id> --idempotency-key zst-123-smoke"
+        }
       ],
       cautions: [
         "Confirm the automation and trigger target before running; manual runs can create tracked issues or chats.",
@@ -9641,8 +9678,14 @@ function registerChatCommands(program) {
   addCommonClientOptions(
     chat.command("read").description(getAgentCliCapabilityById("chat.read").description).argument("<chatId>", "Chat conversation ID").option("--include-transcript", "Include assistant transcript entries").option("--include-output", "Alias for --include-transcript").option("--include-outputs", "Alias for --include-transcript").option("--limit <n>", "Maximum recent messages", "20").option("--turn-limit <n>", "Alias for --limit for chat turn snapshots").option("--cursor <cursor>", "Stable message cursor returned in page.nextCursor").option("--max-output-chars <n>", "Maximum transcript output chars for human output", "1200").addHelpText("after", formatExamplesAndCautions({
       examples: [
-        "rudder chat read <chat-id> --turn-limit 20 --include-output",
-        "rudder chat read <chat-id> --cursor <nextCursor> --json"
+        {
+          description: "Read a bounded conversation page with transcript output when needed:",
+          command: "rudder chat read <chat-id> --turn-limit 20 --include-output"
+        },
+        {
+          description: "Continue from a stable cursor in scripts:",
+          command: "rudder chat read <chat-id> --cursor <nextCursor> --json"
+        }
       ],
       cautions: [
         "Read bounded pages first; long chats can include large transcript payloads.",
@@ -9698,8 +9741,14 @@ function registerChatCommands(program) {
   addCommonClientOptions(
     chat.command("send").description(getAgentCliCapabilityById("chat.send").description).argument("<chatId>", "Chat conversation ID").option("--body <text>", "Message body").option("--edit-user-message-id <id>", "Regenerate/edit from a prior user message").addHelpText("after", formatExamplesAndCautions({
       examples: [
-        'rudder chat send <chat-id> --body "Status: validation is running"',
-        "printf '%s\\n' 'Multiline note' | rudder chat send <chat-id>"
+        {
+          description: "Append a short agent-authored status note:",
+          command: 'rudder chat send <chat-id> --body "Status: validation is running"'
+        },
+        {
+          description: "Send a longer or multiline note through stdin:",
+          command: "printf '%s\\n' 'Multiline note' | rudder chat send <chat-id>"
+        }
       ],
       cautions: [
         "chat send accepts --body or stdin; it does not support --body-file.",
@@ -11301,8 +11350,14 @@ function registerIssueCommands(program) {
   addCommonClientOptions(
     issue.command("comment").description(getAgentCliCapabilityById("issue.comment").description).argument("<issueId>", "Issue ID").option("--body-file <path>", "Read comment body from a file, or '-' for stdin").option("--image <path>", "Image file to upload and append to the comment; may be repeated", collectImagePath, []).option("--reopen", "Reopen if issue is done/cancelled").addHelpText("after", formatExamplesAndCautions({
       examples: [
-        "rudder issue comment ZST-123 --body-file ./progress.md --image ./screenshot.png --json",
-        "printf '%s\\n' 'Short status' | rudder issue comment ZST-123 --body-file -"
+        {
+          description: "Progress update with attached screenshot evidence:",
+          command: "rudder issue comment ZST-123 --body-file ./progress.md --image ./screenshot.png --json"
+        },
+        {
+          description: "Short stdin status when a separate file is unnecessary:",
+          command: "printf '%s\\n' 'Short status' | rudder issue comment ZST-123 --body-file -"
+        }
       ],
       cautions: [
         "Use --body-file for multiline Markdown; the old --body option is intentionally rejected.",
@@ -11338,8 +11393,14 @@ function registerIssueCommands(program) {
       "Review decision: approve, request_changes, needs_followup, or blocked"
     ).option("--comment-file <path>", "Read required review comment from a file, or '-' for stdin").addHelpText("after", formatExamplesAndCautions({
       examples: [
-        "rudder issue review ZST-123 --decision request_changes --comment-file ./review.md --json",
-        "rudder issue review ZST-123 --decision approve --comment-file ./review.md"
+        {
+          description: "Return implementation work with durable review feedback:",
+          command: "rudder issue review ZST-123 --decision request_changes --comment-file ./review.md --json"
+        },
+        {
+          description: "Approve after reading the issue evidence and validation:",
+          command: "rudder issue review ZST-123 --decision approve --comment-file ./review.md"
+        }
       ],
       cautions: [
         "Free-form comments are not durable review decisions; use this command for approve/request_changes/etc.",
@@ -11387,8 +11448,14 @@ function registerIssueCommands(program) {
   addCommonClientOptions(
     issue.command("done").description(getAgentCliCapabilityById("issue.done").description).argument("<issueId>", "Issue ID").option("--comment-file <path>", "Read required completion comment from a file, or '-' for stdin").option("--image <path>", "Image file to upload and append to the completion comment; may be repeated", collectImagePath, []).addHelpText("after", formatExamplesAndCautions({
       examples: [
-        "rudder issue done ZST-123 --comment-file ./done.md --image ./screenshot.png --json",
-        "rudder issue done ZST-123 --comment-file - < ./done.md"
+        {
+          description: "Close out with validation summary and visual evidence:",
+          command: "rudder issue done ZST-123 --comment-file ./done.md --image ./screenshot.png --json"
+        },
+        {
+          description: "Read the completion note from stdin in scripts:",
+          command: "rudder issue done ZST-123 --comment-file - < ./done.md"
+        }
       ],
       cautions: [
         "Include validation evidence and commit/push status in the completion comment.",
@@ -11775,8 +11842,14 @@ function registerLibraryCommands(program) {
   addCommonClientOptions(
     file.command("ref").description(getAgentCliCapabilityById("library.file.ref").description).argument("<filePath>", "Library file path").addHelpText("after", formatExamplesAndCautions({
       examples: [
-        "rudder library file ref projects/rudder/proposals/plan.md --json",
-        'rudder library file ref "$RUDDER_PROJECT_LIBRARY_PATH/proposals/plan.md" --json'
+        {
+          description: "Return the renderable Markdown link for a known Library file:",
+          command: "rudder library file ref projects/rudder/proposals/plan.md --json"
+        },
+        {
+          description: "Reference a file under the current project Library path:",
+          command: 'rudder library file ref "$RUDDER_PROJECT_LIBRARY_PATH/proposals/plan.md" --json'
+        }
       ],
       cautions: [
         "Pass the Library-relative path, not an absolute filesystem path.",
@@ -11794,8 +11867,14 @@ function registerLibraryCommands(program) {
   addCommonClientOptions(
     file.command("put").description(getAgentCliCapabilityById("library.file.put").description).argument("<filePath>", "Library file path").option("--body-file <path>", "Read file content from a file, or '-' for stdin").addHelpText("after", formatExamplesAndCautions({
       examples: [
-        "rudder library file put projects/rudder/proposals/plan.md --body-file ./plan.md --json",
-        "printf '%s\\n' '# Plan' | rudder library file put projects/rudder/proposals/plan.md --body-file -"
+        {
+          description: "Upload a durable Markdown artifact from a local file:",
+          command: "rudder library file put projects/rudder/proposals/plan.md --body-file ./plan.md --json"
+        },
+        {
+          description: "Write a small generated artifact from stdin:",
+          command: "printf '%s\\n' '# Plan' | rudder library file put projects/rudder/proposals/plan.md --body-file -"
+        }
       ],
       cautions: [
         "Use --body-file for content; the old --body option is intentionally rejected.",
@@ -12090,8 +12169,14 @@ function registerProjectCommands(program) {
   addCommonClientOptions(
     project.command("create").description(getAgentCliCapabilityById("project.create").description).option("-O, --org-id <id>", "Organization ID").requiredOption("--name <name>", "Project name").option("--description <text>", "Project description").option("--status <status>", "Project status").option("--goal-id <id>", "Primary goal ID").option("--goal-ids <csv>", "Comma-separated goal IDs").option("--lead-agent-id <id>", "Lead agent ID").option("--target-date <date>", "Target date").option("--color <value>", "Project color or supported gradient token").addHelpText("after", formatExamplesAndCautions({
       examples: [
-        'rudder project create --org-id <org-id> --name "Rudder dev" --status in_progress --json',
-        'rudder project create --org-id <org-id> --name "Release" --goal-id <goal-id> --lead-agent-id <agent-id>'
+        {
+          description: "Create a new active workstream after confirming it does not already exist:",
+          command: 'rudder project create --org-id <org-id> --name "Rudder dev" --status in_progress --json'
+        },
+        {
+          description: "Create a project tied to a goal and responsible agent:",
+          command: 'rudder project create --org-id <org-id> --name "Release" --goal-id <goal-id> --lead-agent-id <agent-id>'
+        }
       ],
       cautions: [
         "Project mutations are organization-scoped; pass --org-id when context might be ambiguous.",
@@ -12121,8 +12206,14 @@ function registerProjectCommands(program) {
   addCommonClientOptions(
     project.command("update").description(getAgentCliCapabilityById("project.update").description).argument("<projectIdOrShortname>", "Project ID or shortname").option("-O, --org-id <id>", "Organization ID for shortname resolution").option("--name <name>", "Project name").option("--description <text>", "Project description").option("--status <status>", "Project status").option("--goal-id <id>", "Primary goal ID").option("--goal-ids <csv>", "Comma-separated goal IDs").option("--lead-agent-id <id>", "Lead agent ID").option("--target-date <date>", "Target date").option("--color <value>", "Project color or supported gradient token").option("--archived-at <iso8601|null>", "Set archivedAt timestamp or literal 'null'").addHelpText("after", formatExamplesAndCautions({
       examples: [
-        "rudder project update rudder-dev --org-id <org-id> --status in_progress --json",
-        "rudder project update <project-id> --archived-at null"
+        {
+          description: "Move a known project shortname under the intended org:",
+          command: "rudder project update rudder-dev --org-id <org-id> --status in_progress --json"
+        },
+        {
+          description: "Unarchive a verified project id:",
+          command: "rudder project update <project-id> --archived-at null"
+        }
       ],
       cautions: [
         "Shortname resolution needs the intended organization; include --org-id for cross-org local contexts.",
@@ -12173,8 +12264,14 @@ function registerRunsCommands(program) {
   addCommonClientOptions(
     runs.command("list").description(getAgentCliCapabilityById("runs.list").description).option("-O, --org-id <id>", "Organization ID").option("--updated-after <iso>", "Only runs updated after this timestamp").option("--run-id-prefix <prefix>", "Filter by run ID prefix").option("--agent-id <id>", "Filter by agent ID").option("--status <status>", "Filter by run status").option("--runtime <type>", "Filter by runtime type").option("--issue-id <id>", "Filter by linked issue ID").option("--used-skill <key-or-name>", "Filter by skill actually used during the run").option("--loaded-skill <key-or-name>", "Filter by skill loaded for the run").option("--created-before <iso>", "Only runs created before this timestamp").option("--limit <n>", "Maximum rows", "200").addHelpText("after", formatExamplesAndCautions({
       examples: [
-        "rudder runs list --org-id <org-id> --agent-id <agent-id> --status failed --limit 20",
-        "rudder runs list --org-id <org-id> --issue-id ZST-123 --used-skill release-maintainer --json"
+        {
+          description: "Find recent failures for one agent before opening transcripts:",
+          command: "rudder runs list --org-id <org-id> --agent-id <agent-id> --status failed --limit 20"
+        },
+        {
+          description: "Collect skill-specific evidence for a linked issue:",
+          command: "rudder runs list --org-id <org-id> --issue-id ZST-123 --used-skill release-maintainer --json"
+        }
       ],
       cautions: [
         "Filter first by org, agent, issue, status, skill, or time; do not start by dumping broad run history.",
@@ -12247,8 +12344,14 @@ function registerRunsCommands(program) {
   addCommonClientOptions(
     runs.command("transcript").description(getAgentCliCapabilityById("runs.transcript").description).argument("<runId>", "Run ID or short run ID").option("--errors-only", "Show only error transcript rows").option("--around-error <id>", "Show context around a run error id such as step-12").option("--context-turns <n>", "Turns around --around-error", "1").option("--cursor <cursor>", "Stable transcript cursor returned in page.nextCursor").option("--turn-limit <n>", "Maximum turns to return", "20").option("--chronological", "Show oldest-first instead of default newest-first").option("--narrative", "Use a narrative human layout").option("--max-chars <n>", "Maximum output characters per row", "1200").option("--max-output-chars <n>", "Alias for --max-chars").option("--include-output", "Include row output in compact human transcript rows").option("--include-outputs", "Alias for --include-output").addHelpText("after", formatExamplesAndCautions({
       examples: [
-        "rudder runs transcript <run-id> --around-error step-12 --context-turns 2",
-        "rudder runs transcript <run-id> --chronological --turn-limit 30 --include-output"
+        {
+          description: "Inspect the neighborhood around a failing step:",
+          command: "rudder runs transcript <run-id> --around-error step-12 --context-turns 2"
+        },
+        {
+          description: "Reconstruct a bounded chronological decision trail:",
+          command: "rudder runs transcript <run-id> --chronological --turn-limit 30 --include-output"
+        }
       ],
       cautions: [
         "Human output is compact and clipped by default; use --json only when a script needs the full payload.",
@@ -12275,8 +12378,14 @@ function registerRunsCommands(program) {
   addCommonClientOptions(
     runs.command("errors").description(getAgentCliCapabilityById("runs.errors").description).argument("<runId>", "Run ID or short run ID").option("--max-chars <n>", "Maximum output characters per error", "1200").addHelpText("after", formatExamplesAndCautions({
       examples: [
-        "rudder runs errors <run-id>",
-        "rudder runs errors <run-id> --max-chars 4000 --json"
+        {
+          description: "Start failed-run investigation with error summaries:",
+          command: "rudder runs errors <run-id>"
+        },
+        {
+          description: "Increase clipped error output for scripts or reports:",
+          command: "rudder runs errors <run-id> --max-chars 4000 --json"
+        }
       ],
       cautions: [
         "Start here for failed runs, then follow the transcript context command returned for the relevant step.",
@@ -12579,8 +12688,14 @@ function registerSkillCommands(program) {
   addCommonClientOptions(
     skill.command("file").description(getAgentCliCapabilityById("skill.file").description).argument("<skillId>", "Skill ID").option("-O, --org-id <id>", "Organization ID").option("--path <path>", "Skill package file path", "SKILL.md").addHelpText("after", formatExamplesAndCautions({
       examples: [
-        "rudder skill file <skill-uuid> --path SKILL.md --org-id <org-id>",
-        "rudder skill file <skill-uuid> --path references/usage.md --json"
+        {
+          description: "Read the main skill trigger and workflow instructions:",
+          command: "rudder skill file <skill-uuid> --path SKILL.md --org-id <org-id>"
+        },
+        {
+          description: "Inspect a specific reference file in the skill package:",
+          command: "rudder skill file <skill-uuid> --path references/usage.md --json"
+        }
       ],
       cautions: [
         "Prefer the skill UUID for slashful keys such as local/<hash>/<slug>.",
@@ -12603,8 +12718,14 @@ function registerSkillCommands(program) {
   addCommonClientOptions(
     skill.command("import").description(getAgentCliCapabilityById("skill.import").description).option("-O, --org-id <id>", "Organization ID").requiredOption("--source <source>", "Skill source (local path, URL, or repo ref)").addHelpText("after", formatExamplesAndCautions({
       examples: [
-        "rudder skill import --org-id <org-id> --source /abs/path/to/skill --json",
-        "rudder skill list --org-id <org-id> --json"
+        {
+          description: "Import a durable organization-shared skill package:",
+          command: "rudder skill import --org-id <org-id> --source /abs/path/to/skill --json"
+        },
+        {
+          description: "List imported skills afterward to get stable ids:",
+          command: "rudder skill list --org-id <org-id> --json"
+        }
       ],
       cautions: [
         "Import organization-shared skills from durable shared paths, not disposable agent-private work directories.",