@vm0/cli 9.86.4 → 9.86.5

package/index.js

@@ -60,7 +60,7 @@ import {
   showNextSteps,
   volumeConfigSchema,
   withErrorHandler
-} from "./chunk-O22JKC6F.js";
+} from "./chunk-CHFMXDPQ.js";
 
 // src/index.ts
 import { Command as Command44 } from "commander";
@@ -445,7 +445,7 @@ function getConfigPath() {
   return join(homedir(), ".vm0", "config.json");
 }
 var infoCommand = new Command6().name("info").description("Display environment and debug information").action(async () => {
-  console.log(chalk3.bold(`VM0 CLI v${"9.86.4"}`));
+  console.log(chalk3.bold(`VM0 CLI v${"9.86.5"}`));
   console.log();
   const config = await loadConfig();
   const hasEnvToken = !!process.env.VM0_TOKEN;
@@ -1549,7 +1549,7 @@ var composeCommand = new Command7().name("compose").description("Create or updat
         options.autoUpdate = false;
       }
       if (options.autoUpdate !== false) {
-        await startSilentUpgrade("9.86.4");
+        await startSilentUpgrade("9.86.5");
       }
       try {
         let result;
@@ -1623,7 +1623,7 @@ var mainRunCommand = new Command8().name("run").description("Run an agent").argu
   withErrorHandler(
     async (identifier, prompt, options) => {
       if (options.autoUpdate !== false) {
-        await startSilentUpgrade("9.86.4");
+        await startSilentUpgrade("9.86.5");
       }
       const { org, name, version } = parseIdentifier(identifier);
       let composeId;
@@ -3379,7 +3379,7 @@ var cookAction = new Command35().name("cook").description("Quick start: prepare,
   withErrorHandler(
     async (prompt, options) => {
       if (options.autoUpdate !== false) {
-        const shouldExit = await checkAndUpgrade("9.86.4", prompt);
+        const shouldExit = await checkAndUpgrade("9.86.5", prompt);
         if (shouldExit) {
           process.exit(0);
         }
@@ -4119,13 +4119,13 @@ var upgradeCommand = new Command42().name("upgrade").description("Upgrade vm0 CL
     if (latestVersion === null) {
       throw new Error("Could not check for updates. Please try again later.");
     }
-    if (latestVersion === "9.86.4") {
-      console.log(chalk33.green(`\u2713 Already up to date (${"9.86.4"})`));
+    if (latestVersion === "9.86.5") {
+      console.log(chalk33.green(`\u2713 Already up to date (${"9.86.5"})`));
       return;
     }
     console.log(
       chalk33.yellow(
-        `Current version: ${"9.86.4"} -> Latest version: ${latestVersion}`
+        `Current version: ${"9.86.5"} -> Latest version: ${latestVersion}`
       )
     );
     console.log();
@@ -4152,7 +4152,7 @@ var upgradeCommand = new Command42().name("upgrade").description("Upgrade vm0 CL
     const success = await performUpgrade(packageManager);
     if (success) {
       console.log(
-        chalk33.green(`\u2713 Upgraded from ${"9.86.4"} to ${latestVersion}`)
+        chalk33.green(`\u2713 Upgraded from ${"9.86.5"} to ${latestVersion}`)
       );
       return;
     }
@@ -4220,7 +4220,7 @@ var whoamiCommand = new Command43().name("whoami").description("Show current ide
 
 // src/index.ts
 var program = new Command44();
-program.name("vm0").description("VM0 CLI - Build and run agents with natural language").version("9.86.4");
+program.name("vm0").description("VM0 CLI - Build and run agents with natural language").version("9.86.5");
 program.addCommand(authCommand);
 program.addCommand(infoCommand);
 program.addCommand(composeCommand);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vm0/cli",
-  "version": "9.86.4",
+  "version": "9.86.5",
   "description": "CLI application",
   "repository": {
     "type": "git",

package/zero.js

@@ -91,7 +91,7 @@ import {
   updateZeroUserPreferences,
   upsertZeroOrgModelProvider,
   withErrorHandler
-} from "./chunk-O22JKC6F.js";
+} from "./chunk-CHFMXDPQ.js";
 
 // src/zero.ts
 import { Command as Command61 } from "commander";
@@ -1074,7 +1074,14 @@ var createCommand = new Command24().name("create").description("Create a new zer
 ).option("--display-name <name>", "Agent display name").option("--description <text>", "Agent description").option(
   "--sound <tone>",
   "Agent tone: professional, friendly, direct, supportive"
-).option("--instructions-file <path>", "Path to instructions file").action(
+).option("--instructions-file <path>", "Path to instructions file").addHelpText(
+  "after",
+  `
+Examples:
+  Minimal:               zero agent create --connectors github
+  With display name:     zero agent create --connectors github,linear --display-name "My Agent"
+  With instructions:     zero agent create --connectors github --instructions-file ./instructions.md`
+).action(
   withErrorHandler(
     async (options) => {
       const connectors = options.connectors.split(",").map((s) => s.trim());
@@ -1108,7 +1115,19 @@ var editCommand = new Command25().name("edit").description("Edit a zero agent").
 ).option("--display-name <name>", "New display name").option("--description <text>", "New description").option(
   "--sound <tone>",
   "New tone: professional, friendly, direct, supportive"
-).option("--instructions-file <path>", "Path to new instructions file").action(
+).option("--instructions-file <path>", "Path to new instructions file").addHelpText(
+  "after",
+  `
+Examples:
+  Update description:      zero agent edit <agent-id> --description "new role"
+  Update tone:             zero agent edit <agent-id> --sound friendly
+  Update instructions:     zero agent edit <agent-id> --instructions-file ./instructions.md
+  Update yourself:         zero agent edit $ZERO_AGENT_ID --description "new role"
+
+Notes:
+  - At least one option is required
+  - Unspecified fields are preserved (not cleared)`
+).action(
   withErrorHandler(
     async (agentId, options) => {
       const hasAgentUpdate = options.connectors !== void 0 || options.displayName !== void 0 || options.description !== void 0 || options.sound !== void 0;
@@ -1139,7 +1158,14 @@ var editCommand = new Command25().name("edit").description("Edit a zero agent").
 // src/commands/zero/agent/view.ts
 import { Command as Command26 } from "commander";
 import chalk23 from "chalk";
-var viewCommand = new Command26().name("view").description("View a zero agent").argument("<agent-id>", "Agent ID").option("--instructions", "Also show instructions content").action(
+var viewCommand = new Command26().name("view").description("View a zero agent").argument("<agent-id>", "Agent ID").option("--instructions", "Also show instructions content").addHelpText(
+  "after",
+  `
+Examples:
+  View basic info:         zero agent view <agent-id>
+  Include instructions:    zero agent view <agent-id> --instructions
+  View yourself:           zero agent view $ZERO_AGENT_ID --instructions`
+).action(
   withErrorHandler(
     async (agentId, options) => {
       const agent = await getZeroAgent(agentId);
@@ -1168,7 +1194,15 @@ var viewCommand = new Command26().name("view").description("View a zero agent").
 // src/commands/zero/agent/list.ts
 import { Command as Command27 } from "commander";
 import chalk24 from "chalk";
-var listCommand5 = new Command27().name("list").alias("ls").description("List all zero agents").action(
+var listCommand5 = new Command27().name("list").alias("ls").description("List all zero agents").addHelpText(
+  "after",
+  `
+Examples:
+  zero agent list
+
+Notes:
+  - Use this to discover teammate agent IDs before delegating with "zero run"`
+).action(
   withErrorHandler(async () => {
     const agents = await listZeroAgents();
     if (agents.length === 0) {
@@ -1205,7 +1239,16 @@ var listCommand5 = new Command27().name("list").alias("ls").description("List al
 // src/commands/zero/agent/delete.ts
 import { Command as Command28 } from "commander";
 import chalk25 from "chalk";
-var deleteCommand2 = new Command28().name("delete").alias("rm").description("Delete a zero agent").argument("<agent-id>", "Agent ID").option("-y, --yes", "Skip confirmation prompt").action(
+var deleteCommand2 = new Command28().name("delete").alias("rm").description("Delete a zero agent").argument("<agent-id>", "Agent ID").option("-y, --yes", "Skip confirmation prompt").addHelpText(
+  "after",
+  `
+Examples:
+  zero agent delete <agent-id>
+  zero agent delete <agent-id> -y
+
+Notes:
+  - Use -y to skip confirmation in non-interactive mode`
+).action(
   withErrorHandler(async (agentId, options) => {
     await getZeroAgent(agentId);
     if (!options.yes) {
@@ -1230,7 +1273,7 @@ var deleteCommand2 = new Command28().name("delete").alias("rm").description("Del
 var zeroAgentCommand = new Command29("agent").description("View or manage zero agents").addCommand(createCommand).addCommand(editCommand).addCommand(viewCommand).addCommand(listCommand5).addCommand(deleteCommand2).addHelpText(
   "after",
   `
-Self-management (inside sandbox):
+Examples:
   Your agent ID is in $ZERO_AGENT_ID (or run: zero whoami)
   View your config:      zero agent view $ZERO_AGENT_ID --instructions
   Update description:    zero agent edit $ZERO_AGENT_ID --description "new role"
@@ -1851,7 +1894,18 @@ import { Command as Command36 } from "commander";
 import { Command as Command35 } from "commander";
 var missingTokenCommand = new Command35().name("missing-token").description(
   "Diagnose a missing token and find the connector that provides it"
-).argument("<token-name>", "The environment variable / token name to look up").action(
+).argument("<token-name>", "The environment variable / token name to look up").addHelpText(
+  "after",
+  `
+Examples:
+  zero doctor missing-token GITHUB_TOKEN
+  zero doctor missing-token LINEAR_API_KEY
+  zero doctor missing-token NOTION_TOKEN
+
+Notes:
+  - Outputs which connector provides the token and a URL for the user to connect it
+  - Use this to guide the user when a required token is not available in the sandbox`
+).action(
   withErrorHandler(async (tokenName) => {
     const connectorType = getConnectorTypeForSecretName(tokenName);
     if (!connectorType) {
@@ -1878,7 +1932,16 @@ var missingTokenCommand = new Command35().name("missing-token").description(
 );
 
 // src/commands/zero/doctor/index.ts
-var zeroDoctorCommand = new Command36().name("doctor").description("Diagnose runtime issues (missing tokens, connectors)").addCommand(missingTokenCommand);
+var zeroDoctorCommand = new Command36().name("doctor").description("Diagnose runtime issues (missing tokens, connectors)").addCommand(missingTokenCommand).addHelpText(
+  "after",
+  `
+Examples:
+  Missing an API key?    zero doctor missing-token GITHUB_TOKEN
+
+Notes:
+  - Use this when your task fails due to a missing environment variable
+  - The doctor will identify which connector provides the token and give the user a link to connect it`
+);
 
 // src/commands/zero/preference/index.ts
 import { Command as Command37 } from "commander";
@@ -2048,7 +2111,18 @@ var mainRunCommand = new Command38().name("run").description("Delegate a task to
 ).option(
   "--model-provider <type>",
   "Override model provider (e.g., anthropic-api-key)"
-).option("--verbose", "Show full tool inputs and outputs").action(
+).option("--verbose", "Show full tool inputs and outputs").addHelpText(
+  "after",
+  `
+Examples:
+  Delegate a task:       zero run <agent-id> "summarize the latest issues"
+  With verbose output:   zero run <agent-id> "fix the bug" --verbose
+
+Notes:
+  - Get agent IDs from "zero agent list"
+  - The command streams events until the delegated run completes
+  - On success, a session ID is printed for follow-up with "zero run continue"`
+).action(
   withErrorHandler(
     async (agentId, prompt, options) => {
       if (!isUUID(agentId)) {
@@ -2090,7 +2164,17 @@ var continueCommand = new Command39().name("continue").description("Continue a p
 ).option(
   "--model-provider <type>",
   "Override model provider (e.g., anthropic-api-key)"
-).option("--verbose", "Show full tool inputs and outputs").action(
+).option("--verbose", "Show full tool inputs and outputs").addHelpText(
+  "after",
+  `
+Examples:
+  zero run continue <session-id> "now deploy it"
+  zero run continue <session-id> "add tests" --verbose
+
+Notes:
+  - The session ID is printed after a successful "zero run" delegation
+  - Continues the same agent session with full prior context`
+).action(
   withErrorHandler(
     async (sessionId, prompt, options) => {
       if (!isUUID(sessionId)) {
@@ -2127,7 +2211,7 @@ mainRunCommand.addCommand(continueCommand);
 mainRunCommand.addHelpText(
   "after",
   `
-Delegation workflow:
+Examples:
   Discover teammates:    zero agent list
   Delegate a task:       zero run <agent-id> "your task"
   Continue delegation:   zero run continue <session-id> "follow up"`
@@ -2569,7 +2653,22 @@ async function handleScheduleEnabling(params) {
     showEnableHint(agentName);
   }
 }
-var setupCommand2 = new Command40().name("setup").description("Create or edit a schedule for a zero agent").argument("<agent-id>", "Agent ID").option("-n, --name <schedule-name>", 'Schedule name (default: "default")').option("-f, --frequency <type>", "Frequency: daily|weekly|monthly|once|loop").option("-t, --time <HH:MM>", "Time to run (24-hour format)").option("-d, --day <day>", "Day of week (mon-sun) or day of month (1-31)").option("-i, --interval <seconds>", "Interval in seconds for loop mode").option("-z, --timezone <tz>", "IANA timezone").option("-p, --prompt <text>", "Prompt to run").option("--artifact-name <name>", "Artifact name", "artifact").option("-e, --enable", "Enable schedule immediately after creation").option("--notify-email", "Enable email notifications (default: true)").option("--no-notify-email", "Disable email notifications").option("--notify-slack", "Enable Slack notifications (default: true)").option("--no-notify-slack", "Disable Slack notifications").action(
+var setupCommand2 = new Command40().name("setup").description("Create or edit a schedule for a zero agent").argument("<agent-id>", "Agent ID").option("-n, --name <schedule-name>", 'Schedule name (default: "default")').option("-f, --frequency <type>", "Frequency: daily|weekly|monthly|once|loop").option("-t, --time <HH:MM>", "Time to run (24-hour format)").option("-d, --day <day>", "Day of week (mon-sun) or day of month (1-31)").option("-i, --interval <seconds>", "Interval in seconds for loop mode").option("-z, --timezone <tz>", "IANA timezone").option("-p, --prompt <text>", "Prompt to run").option("--artifact-name <name>", "Artifact name", "artifact").option("-e, --enable", "Enable schedule immediately after creation").option("--notify-email", "Enable email notifications (default: true)").option("--no-notify-email", "Disable email notifications").option("--notify-slack", "Enable Slack notifications (default: true)").option("--no-notify-slack", "Disable Slack notifications").addHelpText(
+  "after",
+  `
+Examples:
+  Daily at 9am:          zero schedule setup <agent-id> -f daily -t 09:00 -p "run report"
+  Weekly on Monday:      zero schedule setup <agent-id> -f weekly -d mon -t 10:00 -p "weekly sync"
+  Monthly on the 1st:    zero schedule setup <agent-id> -f monthly -d 1 -t 08:00 -p "monthly review"
+  One-time:              zero schedule setup <agent-id> -f once -d 2026-04-01 -t 14:00 -p "one-off task"
+  Loop every 5 minutes:  zero schedule setup <agent-id> -f loop -i 300 -p "poll for updates"
+  Create and enable:     zero schedule setup <agent-id> -f daily -t 09:00 -p "run report" --enable
+
+Notes:
+  - Re-running setup with the same agent updates the existing "default" schedule
+  - Use -n to manage multiple named schedules for the same agent
+  - All flags are required in non-interactive mode; interactive mode prompts for missing values`
+).action(
   withErrorHandler(async (agentIdentifier, options) => {
     const compose = await resolveCompose(agentIdentifier);
     if (!compose) {
@@ -2653,7 +2752,12 @@ var setupCommand2 = new Command40().name("setup").description("Create or edit a
 // src/commands/zero/schedule/list.ts
 import { Command as Command41 } from "commander";
 import chalk34 from "chalk";
-var listCommand7 = new Command41().name("list").alias("ls").description("List all zero schedules").action(
+var listCommand7 = new Command41().name("list").alias("ls").description("List all zero schedules").addHelpText(
+  "after",
+  `
+Examples:
+  zero schedule list`
+).action(
   withErrorHandler(async () => {
     const result = await listZeroSchedules();
     if (result.schedules.length === 0) {
@@ -2764,6 +2868,12 @@ function printTimeSchedule(schedule) {
 var statusCommand3 = new Command42().name("status").description("Show detailed status of a zero schedule").argument("<agent-id>", "Agent ID").option(
   "-n, --name <schedule-name>",
   "Schedule name (required when agent has multiple schedules)"
+).addHelpText(
+  "after",
+  `
+Examples:
+  zero schedule status <agent-id>
+  zero schedule status <agent-id> -n my-schedule`
 ).action(
   withErrorHandler(async (agentName, options) => {
     const schedule = await resolveZeroScheduleByAgent(
@@ -2785,7 +2895,16 @@ import chalk36 from "chalk";
 var deleteCommand3 = new Command43().name("delete").alias("rm").description("Delete a zero schedule").argument("<agent-id>", "Agent ID").option(
   "-n, --name <schedule-name>",
   "Schedule name (required when agent has multiple schedules)"
-).option("-y, --yes", "Skip confirmation prompt").action(
+).option("-y, --yes", "Skip confirmation prompt").addHelpText(
+  "after",
+  `
+Examples:
+  zero schedule delete <agent-id>
+  zero schedule delete <agent-id> -n my-schedule -y
+
+Notes:
+  - Use -y to skip confirmation in non-interactive mode`
+).action(
   withErrorHandler(
     async (agentName, options) => {
       const resolved = await resolveZeroScheduleByAgent(
@@ -2820,6 +2939,12 @@ import chalk37 from "chalk";
 var enableCommand = new Command44().name("enable").description("Enable a zero schedule").argument("<agent-id>", "Agent ID").option(
   "-n, --name <schedule-name>",
   "Schedule name (required when agent has multiple schedules)"
+).addHelpText(
+  "after",
+  `
+Examples:
+  zero schedule enable <agent-id>
+  zero schedule enable <agent-id> -n my-schedule`
 ).action(
   withErrorHandler(async (agentName, options) => {
     const resolved = await resolveZeroScheduleByAgent(
@@ -2840,6 +2965,12 @@ import chalk38 from "chalk";
 var disableCommand = new Command45().name("disable").description("Disable a zero schedule").argument("<agent-id>", "Agent ID").option(
   "-n, --name <schedule-name>",
   "Schedule name (required when agent has multiple schedules)"
+).addHelpText(
+  "after",
+  `
+Examples:
+  zero schedule disable <agent-id>
+  zero schedule disable <agent-id> -n my-schedule`
 ).action(
   withErrorHandler(async (agentName, options) => {
     const resolved = await resolveZeroScheduleByAgent(
@@ -2855,7 +2986,20 @@ var disableCommand = new Command45().name("disable").description("Disable a zero
 );
 
 // src/commands/zero/schedule/index.ts
-var zeroScheduleCommand = new Command46().name("schedule").description("Create or manage recurring scheduled tasks").addCommand(setupCommand2).addCommand(listCommand7).addCommand(statusCommand3).addCommand(deleteCommand3).addCommand(enableCommand).addCommand(disableCommand);
+var zeroScheduleCommand = new Command46().name("schedule").description("Create or manage recurring scheduled tasks").addCommand(setupCommand2).addCommand(listCommand7).addCommand(statusCommand3).addCommand(deleteCommand3).addCommand(enableCommand).addCommand(disableCommand).addHelpText(
+  "after",
+  `
+Examples:
+  Create a daily schedule:   zero schedule setup <agent-id> -f daily -t 09:00 -p "run report"
+  Create a loop schedule:    zero schedule setup <agent-id> -f loop -i 300 -p "poll for updates"
+  Check all schedules:       zero schedule list
+  Pause a schedule:          zero schedule disable <agent-id>
+  Resume a schedule:         zero schedule enable <agent-id>
+
+Notes:
+  - setup is idempotent \u2014 re-running it with the same agent updates the existing schedule
+  - Schedules are created disabled by default; use --enable or enable separately`
+);
 
 // src/commands/zero/secret/index.ts
 import { Command as Command50 } from "commander";
@@ -2999,7 +3143,17 @@ import { Command as Command52 } from "commander";
 import { readFileSync as readFileSync3 } from "fs";
 import { Command as Command51 } from "commander";
 import chalk42 from "chalk";
-var sendCommand = new Command51().name("send").description("Send a message to a Slack channel").requiredOption("-c, --channel <id>", "Channel ID").option("-t, --text <message>", "Message text").option("--thread <ts>", "Thread timestamp for replies").option("--blocks <json>", "Block Kit JSON string").action(
+var sendCommand = new Command51().name("send").description("Send a message to a Slack channel").requiredOption("-c, --channel <id>", "Channel ID").option("-t, --text <message>", "Message text").option("--thread <ts>", "Thread timestamp for replies").option("--blocks <json>", "Block Kit JSON string").addHelpText(
+  "after",
+  `
+Examples:
+  Simple message:        zero slack message send -c C01234 -t "Hello!"
+  Reply in thread:       zero slack message send -c C01234 --thread 1234567890.123456 -t "reply"
+  Rich blocks:           zero slack message send -c C01234 --blocks '[{"type":"section","text":{"type":"mrkdwn","text":"*Bold*"}}]'
+
+Notes:
+  - Either --text or --blocks is required; both can be used together`
+).action(
   withErrorHandler(
     async (options) => {
       let text = options.text;
@@ -3039,10 +3193,21 @@ var sendCommand = new Command51().name("send").description("Send a message to a
 );
 
 // src/commands/zero/slack/message/index.ts
-var zeroSlackMessageCommand = new Command52().name("message").description("Manage Slack messages").addCommand(sendCommand);
+var zeroSlackMessageCommand = new Command52().name("message").description("Manage Slack messages").addCommand(sendCommand).addHelpText(
+  "after",
+  `
+Examples:
+  zero slack message send -c <channel-id> -t "Hello!"`
+);
 
 // src/commands/zero/slack/index.ts
-var zeroSlackCommand = new Command53().name("slack").description("Send messages to Slack channels as the bot").addCommand(zeroSlackMessageCommand);
+var zeroSlackCommand = new Command53().name("slack").description("Send messages to Slack channels as the bot").addCommand(zeroSlackMessageCommand).addHelpText(
+  "after",
+  `
+Examples:
+  Send a message:        zero slack message send -c <channel-id> -t "Hello!"
+  Reply in a thread:     zero slack message send -c <channel-id> --thread <ts> -t "reply"`
+);
 
 // src/commands/zero/variable/index.ts
 import { Command as Command57 } from "commander";
@@ -3175,7 +3340,16 @@ async function showLocalInfo() {
     console.log(`  Active:     ${activeOrg}`);
   }
 }
-var zeroWhoamiCommand = new Command58().name("whoami").description("Show agent identity, run ID, and capabilities").action(
+var zeroWhoamiCommand = new Command58().name("whoami").description("Show agent identity, run ID, and capabilities").addHelpText(
+  "after",
+  `
+Examples:
+  zero whoami
+
+Notes:
+  - Inside sandbox: shows agent ID, run ID, org ID, and granted capabilities
+  - Your agent ID is also available as $ZERO_AGENT_ID`
+).action(
   withErrorHandler(async () => {
     if (isInsideSandbox()) {
       await showSandboxInfo();
@@ -3282,7 +3456,16 @@ Notes:
 );
 
 // src/commands/zero/ask-user/index.ts
-var zeroAskUserCommand = new Command60().name("ask-user").description("Ask the user a question and wait for the answer").addCommand(questionCommand);
+var zeroAskUserCommand = new Command60().name("ask-user").description("Ask the user a question and wait for the answer").addCommand(questionCommand).addHelpText(
+  "after",
+  `
+Examples:
+  zero ask-user question "Deploy to production?" --option "Yes" --option "No"
+
+Notes:
+  - The command blocks until the user responds or the timeout expires (default 300s)
+  - The user's answer is printed to stdout for your consumption`
+);
 
 // src/zero.ts
 var COMMAND_CAPABILITY_MAP = {
@@ -3325,10 +3508,10 @@ function registerZeroCommands(prog, commands) {
 var program = new Command61();
 program.name("zero").description(
   "Zero CLI \u2014 interact with the zero platform from inside the sandbox"
-).version("9.86.4").addHelpText(
+).version("9.86.5").addHelpText(
   "after",
   `
-Common scenarios:
+Examples:
   Missing a token?       zero doctor missing-token <TOKEN_NAME>
   Delegate to teammate?  zero run <agent-id> "your task"
   Send a Slack message?  zero slack message send -c <channel> -t "text"