deepline 0.1.22 → 0.1.24

package/dist/cli/index.mjs

@@ -243,7 +243,7 @@ function saveProjectDeeplineEnvValues(baseUrl, values, startDir = projectEnvStar
 }
 
 // src/version.ts
-var SDK_VERSION = "0.1.22";
+var SDK_VERSION = "0.1.24";
 var SDK_API_CONTRACT = "2026-05-runs-v2";
 
 // ../shared_libs/play-runtime/coordinator-headers.ts
@@ -531,6 +531,19 @@ function sleep(ms) {
 // src/client.ts
 var TERMINAL_PLAY_STATUSES = /* @__PURE__ */ new Set(["completed", "failed", "cancelled"]);
 var INCLUDE_TOOL_METADATA_HEADER = "x-deepline-include-tool-metadata";
+var COMPILE_MANIFEST_RETRY_DELAYS_MS = [250, 1e3];
+function sleep2(ms) {
+  return new Promise((resolve8) => setTimeout(resolve8, ms));
+}
+function isTransientCompileManifestError(error) {
+  if (error instanceof DeeplineError && typeof error.statusCode === "number") {
+    return error.statusCode === 408 || error.statusCode === 425 || error.statusCode === 499 || error.statusCode >= 500 && error.statusCode < 600;
+  }
+  const message = error instanceof Error ? error.message : String(error);
+  return /fetch failed|connection (?:closed|reset|terminated)|socket hang up|econnreset|etimedout|eai_again|abort/i.test(
+    message
+  );
+}
 function isRecord(value) {
   return Boolean(value && typeof value === "object" && !Array.isArray(value));
 }
@@ -936,8 +949,22 @@ var DeeplineClient = class {
     });
   }
   async compilePlayManifest(input) {
-    const response = await this.http.post("/api/v2/plays/compile-manifest", input);
-    return response.compilerManifest;
+    const retryDelays = COMPILE_MANIFEST_RETRY_DELAYS_MS.slice(
+      0,
+      Math.max(0, this.config.maxRetries)
+    );
+    for (let attempt = 0; ; attempt += 1) {
+      try {
+        const response = await this.http.post("/api/v2/plays/compile-manifest", input);
+        return response.compilerManifest;
+      } catch (error) {
+        const delayMs = retryDelays[attempt];
+        if (delayMs === void 0 || !isTransientCompileManifestError(error)) {
+          throw error;
+        }
+        await sleep2(delayMs);
+      }
+    }
   }
   /**
    * Check a bundled play artifact against the server's current play compiler.
@@ -1995,7 +2022,7 @@ function buildCandidateUrls2(url) {
     return [url];
   }
 }
-function sleep2(ms) {
+function sleep3(ms) {
   return new Promise((resolve8) => setTimeout(resolve8, ms));
 }
 function printDeeplineLogo() {
@@ -2078,7 +2105,7 @@ async function handleRegister(args) {
       return EXIT_AUTH;
     }
     if (s >= 500 || s === 0 || s === 400) {
-      await sleep2(2e3);
+      await sleep3(2e3);
       continue;
     }
     if (s >= 400) {
@@ -2102,7 +2129,7 @@ async function handleRegister(args) {
       console.log("That approval link expired. Please run: deepline auth register");
       return EXIT_AUTH;
     }
-    await sleep2(2e3);
+    await sleep3(2e3);
   }
 }
 async function handleWait(args) {
@@ -2139,7 +2166,7 @@ async function handleWait(args) {
       return EXIT_AUTH;
     }
     if (status >= 500 || status === 0 || status === 400) {
-      await sleep2(2e3);
+      await sleep3(2e3);
       continue;
     }
     if (status >= 400) {
@@ -2163,7 +2190,7 @@ async function handleWait(args) {
       console.error("That approval link expired. Run: deepline auth register");
       return EXIT_AUTH;
     }
-    await sleep2(2e3);
+    await sleep3(2e3);
   }
   console.error("Still pending. Approve the browser link, then run: deepline auth wait");
   return EXIT_AUTH;
@@ -2303,18 +2330,48 @@ function registerAuthCommands(program) {
     `
 Common commands:
   deepline auth register
+  deepline auth register --no-wait
+  deepline auth wait --timeout 300
   deepline auth status
   deepline auth status --json
+
+Notes:
+  Registration opens a browser approval page by default. Use --no-wait in CI
+  or agent runs, then finish with deepline auth wait.
+  Auth status shows the target host and active workspace without printing secrets.
 `
   );
-  auth.command("register").description("Register this device and open the approval page in your browser.").option("--org-name <name>", "Workspace name to prefill").option("--agent-name <name>", "Agent name to register").option("--no-wait", "Return immediately after opening the approval page").action(async (options) => {
+  auth.command("register").description("Register this device and open the approval page in your browser.").addHelpText(
+    "after",
+    `
+Notes:
+  Opens a browser approval page and waits for approval unless --no-wait is set.
+  The saved API key is scoped to the selected workspace and host.
+
+Examples:
+  deepline auth register
+  deepline auth register --org-name Acme --agent-name local-cli
+  deepline auth register --no-wait
+`
+  ).option("--org-name <name>", "Workspace name to prefill").option("--agent-name <name>", "Agent name to register").option("--no-wait", "Return immediately after opening the approval page").action(async (options) => {
     process.exitCode = await handleRegister([
       ...options.orgName ? ["--org-name", options.orgName] : [],
       ...options.agentName ? ["--agent-name", options.agentName] : [],
       ...options.noWait || options.wait === false ? ["--no-wait"] : []
     ]);
   });
-  auth.command("wait").description("Wait for a pending browser approval and save the API key.").option("--timeout <seconds>", "Maximum seconds to wait", "300").action(async (options) => {
+  auth.command("wait").description("Wait for a pending browser approval and save the API key.").addHelpText(
+    "after",
+    `
+Notes:
+  Completes a previous deepline auth register --no-wait flow.
+  Saves the approved API key into the host auth file.
+
+Examples:
+  deepline auth wait
+  deepline auth wait --timeout 120
+`
+  ).option("--timeout <seconds>", "Maximum seconds to wait", "300").action(async (options) => {
     process.exitCode = await handleWait([
       ...options.timeout ? ["--timeout", options.timeout] : []
     ]);
@@ -2468,15 +2525,116 @@ async function handleRedeemCode(code, options) {
 `);
 }
 function registerBillingCommands(program) {
-  const billing = program.command("billing").description("Inspect balance, usage, limits, and checkout flows.");
-  billing.command("balance").description("Show current billing balance.").option("--json", "Emit JSON output").action(handleBalance);
-  billing.command("usage").description("Show current usage plus recent calls.").option("--limit <n>", "Recent-call page size").option("--offset <n>", "Recent-call offset").option("--json", "Emit JSON output").action(handleUsage);
-  billing.command("limit").description("Show configured monthly limit state.").option("--json", "Emit JSON output").action(handleLimit);
-  billing.command("set-limit").description("Set monthly credit cap.").argument("<credits>", "Monthly credits limit").option("--json", "Emit JSON output").action(handleSetLimit);
-  billing.command("off").description("Disable monthly credit cap.").option("--json", "Emit JSON output").action(handleLimitOff);
-  billing.command("history").description("Export billing ledger history to CSV.").requiredOption("--time <window>", "Rolling time window: 1d, 1w, 1m, or 1y").option("--json", "Emit JSON output").action(handleHistory);
-  billing.command("checkout").description("Create a checkout session and optionally open it in your browser.").option("--tier <tierId>", "Named pricing tier").option("--credits <credits>", "Custom credit amount").option("--discount-code <code>", "Apply a discount code").option("--no-open", "Print the checkout URL without opening a browser").option("--json", "Emit JSON output").action(handleCheckout);
-  billing.command("redeem-code").description("Redeem a billing code.").requiredOption("--code <code>", "Code to redeem").option("--no-open", "Do not open a browser").option("--json", "Emit JSON output").action(({ code, ...options }) => handleRedeemCode(code, options));
+  const billing = program.command("billing").description("Inspect balance, usage, limits, and checkout flows.").addHelpText(
+    "after",
+    `
+Concepts:
+  Billing commands show Deepline credits, not raw provider spend.
+  set-limit/off mutate the monthly workspace cap. checkout/redeem-code can open
+  a browser unless --no-open is set.
+
+Examples:
+  deepline billing balance --json
+  deepline billing usage --limit 20 --json
+  deepline billing set-limit 500 --json
+  deepline billing checkout --credits 1000 --no-open --json
+`
+  );
+  billing.command("balance").description("Show current billing balance.").addHelpText(
+    "after",
+    `
+Notes:
+  Read-only. Shows the current Deepline credit balance for the active workspace.
+
+Examples:
+  deepline billing balance
+  deepline billing balance --json
+`
+  ).option("--json", "Emit JSON output. Also automatic when stdout is piped").action(handleBalance);
+  billing.command("usage").description("Show current usage plus recent calls.").addHelpText(
+    "after",
+    `
+Notes:
+  Read-only. Shows last-30-day Deepline credit usage plus a bounded recent-call
+  page. Use --limit/--offset to paginate the recent-call section.
+
+Examples:
+  deepline billing usage
+  deepline billing usage --limit 50 --offset 50 --json
+`
+  ).option("--limit <n>", "Recent-call page size").option("--offset <n>", "Recent-call offset").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(handleUsage);
+  billing.command("limit").description("Show configured monthly limit state.").addHelpText(
+    "after",
+    `
+Notes:
+  Read-only. Shows whether the monthly workspace cap is enabled and how many
+  Deepline credits remain before the cap.
+
+Examples:
+  deepline billing limit
+  deepline billing limit --json
+`
+  ).option("--json", "Emit JSON output. Also automatic when stdout is piped").action(handleLimit);
+  billing.command("set-limit").description("Set monthly credit cap.").addHelpText(
+    "after",
+    `
+Notes:
+  Mutates workspace billing settings. The argument is a Deepline credit amount,
+  not dollars and not provider credits.
+
+Examples:
+  deepline billing set-limit 500
+  deepline billing set-limit 500 --json
+`
+  ).argument("<credits>", "Monthly credits limit").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(handleSetLimit);
+  billing.command("off").description("Disable monthly credit cap.").addHelpText(
+    "after",
+    `
+Notes:
+  Mutates workspace billing settings by removing the monthly Deepline credit cap.
+
+Examples:
+  deepline billing off
+  deepline billing off --json
+`
+  ).option("--json", "Emit JSON output. Also automatic when stdout is piped").action(handleLimitOff);
+  billing.command("history").description("Export billing ledger history to CSV.").addHelpText(
+    "after",
+    `
+Notes:
+  Read-only server query that writes a local CSV file. With --json, stdout is a
+  summary containing the output path and row count.
+
+Examples:
+  deepline billing history --time 1m
+  deepline billing history --time 1y --json
+`
+  ).requiredOption("--time <window>", "Rolling time window: 1d, 1w, 1m, or 1y").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(handleHistory);
+  billing.command("checkout").description("Create a checkout session and optionally open it in your browser.").addHelpText(
+    "after",
+    `
+Notes:
+  Creates a payment checkout session. Opens the checkout URL in a browser unless
+  --no-open is set. Use --json for automation.
+
+Examples:
+  deepline billing checkout --tier pro
+  deepline billing checkout --credits 1000 --no-open --json
+  deepline billing checkout --credits 1000 --discount-code LAUNCH --no-open
+`
+  ).option("--tier <tierId>", "Named pricing tier").option("--credits <credits>", "Custom credit amount").option("--discount-code <code>", "Apply a discount code").option("--no-open", "Print the checkout URL without opening a browser").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(handleCheckout);
+  billing.command("redeem-code").description("Redeem a billing code.").addHelpText(
+    "after",
+    `
+Notes:
+  Redeems a workspace billing code and may open a browser for completion unless
+  --no-open is set.
+
+Examples:
+  deepline billing redeem-code --code ABC123
+  deepline billing redeem-code --code ABC123 --no-open --json
+`
+  ).requiredOption("--code <code>", "Code to redeem").option("--no-open", "Do not open a browser").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(({ code, ...options }) => handleRedeemCode(code, options));
 }
 
 // src/cli/dataset-stats.ts
@@ -2907,8 +3065,31 @@ async function handleCsvShow(options) {
 `);
 }
 function registerCsvCommands(program) {
-  const csv = program.command("csv").description("Inspect local CSV files.");
-  csv.command("show").description("Display rows from a CSV file in json, csv, or table form.").requiredOption("--csv <path>", "Input CSV path").option("--format <format>", "Output format: json, csv, or table", "json").option("--rows <range>", "Row range start:end", "0:19").option("--columns <names>", "Comma-separated column names to include").option("--summary", "Print a summary payload instead of row output").option("--verbose", "Do not truncate long values in table output").action(handleCsvShow);
+  const csv = program.command("csv").description("Inspect local CSV files.").addHelpText(
+    "after",
+    `
+Notes:
+  Local-only inspection helpers. These commands do not upload CSV files or call
+  Deepline APIs.
+
+Examples:
+  deepline csv show --csv leads.csv --rows 0:10 --format table
+  deepline csv show --csv leads.csv --summary
+`
+  );
+  csv.command("show").description("Display rows from a CSV file in json, csv, or table form.").addHelpText(
+    "after",
+    `
+Notes:
+  Reads a local CSV path and prints a bounded row range. --rows uses inclusive
+  start:end indexes, so 0:19 prints the first 20 rows. JSON is the default format.
+
+Examples:
+  deepline csv show --csv leads.csv
+  deepline csv show --csv leads.csv --rows 20:39 --columns name,email --format table
+  deepline csv show --csv leads.csv --summary
+`
+  ).requiredOption("--csv <path>", "Input CSV path").option("--format <format>", "Output format: json, csv, or table", "json").option("--rows <range>", "Row range start:end", "0:19").option("--columns <names>", "Comma-separated column names to include").option("--summary", "Print a summary payload instead of row output").option("--verbose", "Do not truncate long values in table output").action(handleCsvShow);
 }
 
 // src/cli/commands/db.ts
@@ -2988,8 +3169,32 @@ async function handleDbQuery(args) {
   return 0;
 }
 function registerDbCommands(program) {
-  const db = program.command("db").alias("customer-db").description("Query the tenant customer database.");
-  db.command("query").alias("psql").description("Run SQL against the tenant customer database.").requiredOption("--sql <sql>", "SQL statement").option("--max-rows <n>", "Maximum returned rows").option("--json", "Emit raw JSON response").action(async (options) => {
+  const db = program.command("db").alias("customer-db").description("Query the tenant customer database.").addHelpText(
+    "after",
+    `
+Notes:
+  Runs SQL against the active workspace customer database through Deepline APIs.
+  Results are bounded by the server and --max-rows. Use --json for stable output.
+
+Examples:
+  deepline db query --sql "select * from companies limit 20"
+  deepline db query --sql "select domain, name from companies limit 20" --json
+  deepline db query --sql "select * from contacts" --max-rows 100 --json
+`
+  );
+  db.command("query").alias("psql").description("Run SQL against the tenant customer database.").addHelpText(
+    "after",
+    `
+Notes:
+  Requires --sql. Output is a compact table in a terminal and raw JSON with
+  --json or when stdout is piped. The active auth workspace determines scope.
+
+Examples:
+  deepline db query --sql "select * from companies limit 20"
+  deepline db query --sql "select domain, name from companies limit 20" --json
+  deepline db psql --sql "select count(*) from contacts" --json
+`
+  ).requiredOption("--sql <sql>", "SQL statement").option("--max-rows <n>", "Maximum returned rows").option("--json", "Emit raw JSON response. Also automatic when stdout is piped").action(async (options) => {
     process.exitCode = await handleDbQuery([
       "--sql",
       options.sql,
@@ -3015,9 +3220,29 @@ async function handleFeedback(text, options) {
   process.stdout.write("Feedback submitted. Thank you.\n");
 }
 function registerFeedbackCommands(program) {
-  const feedback = program.command("feedback").description("Submit CLI feedback to Deepline.");
+  const feedback = program.command("feedback").description("Submit CLI feedback to Deepline.").addHelpText(
+    "after",
+    `
+Notes:
+  Sends the feedback text plus local CLI environment info to Deepline support.
+  Use --command and --payload to attach a reproducible command shape.
+
+Examples:
+  deepline feedback "plays run failed after upload" --command "deepline plays run my.play.ts --watch"
+  deepline feedback "unexpected billing output" --payload '{"command":"billing usage"}' --json
+`
+  );
   feedback.argument("<text>", "Feedback text").option("--command <command>", "Command that reproduced the issue").option("--payload <payload>", "JSON or plain-text payload for the repro").option("--json", "Emit JSON output").action(handleFeedback);
-  program.command("provide-feedback").description("Legacy alias for `deepline feedback`.").argument("<text>", "Feedback text").option("--command <command>", "Command that reproduced the issue").option("--payload <payload>", "JSON or plain-text payload for the repro").option("--json", "Emit JSON output").action(handleFeedback);
+  program.command("provide-feedback").description("Legacy alias for `deepline feedback`.").addHelpText(
+    "after",
+    `
+Notes:
+  Compatibility alias. Prefer deepline feedback in new scripts and docs.
+
+Examples:
+  deepline feedback "tools search returned stale results" --json
+`
+  ).argument("<text>", "Feedback text").option("--command <command>", "Command that reproduced the issue").option("--payload <payload>", "JSON or plain-text payload for the repro").option("--json", "Emit JSON output").action(handleFeedback);
 }
 
 // src/cli/commands/org.ts
@@ -3097,9 +3322,43 @@ async function handleOrgSwitch(selection, options) {
 `);
 }
 function registerOrgCommands(program) {
-  const org = program.command("org").description("List and switch organizations.");
-  org.command("list").description("List your organizations.").option("--json", "Emit JSON output").action(handleOrgList);
-  org.command("switch [selection]").description("Switch to another organization and save the new API key in the host auth file.").option("--org-id <id>", "Switch using an explicit organization id").option("--json", "Emit JSON output").action(handleOrgSwitch);
+  const org = program.command("org").description("List and switch organizations.").addHelpText(
+    "after",
+    `
+Notes:
+  Organizations are workspaces. Switching organizations mutates the saved host
+  auth file so later CLI commands target the selected workspace.
+
+Examples:
+  deepline org list --json
+  deepline org switch 2
+  deepline org switch --org-id org_123 --json
+`
+  );
+  org.command("list").description("List your organizations.").addHelpText(
+    "after",
+    `
+Notes:
+  Read-only. Marks the active organization when the server returns that metadata.
+
+Examples:
+  deepline org list
+  deepline org list --json
+`
+  ).option("--json", "Emit JSON output. Also automatic when stdout is piped").action(handleOrgList);
+  org.command("switch [selection]").description("Switch to another organization and save the new API key in the host auth file.").addHelpText(
+    "after",
+    `
+Notes:
+  Mutates the saved host auth file. Selection can be a list number, exact
+  organization name, or organization id. Without a selection, prints choices.
+
+Examples:
+  deepline org switch
+  deepline org switch 2
+  deepline org switch --org-id org_123 --json
+`
+  ).option("--org-id <id>", "Switch using an explicit organization id").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(handleOrgSwitch);
 }
 
 // src/cli/commands/play.ts
@@ -6045,7 +6304,7 @@ function parsePlayRunOptions(args) {
   let input = null;
   let revisionId = null;
   let revisionSelector = null;
-  const watch = args.includes("--watch");
+  const watch = args.includes("--watch") || args.includes("--wait");
   let jsonOutput = watch ? args.includes("--json") : argsWantJson(args);
   const emitLogs = !jsonOutput || args.includes("--logs");
   const force = args.includes("--force");
@@ -6095,15 +6354,13 @@ function parsePlayRunOptions(args) {
       if (arg === "--watch") {
         continue;
       }
+      if (arg === "--wait") {
+        continue;
+      }
       if (arg === "--json") {
         jsonOutput = true;
         continue;
       }
-      if (arg === "--wait") {
-        throw new Error(
-          "--wait is removed for `plays run`; use `--watch` to stream completion output."
-        );
-      }
       if (arg === "--tail") {
         throw new Error(
           "--tail is removed for `plays run`; use `--watch` to stream completion output."
@@ -7218,12 +7475,15 @@ Concepts:
   Plays are durable cloud workflows.
   Stable ctx.tools.execute({ id, tool, input }) calls are replay-safe.
   ctx.map adds row keys and row progress.
+  Named play runs use the live revision unless --latest or --revision-id is set.
+  Running a local file does not make it live; use set-live/publish explicitly.
 
 Common commands:
   deepline plays search email --json
   deepline plays describe person-linkedin-to-email --json
   deepline plays check my.play.ts
   deepline plays run my.play.ts --input '{"domain":"stripe.com"}' --watch
+  deepline plays set-live my.play.ts --json
   deepline plays get person-linkedin-to-email --json
 `
   );
@@ -7253,9 +7513,11 @@ Notes:
   Unknown --foo and --foo.bar flags are treated as play input args.
   File args accept local paths; the CLI stages files before submit.
   --watch prints logs, previews, stats, and next commands.
+  --wait is accepted as a compatibility alias for --watch.
   The play page opens in your browser as soon as the run starts; use --no-open
   to only print the URL.
   --force supersedes active runs; it does not bypass completed reuse.
+  This command starts cloud work and may spend Deepline credits through tool calls.
 
 Idempotent execution:
   Stable tool call ids are the reuse key:
@@ -7280,6 +7542,7 @@ Idempotent execution:
 
 Examples:
   deepline plays run my.play.ts --input '{"domain":"stripe.com"}' --watch
+  deepline plays run my.play.ts --input @input.json --wait --json
   deepline plays run person-linkedin-to-email --input '{"linkedin_url":"..."}' --watch
   deepline plays run enrich.play.ts --csv leads.csv --watch --out leads-enriched.csv
   deepline plays run cto-search.play.ts --limit 5 --watch
@@ -7291,7 +7554,7 @@ Examples:
   ).option(
     "--out <path>",
     "Write the completed row output to CSV; requires --watch"
-  ).option("--watch", "Stream logs until completion").option(
+  ).option("--watch", "Stream logs until completion").option("--wait", "Alias for --watch; stream logs until completion").option(
     "--logs",
     "When output is non-interactive, stream play logs to stderr while waiting"
   ).option("--tail-timeout-ms <ms>", "Timeout while watching the run stream").option("--force", "Supersede any active runs for this play").option("--no-open", "Print the play page URL without opening a browser").option("--json", "Emit JSON output").action(async (target, options, command) => {
@@ -7314,7 +7577,7 @@ Examples:
       ...options.latest ? ["--latest"] : [],
       ...options.revisionId ? ["--revision-id", options.revisionId] : [],
       ...options.out ? ["--out", options.out] : [],
-      ...options.watch ? ["--watch"] : [],
+      ...options.watch || options.wait ? ["--watch"] : [],
       ...options.logs ? ["--logs"] : [],
       ...options.tailTimeoutMs ? ["--tail-timeout-ms", options.tailTimeoutMs] : [],
       ...options.force ? ["--force"] : [],
@@ -7345,12 +7608,36 @@ Examples:
       ...options.out ? ["--out", options.out] : []
     ]);
   });
-  play.command("list").description("List saved and prebuilt plays.").option("--json", "Emit JSON output").action(async (options) => {
+  play.command("list").description("List saved and prebuilt plays.").addHelpText(
+    "after",
+    `
+Notes:
+  Inventory command for saved org plays and prebuilt plays. Use search for
+  ranked discovery by task or schema.
+
+Examples:
+  deepline plays list
+  deepline plays list --json
+  deepline plays search email --origin prebuilt --json
+`
+  ).option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (options) => {
     process.exitCode = await handlePlayList([
       ...options.json ? ["--json"] : []
     ]);
   });
-  play.command("search <query>").description("Search saved and prebuilt plays.").option("--origin <origin>", "Filter to prebuilt or owned plays").option("--compact", "Emit compact schemas").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (query, options) => {
+  play.command("search <query>").description("Search saved and prebuilt plays.").addHelpText(
+    "after",
+    `
+Notes:
+  Ranked discovery for workflows. Use --origin prebuilt or --origin owned when
+  you need to narrow results. Use describe on a result before running it.
+
+Examples:
+  deepline plays search email
+  deepline plays search "linkedin to email" --origin prebuilt --compact --json
+  deepline plays describe person-linkedin-to-email --json
+`
+  ).option("--origin <origin>", "Filter to prebuilt or owned plays").option("--compact", "Emit compact schemas").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (query, options) => {
     process.exitCode = await handlePlaySearch([
       query,
       ...options.origin ? ["--origin", options.origin] : [],
@@ -7376,13 +7663,53 @@ Examples:
       ...options.json ? ["--json"] : []
     ]);
   });
-  play.command("versions").description("List revisions for a named play.").option("--name <name>", "Saved play name").option("--json", "Emit JSON output").action(async (options) => {
+  play.command("versions").description("List revisions for a named play.").addHelpText(
+    "after",
+    `
+Notes:
+  Shows saved revisions for an org-owned play, including which revision is live
+  when that metadata is available. Named runs use the live revision by default.
+
+Examples:
+  deepline plays versions --name my-play
+  deepline plays versions --name my-play --json
+  deepline plays run my-play --revision-id <revision-id> --watch
+`
+  ).option("--name <name>", "Saved play name").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (options) => {
     process.exitCode = await handlePlayVersions([
       ...options.name ? ["--name", options.name] : [],
       ...options.json ? ["--json"] : []
     ]);
   });
-  play.command("publish <target>").description("Bundle, validate, save, and publish a play.").option("--latest", "Promote the newest saved revision").option("--revision-id <id>", "Revision to promote").option("--json", "Emit JSON output").action(async (target, options) => {
+  const addPublishHelp = (command) => command.addHelpText(
+    "after",
+    `
+Notes:
+  Mutates cloud state. For a local file, this bundles, validates, saves a new
+  revision, and promotes that revision live. For a saved play, --latest or
+  --revision-id promotes an existing saved revision live.
+  Running a local file with plays run does not publish it.
+
+Examples:
+  deepline plays set-live my.play.ts --json
+  deepline plays set-live my-play --latest --json
+  deepline plays set-live my-play --revision-id <revision-id> --json
+  deepline plays publish my.play.ts --json
+`
+  );
+  addPublishHelp(
+    play.command("publish <target>").description("Bundle, validate, save, and promote a play revision live.")
+  ).option("--latest", "Promote the newest saved revision").option("--revision-id <id>", "Revision to promote").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (target, options) => {
+    process.exitCode = await handlePlayPublish([
+      target,
+      ...options.latest ? ["--latest"] : [],
+      ...options.revisionId ? ["--revision-id", options.revisionId] : [],
+      ...options.json ? ["--json"] : []
+    ]);
+  });
+  addPublishHelp(
+    play.command("set-live <target>").description("Promote a local file or saved revision as the live play revision.")
+  ).option("--latest", "Promote the newest saved revision").option("--revision-id <id>", "Revision to promote").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (target, options) => {
     process.exitCode = await handlePlayPublish([
       target,
       ...options.latest ? ["--latest"] : [],
@@ -7390,7 +7717,18 @@ Examples:
       ...options.json ? ["--json"] : []
     ]);
   });
-  play.command("delete <target>").description("Delete an org-owned play and its saved revisions/runs.").option("-y, --yes", "Confirm deletion").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (target, options) => {
+  play.command("delete <target>").description("Delete an org-owned play and its saved revisions/runs.").addHelpText(
+    "after",
+    `
+Notes:
+  Destructive mutation. Deletes an org-owned play plus saved revisions and run
+  records. Prebuilt/read-only plays are refused. Use --yes for noninteractive runs.
+
+Examples:
+  deepline plays delete my-play
+  deepline plays delete my-play --yes --json
+`
+  ).option("-y, --yes", "Confirm deletion").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (target, options) => {
     process.exitCode = await handlePlayDelete([
       target,
       ...options.yes ? ["--yes"] : [],
@@ -7400,6 +7738,12 @@ Examples:
   const runs = program.command("runs").description("Inspect, tail, stop, and export play runs.").addHelpText(
     "after",
     `
+Concepts:
+  A run is one execution instance of a play. It has status, progress, logs,
+  preview output, recovery metadata, and optional full row export.
+  tail reads the live stream. logs fetches persisted logs after the fact.
+  stop mutates cloud state by requesting cancellation.
+
 Examples:
   deepline runs get play/my-play/run/20260501t000000-000 --json
   deepline runs tail play/my-play/run/20260501t000000-000
@@ -7409,14 +7753,36 @@ Examples:
   deepline runs export play/my-play/run/20260501t000000-000 --out output.csv
 `
   );
-  runs.command("get <runId>").description("Get status, progress, outputs, errors, and recovery metadata for a play run.").option("--json", "Emit JSON output. Also automatic when stdout is piped").option("--full", "Debug only: with --json, emit the raw status payload").action(async (runId, options) => {
+  runs.command("get <runId>").description("Get status, progress, outputs, errors, and recovery metadata for a play run.").addHelpText(
+    "after",
+    `
+Notes:
+  Full run status read. Use --full --json when debugging raw stream/status fields.
+
+Examples:
+  deepline runs get play/my-play/run/20260501t000000-000
+  deepline runs get play/my-play/run/20260501t000000-000 --json
+  deepline runs get play/my-play/run/20260501t000000-000 --full --json
+`
+  ).option("--json", "Emit JSON output. Also automatic when stdout is piped").option("--full", "Debug only: with --json, emit the raw status payload").action(async (runId, options) => {
     process.exitCode = await handleRunGet([
       runId,
       ...options.json ? ["--json"] : [],
       ...options.full ? ["--full"] : []
     ]);
   });
-  runs.command("list").description("List play runs.").requiredOption("--play <name>", "Play name to filter runs").option("--status <status>", "Filter by run status").option("--compact", "Drop verbose fields from JSON output").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (options) => {
+  runs.command("list").description("List play runs.").addHelpText(
+    "after",
+    `
+Notes:
+  Bounded inventory for a play's recent runs. Use --compact for agent loops.
+  Common statuses include running, completed, failed, and stopped.
+
+Examples:
+  deepline runs list --play my-play
+  deepline runs list --play my-play --status failed --compact --json
+`
+  ).requiredOption("--play <name>", "Play name to filter runs").option("--status <status>", "Filter by run status").option("--compact", "Drop verbose fields from JSON output").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (options) => {
     process.exitCode = await handleRunsList([
       "--play",
       options.play,
@@ -7425,14 +7791,37 @@ Examples:
       ...options.json ? ["--json"] : []
     ]);
   });
-  runs.command("tail <runId>").description("Read the canonical live stream for a play run.").option("--json", "Emit JSON output. Also automatic when stdout is piped").option("--compact", "Drop verbose fields from JSON output").action(async (runId, options) => {
+  runs.command("tail <runId>").description("Read the canonical live stream for a play run.").addHelpText(
+    "after",
+    `
+Notes:
+  Streams live run events until the stream ends. Use get for current status and
+  logs for persisted log history.
+
+Examples:
+  deepline runs tail play/my-play/run/20260501t000000-000
+  deepline runs tail play/my-play/run/20260501t000000-000 --compact --json
+`
+  ).option("--json", "Emit JSON output. Also automatic when stdout is piped").option("--compact", "Drop verbose fields from JSON output").action(async (runId, options) => {
     process.exitCode = await handleRunTail([
       runId,
       ...options.json ? ["--json"] : [],
       ...options.compact ? ["--compact"] : []
     ]);
   });
-  runs.command("logs <runId>").description("Fetch persisted logs for a play run.").option("--limit <count>", "Maximum recent log lines to print without --out", "200").option("--out <path>", "Write the full persisted log stream to a file").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (runId, options) => {
+  runs.command("logs <runId>").description("Fetch persisted logs for a play run.").addHelpText(
+    "after",
+    `
+Notes:
+  Prints a bounded recent log preview by default. Use --out to write the full
+  persisted log stream to a local file.
+
+Examples:
+  deepline runs logs play/my-play/run/20260501t000000-000
+  deepline runs logs play/my-play/run/20260501t000000-000 --limit 500
+  deepline runs logs play/my-play/run/20260501t000000-000 --out run.log --json
+`
+  ).option("--limit <count>", "Maximum recent log lines to print without --out", "200").option("--out <path>", "Write the full persisted log stream to a file").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (runId, options) => {
     process.exitCode = await handleRunLogs([
       runId,
       ...options.limit ? ["--limit", options.limit] : [],
@@ -7440,14 +7829,36 @@ Examples:
       ...options.json ? ["--json"] : []
     ]);
   });
-  runs.command("stop <runId>").description("Stop a play run.").option("--reason <text>", "Reason to include with the stop request").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (runId, options) => {
+  runs.command("stop <runId>").description("Stop a play run.").addHelpText(
+    "after",
+    `
+Notes:
+  Mutates cloud state by requesting cancellation for an active run. Already
+  terminal runs are returned as no-ops by the server when applicable.
+
+Examples:
+  deepline runs stop play/my-play/run/20260501t000000-000 --reason "stale lock"
+  deepline runs stop play/my-play/run/20260501t000000-000 --json
+`
+  ).option("--reason <text>", "Reason to include with the stop request").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (runId, options) => {
     process.exitCode = await handleRunStop([
       runId,
       ...options.reason ? ["--reason", options.reason] : [],
       ...options.json ? ["--json"] : []
     ]);
   });
-  runs.command("export <runId>").description("Export the completed row output for a play run to CSV.").requiredOption("--out <path>", "Output CSV path").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (runId, options) => {
+  runs.command("export <runId>").description("Export the completed row output for a play run to CSV.").addHelpText(
+    "after",
+    `
+Notes:
+  Writes the completed row output to the requested local CSV path. Use runs get
+  first when you need to confirm the run is complete or inspect preview output.
+
+Examples:
+  deepline runs export play/my-play/run/20260501t000000-000 --out output.csv
+  deepline runs export play/my-play/run/20260501t000000-000 --out output.csv --json
+`
+  ).requiredOption("--out <path>", "Output CSV path").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (runId, options) => {
     process.exitCode = await handleRunExport([
       runId,
       "--out",
@@ -7691,16 +8102,44 @@ Concepts:
 
 Common commands:
   deepline tools search email --json
-  deepline tools get hunter_email_verifier --json
+  deepline tools describe hunter_email_verifier --json
   deepline tools call hunter_email_verifier --input '{"email":"a@b.com"}'
+
+Output:
+  Search/list output is bounded. Use describe for a compact contract and get for
+  the full machine-readable metadata available for the tool.
 `
   );
-  tools.command("list").description("List available tools.").option("--json", "Emit JSON output").action(async (options) => {
+  tools.command("list").description("List available tools.").addHelpText(
+    "after",
+    `
+Notes:
+  Inventory command for known tool ids. Use search for ranked discovery by
+  intent, aliases, descriptions, and schema fields.
+
+Examples:
+  deepline tools list
+  deepline tools list --json
+  deepline tools search email --json
+`
+  ).option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (options) => {
     process.exitCode = await listTools([
       ...options.json ? ["--json"] : []
     ]);
   });
-  tools.command("search <query>").description("Search available tools.").option("--categories <categories>", "Comma-separated categories to filter ranked search").option("--search_terms <terms>", "Structured search terms for ranked search").option("--search-terms <terms>", "Structured search terms for ranked search").option("--search-mode <mode>", "Ranked search mode: v1 or v2").option("--include-search-debug", "Include ranked search debug metadata").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (query, options) => {
+  tools.command("search <query>").description("Search available tools.").addHelpText(
+    "after",
+    `
+Notes:
+  Ranked discovery for atomic provider/API operations. Results include tool ids
+  that can be passed to deepline tools describe or deepline tools call.
+
+Examples:
+  deepline tools search email
+  deepline tools search "company enrichment" --categories enrichment --json
+  deepline tools search verifier --search-mode v2 --json
+`
+  ).option("--categories <categories>", "Comma-separated categories to filter ranked search").option("--search_terms <terms>", "Structured search terms for ranked search").option("--search-terms <terms>", "Structured search terms for ranked search").option("--search-mode <mode>", "Ranked search mode: v1 or v2").option("--include-search-debug", "Include ranked search debug metadata").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (query, options) => {
     process.exitCode = await searchTools(query, {
       json: options.json,
       categories: options.categories,
@@ -7709,15 +8148,18 @@ Common commands:
       includeSearchDebug: Boolean(options.includeSearchDebug)
     });
   });
-  tools.command("get <toolId>").alias("describe").description("Show metadata for a tool.").addHelpText(
+  const addToolMetadataCommand = (command, preferredExample) => command.description("Show metadata for a tool.").addHelpText(
     "after",
     `
 Notes:
-  Shows the tool contract, input schema, output schema, costs, aliases, and metadata.
+  Shows the tool contract, input schema, output schema, Deepline cost, aliases,
+  and metadata. describe is the preferred discovery verb; get is kept as a
+  compatibility command for the same metadata surface.
 
 Examples:
-  deepline tools get hunter_email_verifier
-  deepline tools get hunter_email_verifier --json | jq '.inputSchema'
+  deepline tools ${preferredExample} hunter_email_verifier
+  deepline tools ${preferredExample} hunter_email_verifier --json | jq '.inputSchema'
+  deepline tools call hunter_email_verifier --input '{"email":"a@b.com"}'
 `
   ).option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (toolId, options) => {
     process.exitCode = await getTool([
@@ -7725,12 +8167,16 @@ Examples:
       ...options.json ? ["--json"] : []
     ]);
   });
+  addToolMetadataCommand(tools.command("describe <toolId>"), "describe");
+  addToolMetadataCommand(tools.command("get <toolId>"), "get");
   tools.command("call <toolId>").alias("execute").alias("run").description("Execute a tool by id.").addHelpText(
     "after",
     `
 Notes:
   Use tools for one atomic provider/API operation. Use plays for composed workflows,
   waterfalls, row maps, checkpoints, and retries.
+  Calling a provider-backed tool can spend Deepline credits. Use --json for the
+  stable result payload and --full-output when debugging response metadata.
 
 Examples:
   deepline tools call hunter_email_verifier --input '{"email":"a@b.com"}'
@@ -8416,6 +8862,9 @@ function shouldPrintStartupPhase() {
     return false;
   }
   const args = process.argv.slice(2);
+  if (args.includes("-h") || args.includes("--help")) {
+    return false;
+  }
   const command = args[0];
   const subcommand = args[1];
   return (command === "play" || command === "plays") && subcommand === "run";
@@ -8449,9 +8898,23 @@ Common commands:
   deepline plays run my.play.ts --input '{"domain":"stripe.com"}' --watch
   deepline tools call hunter_email_verifier --input '{"email":"a@b.com"}'
 
+Product model:
+  Tools are atomic provider/API operations that may spend credits.
+  Plays are durable workflows backed by source code or saved cloud revisions.
+  Runs are execution instances with logs, status, outputs, and cancellation.
+  Live plays are promoted revisions used by named play runs.
+
 Output:
   Structured commands print human-readable output in a terminal and JSON when stdout is piped.
   Use --json to force JSON in an interactive terminal.
+
+Safety:
+  Commands that mutate state, open a browser, write files, stop work, or spend credits say so in their help.
+  Use --no-open where available for CI and agent runs.
+
+Exit codes:
+  0 success; 2 usage/local input error; 3 auth/permission error; 4 not found;
+  5 server/runtime/provider failure; 7 validation/check failed.
 `
   );
   program.hook("preAction", async (_thisCommand, actionCommand) => {
@@ -8486,7 +8949,17 @@ Output:
   registerCsvCommands(program);
   registerDbCommands(program);
   registerFeedbackCommands(program);
-  program.command("health").description("Check server health.").action(async () => {
+  program.command("health").description("Check server health.").addHelpText(
+    "after",
+    `
+Notes:
+  Read-only connectivity check for the configured Deepline host. Prints the raw
+  server health payload as JSON.
+
+Examples:
+  deepline health
+`
+  ).action(async () => {
     try {
       const client = new DeeplineClient();
       const data = await client.health();
@@ -8498,7 +8971,18 @@ Output:
       );
     }
   });
-  program.command("version").description("Show version.").action(() => {
+  program.command("version").description("Show version.").addHelpText(
+    "after",
+    `
+Notes:
+  Prints the SDK CLI package version. The top-level -v/--version flag returns
+  the same version.
+
+Examples:
+  deepline version
+  deepline --version
+`
+  ).action(() => {
     process.stdout.write(`deepline ${SDK_VERSION}
 `);
   });