deepline 0.1.27 → 0.1.28

package/README.md

@@ -60,7 +60,7 @@ Config resolution order: explicit options > env vars > checkout `.env.worktree`
 ```bash
 bun sdk/bin/deepline-dev.ts health
 bun sdk/bin/deepline-dev.ts auth register|status
-bun sdk/bin/deepline-dev.ts tools list|get|call
+bun sdk/bin/deepline-dev.ts tools list|describe|execute
 bun sdk/bin/deepline-dev.ts plays run <file.play.ts> [--input '{}'] [--<input> value] [--watch]
 bun sdk/bin/deepline-dev.ts plays run <name> [--input '{}'] [--<input> value] [--watch]
 bun sdk/bin/deepline-dev.ts plays get <file.play.ts|name> [--json]
@@ -70,8 +70,13 @@ bun sdk/bin/deepline-dev.ts runs get <run-id> [--json]
 bun sdk/bin/deepline-dev.ts runs tail <run-id> [--json]
 bun sdk/bin/deepline-dev.ts runs stop <run-id> [--reason "..."] [--json]
 bun sdk/bin/deepline-dev.ts plays publish <play-file.ts|name> [--latest|--revision-id <id>] [--json]
+bun sdk/bin/deepline-dev.ts update
 ```
 
+`tools describe` and `tools execute` are canonical. `tools get` and `tools run`
+remain compatibility aliases. Unknown `plays run` flags such as
+`--csv leads.csv` or `--limit 5` are passed into the play input object.
+
 ## Public play entrypoints
 
 These are the public ways to run plays. They intentionally map to the external

package/dist/cli/index.js

@@ -266,7 +266,7 @@ function saveProjectDeeplineEnvValues(baseUrl, values, startDir = projectEnvStar
 }
 
 // src/version.ts
-var SDK_VERSION = "0.1.27";
+var SDK_VERSION = "0.1.28";
 var SDK_API_CONTRACT = "2026-05-runs-v2";
 
 // ../shared_libs/play-runtime/coordinator-headers.ts
@@ -548,7 +548,7 @@ function decodeSseFrame(frame) {
   return parsed;
 }
 function sleep(ms) {
-  return new Promise((resolve9) => setTimeout(resolve9, ms));
+  return new Promise((resolve10) => setTimeout(resolve10, ms));
 }
 
 // src/client.ts
@@ -556,7 +556,7 @@ var TERMINAL_PLAY_STATUSES = /* @__PURE__ */ new Set(["completed", "failed", "ca
 var INCLUDE_TOOL_METADATA_HEADER = "x-deepline-include-tool-metadata";
 var COMPILE_MANIFEST_RETRY_DELAYS_MS = [250, 1e3];
 function sleep2(ms) {
-  return new Promise((resolve9) => setTimeout(resolve9, ms));
+  return new Promise((resolve10) => setTimeout(resolve10, ms));
 }
 function isTransientCompileManifestError(error) {
   if (error instanceof DeeplineError && typeof error.statusCode === "number") {
@@ -714,7 +714,7 @@ var DeeplineClient = class {
       play.outputSchema,
       "rowOutputSchema"
     );
-    const runCommand = this.playRunCommand(play, { csvInput });
+    const runCommand2 = this.playRunCommand(play, { csvInput });
     return {
       name: play.name,
       ...play.reference ? { reference: play.reference } : {},
@@ -728,8 +728,8 @@ var DeeplineClient = class {
       outputSchema: options?.compact ? this.compactSchema(play.outputSchema) : play.outputSchema ?? null,
       ...csvInput ? { csvInput } : {},
       ...rowOutputSchema ? { rowOutputSchema } : {},
-      runCommand,
-      examples: [runCommand],
+      runCommand: runCommand2,
+      examples: [runCommand2],
       currentPublishedVersion: play.currentPublishedVersion ?? null,
       isDraftDirty: play.isDraftDirty
     };
@@ -2041,7 +2041,7 @@ function buildCandidateUrls2(url) {
   }
 }
 function sleep3(ms) {
-  return new Promise((resolve9) => setTimeout(resolve9, ms));
+  return new Promise((resolve10) => setTimeout(resolve10, ms));
 }
 function printDeeplineLogo() {
   if (process.stdout.isTTY && (process.stdout.columns ?? 80) >= 70) {
@@ -6477,7 +6477,7 @@ function writeStartedPlayRun(input) {
   console.log(output);
 }
 function parsePlayRunOptions(args) {
-  const usage = "Usage: deepline plays run <play-name> [--input '{...}'] [--watch] [--out output.csv] [--tail-timeout-ms 30000] [--force] [--<input> value]\n       deepline plays run <play-file.ts> [--input '{...}'] [--watch] [--out output.csv] [--tail-timeout-ms 30000] [--force] [--<input> value]\n       deepline plays run --file <play-file.ts> [--input '{...}'] [--watch] [--out output.csv] [--tail-timeout-ms 30000] [--force] [--<input> value]\n       deepline plays run --name <name> [--input '{...}'] [--live|--latest|--revision-id <id>] [--watch] [--out output.csv] [--tail-timeout-ms 30000] [--force] [--no-open] [--json] [--<input> value]\nRun `deepline plays run --help` for idempotency, tool call id, and ctx.map guidance.";
+  const usage = "Usage: deepline plays run <play-name> [--input '{...}'] [--watch] [--out output.csv] [--tail-timeout-ms 30000] [--force] [--<input> value]\n       deepline plays run <play-file.ts> [--input '{...}'] [--watch] [--out output.csv] [--tail-timeout-ms 30000] [--force] [--<input> value]\n       deepline plays run --file <play-file.ts> [--input '{...}'] [--watch] [--out output.csv] [--tail-timeout-ms 30000] [--force] [--<input> value]\n       deepline plays run --name <name> [--input '{...}'] [--live|--latest|--revision-id <id>] [--watch] [--out output.csv] [--tail-timeout-ms 30000] [--force] [--no-open] [--json] [--<input> value]\n       Unknown --<input> value flags, such as --csv leads.csv or --limit 5, are passed into play input.\nRun `deepline plays run --help` for idempotency, tool call id, and ctx.map guidance.";
   let filePath = null;
   let playName = null;
   let input = null;
@@ -7689,7 +7689,9 @@ Examples:
 Notes:
   Local files are bundled, preflighted, then run in Deepline cloud.
   Named plays run the live saved revision.
-  Unknown --foo and --foo.bar flags are treated as play input args.
+  Unknown --foo value and --foo.bar value flags are passed into play input.
+  Example: --csv leads.csv becomes input.csv = "leads.csv"; --limit 5 becomes
+  input.limit = 5.
   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.
@@ -7736,7 +7738,15 @@ Examples:
   ).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) => {
+  ).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").addHelpText(
+    "afterAll",
+    `
+Pass-through input flags:
+  Unknown flags are accepted intentionally and become play input fields. Use
+  this for play-specific inputs like --csv leads.csv, --limit 5, or
+  --filters.title "GTM Engineer".
+`
+  ).action(async (target, options, command) => {
     const passthroughArgs = [...command.args];
     const explicitTarget = options.file || options.name;
     const targetIsInputFlag = typeof target === "string" && target.startsWith("--");
@@ -8199,7 +8209,7 @@ function toListedTool(tool) {
     ...tool,
     id: tool.toolId,
     type: "tool",
-    callCommand: `deepline tools call ${tool.toolId}`
+    executeCommand: `deepline tools execute ${tool.toolId}`
   };
 }
 async function listTools(args) {
@@ -8272,7 +8282,7 @@ Inspect its schema with: deepline plays describe ${playName} --json`
   );
 }
 function registerToolsCommands(program) {
-  const tools = program.command("tools").description("Search, describe, and call atomic provider tools.").addHelpText(
+  const tools = program.command("tools").description("Search, describe, and execute atomic provider tools.").addHelpText(
     "after",
     `
 Concepts:
@@ -8282,11 +8292,11 @@ Concepts:
 Common commands:
   deepline tools search email --json
   deepline tools describe hunter_email_verifier --json
-  deepline tools call hunter_email_verifier --input '{"email":"a@b.com"}'
+  deepline tools execute 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.
+  Use describe for tool contracts. get is accepted as a compatibility alias.
+  Use execute to run a tool. run is accepted as a compatibility alias.
 `
   );
   tools.command("list").description("List available tools.").addHelpText(
@@ -8311,7 +8321,7 @@ Examples:
     `
 Notes:
   Ranked discovery for atomic provider/API operations. Results include tool ids
-  that can be passed to deepline tools describe or deepline tools call.
+  that can be passed to deepline tools describe or deepline tools execute.
 
 Examples:
   deepline tools search email
@@ -8327,18 +8337,18 @@ Examples:
       includeSearchDebug: Boolean(options.includeSearchDebug)
     });
   });
-  const addToolMetadataCommand = (command, preferredExample) => command.description("Show metadata for a tool.").addHelpText(
+  const addToolMetadataCommand = (command) => command.description("Show metadata for a tool.").addHelpText(
     "after",
     `
 Notes:
   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.
+  and metadata. describe is the preferred discovery verb. get is kept as a
+  compatibility alias for the same metadata surface.
 
 Examples:
-  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"}'
+  deepline tools describe hunter_email_verifier
+  deepline tools describe hunter_email_verifier --json | jq '.inputSchema'
+  deepline tools execute 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([
@@ -8346,21 +8356,21 @@ 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(
+  addToolMetadataCommand(tools.command("describe <toolId>").alias("get"));
+  tools.command("execute <toolId>").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.
+  execute is the canonical execution verb. run is a compatibility alias.
   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"}'
-  deepline tools call hunter_email_verifier -p email=a@b.com
-  deepline tools call test_rate_limit --input '{"key":"smoke"}' --json | jq '.status'
+  deepline tools execute hunter_email_verifier --input '{"email":"a@b.com"}'
+  deepline tools execute hunter_email_verifier -p email=a@b.com
+  deepline tools execute test_rate_limit --input '{"key":"smoke"}' --json | jq '.status'
 `
   ).option("-p, --param <key=value>", "Pass one parameter. Repeat for multiple values.", (value, acc) => {
     acc.push(value);
@@ -8649,7 +8659,7 @@ function normalizeOutputFormat(raw) {
 function parseExecuteOptions(args) {
   const toolId = args[0];
   if (!toolId) {
-    throw new Error(`Usage: deepline tools call <toolId> [--param key=value ...] [--input '{"k":"v"}'] [--output-format auto|csv|csv_file|json|json_file] [--full-output] [--no-preview]`);
+    throw new Error(`Usage: deepline tools execute <toolId> [--param key=value ...] [--input '{"k":"v"}'] [--output-format auto|csv|csv_file|json|json_file] [--full-output] [--no-preview]`);
   }
   const params = {};
   let outputFormat = "auto";
@@ -8843,11 +8853,123 @@ async function executeTool(args) {
   return 0;
 }
 
-// src/cli/skills-sync.ts
+// src/cli/commands/update.ts
 var import_node_child_process2 = require("child_process");
 var import_node_fs10 = require("fs");
-var import_node_os8 = require("os");
 var import_node_path12 = require("path");
+function posixShellQuote(value) {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+function windowsCmdQuote(value) {
+  return `"${value.replace(/"/g, '""')}"`;
+}
+function shellQuote2(value) {
+  if (process.platform === "win32") {
+    return /^[A-Za-z0-9_./:@%+=,-]+$/.test(value) ? value : windowsCmdQuote(value);
+  }
+  return posixShellQuote(value);
+}
+function buildSourceUpdateCommand(sourceRoot) {
+  const quotedRoot = shellQuote2(sourceRoot);
+  const cdCommand = process.platform === "win32" ? `cd /d ${quotedRoot}` : `cd ${quotedRoot}`;
+  return `${cdCommand} && git fetch origin main --tags && git merge --ff-only origin/main`;
+}
+function findRepoBackedSdkRoot(startPath) {
+  let current = (0, import_node_path12.resolve)(startPath);
+  while (true) {
+    if ((0, import_node_fs10.existsSync)((0, import_node_path12.join)(current, "sdk", "package.json")) && (0, import_node_fs10.existsSync)((0, import_node_path12.join)(current, "sdk", "bin", "deepline-dev.ts"))) {
+      return current;
+    }
+    const parent = (0, import_node_path12.dirname)(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+function resolveUpdatePlan() {
+  const entrypoint = process.argv[1] ? (0, import_node_path12.resolve)(process.argv[1]) : "";
+  const sourceRoot = entrypoint ? findRepoBackedSdkRoot((0, import_node_path12.dirname)(entrypoint)) : null;
+  if (sourceRoot) {
+    return {
+      kind: "source",
+      repoRoot: sourceRoot,
+      manualCommand: buildSourceUpdateCommand(sourceRoot)
+    };
+  }
+  const command = "npm";
+  const args = ["install", "-g", "deepline@latest"];
+  return {
+    kind: "npm-global",
+    command,
+    args,
+    manualCommand: `${command} ${args.map(shellQuote2).join(" ")}`
+  };
+}
+function runCommand(command, args) {
+  return new Promise((resolveExitCode) => {
+    const child = (0, import_node_child_process2.spawn)(command, args, {
+      stdio: "inherit",
+      shell: process.platform === "win32",
+      env: process.env
+    });
+    child.on("error", (error) => {
+      process.stderr.write(`Failed to start ${command}: ${error.message}
+`);
+      resolveExitCode(1);
+    });
+    child.on("close", (code) => {
+      resolveExitCode(code ?? 1);
+    });
+  });
+}
+async function handleUpdate(options) {
+  const plan = resolveUpdatePlan();
+  if (options.json) {
+    process.stdout.write(`${JSON.stringify(plan)}
+`);
+    return 0;
+  }
+  if (options.printCommand) {
+    process.stdout.write(`${plan.manualCommand}
+`);
+    return 0;
+  }
+  if (plan.kind === "source") {
+    process.stdout.write(
+      `This Deepline CLI is running from SDK source, so it cannot safely update itself like an npm global.
+Update the backing checkout with:
+  ${plan.manualCommand}
+`
+    );
+    return 0;
+  }
+  process.stderr.write(`Updating Deepline SDK/CLI with: ${plan.manualCommand}
+`);
+  return runCommand(plan.command, plan.args);
+}
+function registerUpdateCommand(program) {
+  program.command("update").alias("upgrade").description("Update the Deepline SDK/CLI.").addHelpText(
+    "after",
+    `
+Notes:
+  For the published npm CLI, this runs npm install -g deepline@latest.
+  For repo-backed SDK wrappers such as cli-env sdk-prod or sdk-worktree, this
+  prints the exact git command to update the checkout that provides the CLI.
+
+Examples:
+  deepline update
+  deepline update --print-command
+  deepline update --json
+`
+  ).option("--print-command", "Print the update command without running it").option("--json", "Emit the resolved update plan as JSON").action(async (options) => {
+    process.exitCode = await handleUpdate(options);
+  });
+}
+
+// src/cli/skills-sync.ts
+var import_node_child_process3 = require("child_process");
+var import_node_fs11 = require("fs");
+var import_node_os8 = require("os");
+var import_node_path13 = require("path");
 var CHECK_TIMEOUT_MS2 = 3e3;
 var SDK_SKILL_NAME = "deepline-sdk";
 var SKILL_AGENTS = ["codex", "claude-code", "cursor"];
@@ -8858,21 +8980,21 @@ function shouldSkipSkillsSync() {
 }
 function sdkSkillsVersionPath(baseUrl) {
   const home = process.env.HOME?.trim() || (0, import_node_os8.homedir)();
-  return (0, import_node_path12.join)(home, ".local", "deepline", baseUrlSlug(baseUrl), "sdk-skills", ".version");
+  return (0, import_node_path13.join)(home, ".local", "deepline", baseUrlSlug(baseUrl), "sdk-skills", ".version");
 }
 function readLocalSkillsVersion(baseUrl) {
   const path = sdkSkillsVersionPath(baseUrl);
-  if (!(0, import_node_fs10.existsSync)(path)) return "";
+  if (!(0, import_node_fs11.existsSync)(path)) return "";
   try {
-    return (0, import_node_fs10.readFileSync)(path, "utf-8").trim();
+    return (0, import_node_fs11.readFileSync)(path, "utf-8").trim();
   } catch {
     return "";
   }
 }
 function writeLocalSkillsVersion(baseUrl, version) {
   const path = sdkSkillsVersionPath(baseUrl);
-  (0, import_node_fs10.mkdirSync)((0, import_node_path12.dirname)(path), { recursive: true });
-  (0, import_node_fs10.writeFileSync)(path, `${version}
+  (0, import_node_fs11.mkdirSync)((0, import_node_path13.dirname)(path), { recursive: true });
+  (0, import_node_fs11.writeFileSync)(path, `${version}
 `, "utf-8");
 }
 async function fetchSkillsUpdate(baseUrl, localVersion) {
@@ -8936,13 +9058,13 @@ function buildBunxSkillsInstallArgs(baseUrl) {
   ];
 }
 function hasCommand(command) {
-  const result = (0, import_node_child_process2.spawnSync)(command, ["--version"], {
+  const result = (0, import_node_child_process3.spawnSync)(command, ["--version"], {
     stdio: "ignore",
     shell: process.platform === "win32"
   });
   return result.status === 0;
 }
-function shellQuote2(arg) {
+function shellQuote3(arg) {
   return `'${arg.replace(/'/g, `'\\''`)}'`;
 }
 function resolveSkillsInstallCommands(baseUrl) {
@@ -8950,7 +9072,7 @@ function resolveSkillsInstallCommands(baseUrl) {
   const npxInstall = {
     command: "npx",
     args: npxArgs,
-    manualCommand: `npx ${npxArgs.map(shellQuote2).join(" ")}`
+    manualCommand: `npx ${npxArgs.map(shellQuote3).join(" ")}`
   };
   if (hasCommand("bunx")) {
     const bunxArgs = buildBunxSkillsInstallArgs(baseUrl);
@@ -8958,7 +9080,7 @@ function resolveSkillsInstallCommands(baseUrl) {
       {
         command: "bunx",
         args: bunxArgs,
-        manualCommand: `bunx ${bunxArgs.map(shellQuote2).join(" ")}`
+        manualCommand: `bunx ${bunxArgs.map(shellQuote3).join(" ")}`
       },
       npxInstall
     ];
@@ -8966,8 +9088,8 @@ function resolveSkillsInstallCommands(baseUrl) {
   return [npxInstall];
 }
 function runOneSkillsInstall(install) {
-  return new Promise((resolve9) => {
-    const child = (0, import_node_child_process2.spawn)(install.command, install.args, {
+  return new Promise((resolve10) => {
+    const child = (0, import_node_child_process3.spawn)(install.command, install.args, {
       stdio: ["ignore", "ignore", "pipe"],
       env: process.env
     });
@@ -8976,7 +9098,7 @@ function runOneSkillsInstall(install) {
       stderr += chunk.toString("utf-8");
     });
     child.on("error", (error) => {
-      resolve9({
+      resolve10({
         ok: false,
         detail: `failed to start ${install.command}: ${error.message}`,
         manualCommand: install.manualCommand
@@ -8984,11 +9106,11 @@ function runOneSkillsInstall(install) {
     });
     child.on("close", (code) => {
       if (code === 0) {
-        resolve9({ ok: true, detail: "", manualCommand: install.manualCommand });
+        resolve10({ ok: true, detail: "", manualCommand: install.manualCommand });
         return;
       }
       const detail = stderr.trim();
-      resolve9({
+      resolve10({
         ok: false,
         detail: detail ? `${install.command}: ${detail}` : `${install.command} exited ${code}`,
         manualCommand: install.manualCommand
@@ -9075,7 +9197,8 @@ Common commands:
   deepline plays search email --json
   deepline plays describe person-linkedin-to-email --json
   deepline plays run my.play.ts --input '{"domain":"stripe.com"}' --watch
-  deepline tools call hunter_email_verifier --input '{"email":"a@b.com"}'
+  deepline tools execute hunter_email_verifier --input '{"email":"a@b.com"}'
+  deepline update
 
 Product model:
   Tools are atomic provider/API operations that may spend credits.
@@ -9097,7 +9220,7 @@ Exit codes:
 `
   );
   program.hook("preAction", async (_thisCommand, actionCommand) => {
-    if (actionCommand.name() === "version") {
+    if (actionCommand.name() === "version" || actionCommand.name() === "update") {
       return;
     }
     if (printStartupPhase) {
@@ -9128,6 +9251,7 @@ Exit codes:
   registerCsvCommands(program);
   registerDbCommands(program);
   registerFeedbackCommands(program);
+  registerUpdateCommand(program);
   program.command("health").description("Check server health.").addHelpText(
     "after",
     `

package/dist/cli/index.mjs

@@ -243,7 +243,7 @@ function saveProjectDeeplineEnvValues(baseUrl, values, startDir = projectEnvStar
 }
 
 // src/version.ts
-var SDK_VERSION = "0.1.27";
+var SDK_VERSION = "0.1.28";
 var SDK_API_CONTRACT = "2026-05-runs-v2";
 
 // ../shared_libs/play-runtime/coordinator-headers.ts
@@ -525,7 +525,7 @@ function decodeSseFrame(frame) {
   return parsed;
 }
 function sleep(ms) {
-  return new Promise((resolve9) => setTimeout(resolve9, ms));
+  return new Promise((resolve10) => setTimeout(resolve10, ms));
 }
 
 // src/client.ts
@@ -533,7 +533,7 @@ var TERMINAL_PLAY_STATUSES = /* @__PURE__ */ new Set(["completed", "failed", "ca
 var INCLUDE_TOOL_METADATA_HEADER = "x-deepline-include-tool-metadata";
 var COMPILE_MANIFEST_RETRY_DELAYS_MS = [250, 1e3];
 function sleep2(ms) {
-  return new Promise((resolve9) => setTimeout(resolve9, ms));
+  return new Promise((resolve10) => setTimeout(resolve10, ms));
 }
 function isTransientCompileManifestError(error) {
   if (error instanceof DeeplineError && typeof error.statusCode === "number") {
@@ -691,7 +691,7 @@ var DeeplineClient = class {
       play.outputSchema,
       "rowOutputSchema"
     );
-    const runCommand = this.playRunCommand(play, { csvInput });
+    const runCommand2 = this.playRunCommand(play, { csvInput });
     return {
       name: play.name,
       ...play.reference ? { reference: play.reference } : {},
@@ -705,8 +705,8 @@ var DeeplineClient = class {
       outputSchema: options?.compact ? this.compactSchema(play.outputSchema) : play.outputSchema ?? null,
       ...csvInput ? { csvInput } : {},
       ...rowOutputSchema ? { rowOutputSchema } : {},
-      runCommand,
-      examples: [runCommand],
+      runCommand: runCommand2,
+      examples: [runCommand2],
       currentPublishedVersion: play.currentPublishedVersion ?? null,
       isDraftDirty: play.isDraftDirty
     };
@@ -2023,7 +2023,7 @@ function buildCandidateUrls2(url) {
   }
 }
 function sleep3(ms) {
-  return new Promise((resolve9) => setTimeout(resolve9, ms));
+  return new Promise((resolve10) => setTimeout(resolve10, ms));
 }
 function printDeeplineLogo() {
   if (process.stdout.isTTY && (process.stdout.columns ?? 80) >= 70) {
@@ -6464,7 +6464,7 @@ function writeStartedPlayRun(input) {
   console.log(output);
 }
 function parsePlayRunOptions(args) {
-  const usage = "Usage: deepline plays run <play-name> [--input '{...}'] [--watch] [--out output.csv] [--tail-timeout-ms 30000] [--force] [--<input> value]\n       deepline plays run <play-file.ts> [--input '{...}'] [--watch] [--out output.csv] [--tail-timeout-ms 30000] [--force] [--<input> value]\n       deepline plays run --file <play-file.ts> [--input '{...}'] [--watch] [--out output.csv] [--tail-timeout-ms 30000] [--force] [--<input> value]\n       deepline plays run --name <name> [--input '{...}'] [--live|--latest|--revision-id <id>] [--watch] [--out output.csv] [--tail-timeout-ms 30000] [--force] [--no-open] [--json] [--<input> value]\nRun `deepline plays run --help` for idempotency, tool call id, and ctx.map guidance.";
+  const usage = "Usage: deepline plays run <play-name> [--input '{...}'] [--watch] [--out output.csv] [--tail-timeout-ms 30000] [--force] [--<input> value]\n       deepline plays run <play-file.ts> [--input '{...}'] [--watch] [--out output.csv] [--tail-timeout-ms 30000] [--force] [--<input> value]\n       deepline plays run --file <play-file.ts> [--input '{...}'] [--watch] [--out output.csv] [--tail-timeout-ms 30000] [--force] [--<input> value]\n       deepline plays run --name <name> [--input '{...}'] [--live|--latest|--revision-id <id>] [--watch] [--out output.csv] [--tail-timeout-ms 30000] [--force] [--no-open] [--json] [--<input> value]\n       Unknown --<input> value flags, such as --csv leads.csv or --limit 5, are passed into play input.\nRun `deepline plays run --help` for idempotency, tool call id, and ctx.map guidance.";
   let filePath = null;
   let playName = null;
   let input = null;
@@ -7676,7 +7676,9 @@ Examples:
 Notes:
   Local files are bundled, preflighted, then run in Deepline cloud.
   Named plays run the live saved revision.
-  Unknown --foo and --foo.bar flags are treated as play input args.
+  Unknown --foo value and --foo.bar value flags are passed into play input.
+  Example: --csv leads.csv becomes input.csv = "leads.csv"; --limit 5 becomes
+  input.limit = 5.
   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.
@@ -7723,7 +7725,15 @@ Examples:
   ).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) => {
+  ).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").addHelpText(
+    "afterAll",
+    `
+Pass-through input flags:
+  Unknown flags are accepted intentionally and become play input fields. Use
+  this for play-specific inputs like --csv leads.csv, --limit 5, or
+  --filters.title "GTM Engineer".
+`
+  ).action(async (target, options, command) => {
     const passthroughArgs = [...command.args];
     const explicitTarget = options.file || options.name;
     const targetIsInputFlag = typeof target === "string" && target.startsWith("--");
@@ -8186,7 +8196,7 @@ function toListedTool(tool) {
     ...tool,
     id: tool.toolId,
     type: "tool",
-    callCommand: `deepline tools call ${tool.toolId}`
+    executeCommand: `deepline tools execute ${tool.toolId}`
   };
 }
 async function listTools(args) {
@@ -8259,7 +8269,7 @@ Inspect its schema with: deepline plays describe ${playName} --json`
   );
 }
 function registerToolsCommands(program) {
-  const tools = program.command("tools").description("Search, describe, and call atomic provider tools.").addHelpText(
+  const tools = program.command("tools").description("Search, describe, and execute atomic provider tools.").addHelpText(
     "after",
     `
 Concepts:
@@ -8269,11 +8279,11 @@ Concepts:
 Common commands:
   deepline tools search email --json
   deepline tools describe hunter_email_verifier --json
-  deepline tools call hunter_email_verifier --input '{"email":"a@b.com"}'
+  deepline tools execute 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.
+  Use describe for tool contracts. get is accepted as a compatibility alias.
+  Use execute to run a tool. run is accepted as a compatibility alias.
 `
   );
   tools.command("list").description("List available tools.").addHelpText(
@@ -8298,7 +8308,7 @@ Examples:
     `
 Notes:
   Ranked discovery for atomic provider/API operations. Results include tool ids
-  that can be passed to deepline tools describe or deepline tools call.
+  that can be passed to deepline tools describe or deepline tools execute.
 
 Examples:
   deepline tools search email
@@ -8314,18 +8324,18 @@ Examples:
       includeSearchDebug: Boolean(options.includeSearchDebug)
     });
   });
-  const addToolMetadataCommand = (command, preferredExample) => command.description("Show metadata for a tool.").addHelpText(
+  const addToolMetadataCommand = (command) => command.description("Show metadata for a tool.").addHelpText(
     "after",
     `
 Notes:
   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.
+  and metadata. describe is the preferred discovery verb. get is kept as a
+  compatibility alias for the same metadata surface.
 
 Examples:
-  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"}'
+  deepline tools describe hunter_email_verifier
+  deepline tools describe hunter_email_verifier --json | jq '.inputSchema'
+  deepline tools execute 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([
@@ -8333,21 +8343,21 @@ 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(
+  addToolMetadataCommand(tools.command("describe <toolId>").alias("get"));
+  tools.command("execute <toolId>").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.
+  execute is the canonical execution verb. run is a compatibility alias.
   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"}'
-  deepline tools call hunter_email_verifier -p email=a@b.com
-  deepline tools call test_rate_limit --input '{"key":"smoke"}' --json | jq '.status'
+  deepline tools execute hunter_email_verifier --input '{"email":"a@b.com"}'
+  deepline tools execute hunter_email_verifier -p email=a@b.com
+  deepline tools execute test_rate_limit --input '{"key":"smoke"}' --json | jq '.status'
 `
   ).option("-p, --param <key=value>", "Pass one parameter. Repeat for multiple values.", (value, acc) => {
     acc.push(value);
@@ -8636,7 +8646,7 @@ function normalizeOutputFormat(raw) {
 function parseExecuteOptions(args) {
   const toolId = args[0];
   if (!toolId) {
-    throw new Error(`Usage: deepline tools call <toolId> [--param key=value ...] [--input '{"k":"v"}'] [--output-format auto|csv|csv_file|json|json_file] [--full-output] [--no-preview]`);
+    throw new Error(`Usage: deepline tools execute <toolId> [--param key=value ...] [--input '{"k":"v"}'] [--output-format auto|csv|csv_file|json|json_file] [--full-output] [--no-preview]`);
   }
   const params = {};
   let outputFormat = "auto";
@@ -8830,11 +8840,123 @@ async function executeTool(args) {
   return 0;
 }
 
+// src/cli/commands/update.ts
+import { spawn } from "child_process";
+import { existsSync as existsSync7 } from "fs";
+import { dirname as dirname9, join as join9, resolve as resolve9 } from "path";
+function posixShellQuote(value) {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+function windowsCmdQuote(value) {
+  return `"${value.replace(/"/g, '""')}"`;
+}
+function shellQuote2(value) {
+  if (process.platform === "win32") {
+    return /^[A-Za-z0-9_./:@%+=,-]+$/.test(value) ? value : windowsCmdQuote(value);
+  }
+  return posixShellQuote(value);
+}
+function buildSourceUpdateCommand(sourceRoot) {
+  const quotedRoot = shellQuote2(sourceRoot);
+  const cdCommand = process.platform === "win32" ? `cd /d ${quotedRoot}` : `cd ${quotedRoot}`;
+  return `${cdCommand} && git fetch origin main --tags && git merge --ff-only origin/main`;
+}
+function findRepoBackedSdkRoot(startPath) {
+  let current = resolve9(startPath);
+  while (true) {
+    if (existsSync7(join9(current, "sdk", "package.json")) && existsSync7(join9(current, "sdk", "bin", "deepline-dev.ts"))) {
+      return current;
+    }
+    const parent = dirname9(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+function resolveUpdatePlan() {
+  const entrypoint = process.argv[1] ? resolve9(process.argv[1]) : "";
+  const sourceRoot = entrypoint ? findRepoBackedSdkRoot(dirname9(entrypoint)) : null;
+  if (sourceRoot) {
+    return {
+      kind: "source",
+      repoRoot: sourceRoot,
+      manualCommand: buildSourceUpdateCommand(sourceRoot)
+    };
+  }
+  const command = "npm";
+  const args = ["install", "-g", "deepline@latest"];
+  return {
+    kind: "npm-global",
+    command,
+    args,
+    manualCommand: `${command} ${args.map(shellQuote2).join(" ")}`
+  };
+}
+function runCommand(command, args) {
+  return new Promise((resolveExitCode) => {
+    const child = spawn(command, args, {
+      stdio: "inherit",
+      shell: process.platform === "win32",
+      env: process.env
+    });
+    child.on("error", (error) => {
+      process.stderr.write(`Failed to start ${command}: ${error.message}
+`);
+      resolveExitCode(1);
+    });
+    child.on("close", (code) => {
+      resolveExitCode(code ?? 1);
+    });
+  });
+}
+async function handleUpdate(options) {
+  const plan = resolveUpdatePlan();
+  if (options.json) {
+    process.stdout.write(`${JSON.stringify(plan)}
+`);
+    return 0;
+  }
+  if (options.printCommand) {
+    process.stdout.write(`${plan.manualCommand}
+`);
+    return 0;
+  }
+  if (plan.kind === "source") {
+    process.stdout.write(
+      `This Deepline CLI is running from SDK source, so it cannot safely update itself like an npm global.
+Update the backing checkout with:
+  ${plan.manualCommand}
+`
+    );
+    return 0;
+  }
+  process.stderr.write(`Updating Deepline SDK/CLI with: ${plan.manualCommand}
+`);
+  return runCommand(plan.command, plan.args);
+}
+function registerUpdateCommand(program) {
+  program.command("update").alias("upgrade").description("Update the Deepline SDK/CLI.").addHelpText(
+    "after",
+    `
+Notes:
+  For the published npm CLI, this runs npm install -g deepline@latest.
+  For repo-backed SDK wrappers such as cli-env sdk-prod or sdk-worktree, this
+  prints the exact git command to update the checkout that provides the CLI.
+
+Examples:
+  deepline update
+  deepline update --print-command
+  deepline update --json
+`
+  ).option("--print-command", "Print the update command without running it").option("--json", "Emit the resolved update plan as JSON").action(async (options) => {
+    process.exitCode = await handleUpdate(options);
+  });
+}
+
 // src/cli/skills-sync.ts
-import { spawn, spawnSync as spawnSync2 } from "child_process";
-import { existsSync as existsSync7, mkdirSync as mkdirSync5, readFileSync as readFileSync5, writeFileSync as writeFileSync8 } from "fs";
+import { spawn as spawn2, spawnSync as spawnSync2 } from "child_process";
+import { existsSync as existsSync8, mkdirSync as mkdirSync5, readFileSync as readFileSync5, writeFileSync as writeFileSync8 } from "fs";
 import { homedir as homedir4 } from "os";
-import { dirname as dirname9, join as join9 } from "path";
+import { dirname as dirname10, join as join10 } from "path";
 var CHECK_TIMEOUT_MS2 = 3e3;
 var SDK_SKILL_NAME = "deepline-sdk";
 var SKILL_AGENTS = ["codex", "claude-code", "cursor"];
@@ -8845,11 +8967,11 @@ function shouldSkipSkillsSync() {
 }
 function sdkSkillsVersionPath(baseUrl) {
   const home = process.env.HOME?.trim() || homedir4();
-  return join9(home, ".local", "deepline", baseUrlSlug(baseUrl), "sdk-skills", ".version");
+  return join10(home, ".local", "deepline", baseUrlSlug(baseUrl), "sdk-skills", ".version");
 }
 function readLocalSkillsVersion(baseUrl) {
   const path = sdkSkillsVersionPath(baseUrl);
-  if (!existsSync7(path)) return "";
+  if (!existsSync8(path)) return "";
   try {
     return readFileSync5(path, "utf-8").trim();
   } catch {
@@ -8858,7 +8980,7 @@ function readLocalSkillsVersion(baseUrl) {
 }
 function writeLocalSkillsVersion(baseUrl, version) {
   const path = sdkSkillsVersionPath(baseUrl);
-  mkdirSync5(dirname9(path), { recursive: true });
+  mkdirSync5(dirname10(path), { recursive: true });
   writeFileSync8(path, `${version}
 `, "utf-8");
 }
@@ -8929,7 +9051,7 @@ function hasCommand(command) {
   });
   return result.status === 0;
 }
-function shellQuote2(arg) {
+function shellQuote3(arg) {
   return `'${arg.replace(/'/g, `'\\''`)}'`;
 }
 function resolveSkillsInstallCommands(baseUrl) {
@@ -8937,7 +9059,7 @@ function resolveSkillsInstallCommands(baseUrl) {
   const npxInstall = {
     command: "npx",
     args: npxArgs,
-    manualCommand: `npx ${npxArgs.map(shellQuote2).join(" ")}`
+    manualCommand: `npx ${npxArgs.map(shellQuote3).join(" ")}`
   };
   if (hasCommand("bunx")) {
     const bunxArgs = buildBunxSkillsInstallArgs(baseUrl);
@@ -8945,7 +9067,7 @@ function resolveSkillsInstallCommands(baseUrl) {
       {
         command: "bunx",
         args: bunxArgs,
-        manualCommand: `bunx ${bunxArgs.map(shellQuote2).join(" ")}`
+        manualCommand: `bunx ${bunxArgs.map(shellQuote3).join(" ")}`
       },
       npxInstall
     ];
@@ -8953,8 +9075,8 @@ function resolveSkillsInstallCommands(baseUrl) {
   return [npxInstall];
 }
 function runOneSkillsInstall(install) {
-  return new Promise((resolve9) => {
-    const child = spawn(install.command, install.args, {
+  return new Promise((resolve10) => {
+    const child = spawn2(install.command, install.args, {
       stdio: ["ignore", "ignore", "pipe"],
       env: process.env
     });
@@ -8963,7 +9085,7 @@ function runOneSkillsInstall(install) {
       stderr += chunk.toString("utf-8");
     });
     child.on("error", (error) => {
-      resolve9({
+      resolve10({
         ok: false,
         detail: `failed to start ${install.command}: ${error.message}`,
         manualCommand: install.manualCommand
@@ -8971,11 +9093,11 @@ function runOneSkillsInstall(install) {
     });
     child.on("close", (code) => {
       if (code === 0) {
-        resolve9({ ok: true, detail: "", manualCommand: install.manualCommand });
+        resolve10({ ok: true, detail: "", manualCommand: install.manualCommand });
         return;
       }
       const detail = stderr.trim();
-      resolve9({
+      resolve10({
         ok: false,
         detail: detail ? `${install.command}: ${detail}` : `${install.command} exited ${code}`,
         manualCommand: install.manualCommand
@@ -9062,7 +9184,8 @@ Common commands:
   deepline plays search email --json
   deepline plays describe person-linkedin-to-email --json
   deepline plays run my.play.ts --input '{"domain":"stripe.com"}' --watch
-  deepline tools call hunter_email_verifier --input '{"email":"a@b.com"}'
+  deepline tools execute hunter_email_verifier --input '{"email":"a@b.com"}'
+  deepline update
 
 Product model:
   Tools are atomic provider/API operations that may spend credits.
@@ -9084,7 +9207,7 @@ Exit codes:
 `
   );
   program.hook("preAction", async (_thisCommand, actionCommand) => {
-    if (actionCommand.name() === "version") {
+    if (actionCommand.name() === "version" || actionCommand.name() === "update") {
       return;
     }
     if (printStartupPhase) {
@@ -9115,6 +9238,7 @@ Exit codes:
   registerCsvCommands(program);
   registerDbCommands(program);
   registerFeedbackCommands(program);
+  registerUpdateCommand(program);
   program.command("health").description("Check server health.").addHelpText(
     "after",
     `

package/dist/index.d.mts

@@ -1401,7 +1401,7 @@ declare class DeeplineClient {
     }>;
 }
 
-declare const SDK_VERSION = "0.1.27";
+declare const SDK_VERSION = "0.1.28";
 declare const SDK_API_CONTRACT = "2026-05-runs-v2";
 
 /**

package/dist/index.d.ts

@@ -1401,7 +1401,7 @@ declare class DeeplineClient {
     }>;
 }
 
-declare const SDK_VERSION = "0.1.27";
+declare const SDK_VERSION = "0.1.28";
 declare const SDK_API_CONTRACT = "2026-05-runs-v2";
 
 /**

package/dist/index.js

@@ -241,7 +241,7 @@ function resolveConfig(options) {
 }
 
 // src/version.ts
-var SDK_VERSION = "0.1.27";
+var SDK_VERSION = "0.1.28";
 var SDK_API_CONTRACT = "2026-05-runs-v2";
 
 // ../shared_libs/play-runtime/coordinator-headers.ts

package/dist/index.mjs

@@ -195,7 +195,7 @@ function resolveConfig(options) {
 }
 
 // src/version.ts
-var SDK_VERSION = "0.1.27";
+var SDK_VERSION = "0.1.28";
 var SDK_API_CONTRACT = "2026-05-runs-v2";
 
 // ../shared_libs/play-runtime/coordinator-headers.ts

package/dist/repo/sdk/src/version.ts

@@ -1,2 +1,2 @@
-export const SDK_VERSION = "0.1.27";
+export const SDK_VERSION = "0.1.28";
 export const SDK_API_CONTRACT = "2026-05-runs-v2";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepline",
-  "version": "0.1.27",
+  "version": "0.1.28",
   "description": "Deepline SDK + CLI — B2B data enrichment powered by durable cloud execution",
   "license": "MIT",
   "repository": {