deepline 0.1.28 → 0.1.30

package/dist/cli/index.mjs

@@ -243,8 +243,8 @@ function saveProjectDeeplineEnvValues(baseUrl, values, startDir = projectEnvStar
 }
 
 // src/version.ts
-var SDK_VERSION = "0.1.28";
-var SDK_API_CONTRACT = "2026-05-runs-v2";
+var SDK_VERSION = "0.1.30";
+var SDK_API_CONTRACT = "2026-05-runs-v2-datasets";
 
 // ../shared_libs/play-runtime/coordinator-headers.ts
 var COORDINATOR_INTERNAL_TOKEN_HEADER = "x-deepline-internal-token";
@@ -653,6 +653,7 @@ var DeeplineClient = class {
       list: (options2) => this.listRuns(options2),
       tail: (runId, options2) => this.tailRun(runId, options2),
       logs: (runId, options2) => this.getRunLogs(runId, options2),
+      exportDatasetRows: (input) => this.getPlaySheetRows(input),
       stop: (runId, options2) => this.stopRun(runId, options2)
     };
   }
@@ -680,7 +681,7 @@ var DeeplineClient = class {
     const target = play.reference || play.name;
     if (options?.csvInput) {
       const inputField = typeof options.csvInput.inputField === "string" && options.csvInput.inputField.trim() ? options.csvInput.inputField.trim() : "csv";
-      return `deepline plays run ${target} --${inputField} leads.csv --watch`;
+      return `deepline plays run ${target} --input '${JSON.stringify({ [inputField]: "leads.csv" })}' --watch`;
     }
     return `deepline plays run ${target} --input '{...}' --watch`;
   }
@@ -1340,6 +1341,19 @@ var DeeplineClient = class {
       entries
     };
   }
+  async getPlaySheetRows(input) {
+    const params = new URLSearchParams({
+      tableNamespace: input.tableNamespace,
+      limit: String(input.limit ?? 5e3),
+      offset: String(input.offset ?? 0)
+    });
+    if (input.runId?.trim()) {
+      params.set("runId", input.runId.trim());
+    }
+    return await this.http.get(
+      `/api/v2/plays/${encodeURIComponent(input.playName)}/sheet?${params.toString()}`
+    );
+  }
   /**
    * Stop a run by id using the public runs resource model.
    *
@@ -1952,6 +1966,38 @@ function clip(value, maxLength) {
   return value.length > maxLength ? `${value.slice(0, maxLength - 1)}\u2026` : value;
 }
 
+// src/cli/command-envelope.ts
+function renderSections(render) {
+  const lines = [];
+  for (const section of render?.sections ?? []) {
+    if (!section.title || section.lines.length === 0) continue;
+    lines.push(section.title);
+    lines.push(...section.lines.map((line) => `  ${line}`));
+  }
+  for (const action of render?.actions ?? []) {
+    if (!action.label || !action.command) continue;
+    lines.push(`${action.label}: ${action.command}`);
+  }
+  return lines;
+}
+function renderCommandEnvelopeText(envelope) {
+  const lines = renderSections(envelope.render);
+  if (lines.length > 0) {
+    return `${lines.join("\n")}
+`;
+  }
+  return `${JSON.stringify(envelope, null, 2)}
+`;
+}
+function printCommandEnvelope(envelope, options = {}) {
+  const jsonOutput = typeof options.json === "boolean" ? options.json : shouldEmitJson();
+  if (jsonOutput) {
+    printJson(envelope);
+    return;
+  }
+  process.stdout.write(options.text ?? renderCommandEnvelopeText(envelope));
+}
+
 // src/cli/commands/auth.ts
 var EXIT_OK = 0;
 var EXIT_AUTH = 1;
@@ -2200,6 +2246,7 @@ async function handleStatus(args) {
   const reveal = args.includes("--reveal");
   const jsonOutput = argsWantJson(args);
   let hostStatusPayload = null;
+  const hostLines = [];
   try {
     const { status: hStatus, data: hData } = await httpJson("GET", `${baseUrl}/api/v2/health`, null);
     if (hStatus === 200) {
@@ -2208,11 +2255,9 @@ async function handleStatus(args) {
         hostStatus: hData.status || "ok",
         hostVersion: hData.version || "(unknown)"
       };
-      if (!jsonOutput) {
-        console.log(`Host: ${baseUrl}`);
-        console.log(`Host status: ${hData.status || "ok"}`);
-        console.log(`Host version: ${hData.version || "(unknown)"}`);
-      }
+      hostLines.push(`Host: ${baseUrl}`);
+      hostLines.push(`Host status: ${hData.status || "ok"}`);
+      hostLines.push(`Host version: ${hData.version || "(unknown)"}`);
     }
   } catch {
     hostStatusPayload = {
@@ -2220,40 +2265,34 @@ async function handleStatus(args) {
       hostStatus: "unreachable",
       hostVersion: null
     };
-    if (!jsonOutput) {
-      console.log(`Host: ${baseUrl} (unreachable)`);
-    }
+    hostLines.push(`Host: ${baseUrl} (unreachable)`);
   }
   const env = loadCliEnv(baseUrl);
   const apiKey = process.env.DEEPLINE_API_KEY?.trim() || env.DEEPLINE_API_KEY || "";
   if (!apiKey) {
     if (env.DEEPLINE_CLAIM_TOKEN?.trim()) {
-      if (jsonOutput) {
-        process.stdout.write(`${JSON.stringify({
-          ...hostStatusPayload ?? { host: baseUrl },
-          status: "pending",
-          connected: false,
-          next: "deepline auth wait"
-        })}
-`);
-        return EXIT_OK;
-      }
-      console.log("Status: pending");
-      console.log("Run: deepline auth wait");
-      return EXIT_OK;
-    }
-    if (jsonOutput) {
-      process.stdout.write(`${JSON.stringify({
+      printCommandEnvelope({
         ...hostStatusPayload ?? { host: baseUrl },
-        status: "not connected",
+        status: "pending",
         connected: false,
-        next: "deepline auth register"
-      })}
-`);
+        next: "deepline auth wait",
+        render: {
+          sections: [{ title: "auth status", lines: [...hostLines, "Status: pending"] }],
+          actions: [{ label: "Run", command: "deepline auth wait" }]
+        }
+      }, { json: jsonOutput });
       return EXIT_OK;
     }
-    console.log("Status: not connected");
-    console.log("Run: deepline auth register");
+    printCommandEnvelope({
+      ...hostStatusPayload ?? { host: baseUrl },
+      status: "not connected",
+      connected: false,
+      next: "deepline auth register",
+      render: {
+        sections: [{ title: "auth status", lines: [...hostLines, "Status: not connected"] }],
+        actions: [{ label: "Run", command: "deepline auth register" }]
+      }
+    }, { json: jsonOutput });
     return EXIT_OK;
   }
   const { status, data } = await httpJson("POST", `${baseUrl}/api/v2/auth/cli/status`, apiKey, {
@@ -2261,18 +2300,16 @@ async function handleStatus(args) {
     reveal
   });
   if (status === 401 || status === 403) {
-    if (jsonOutput) {
-      process.stdout.write(`${JSON.stringify({
-        ...hostStatusPayload ?? { host: baseUrl },
-        status: "unauthorized",
-        connected: false,
-        next: "deepline auth register"
-      })}
-`);
-      return EXIT_AUTH;
-    }
-    console.log("Status: unauthorized");
-    console.log("Run: deepline auth register");
+    printCommandEnvelope({
+      ...hostStatusPayload ?? { host: baseUrl },
+      status: "unauthorized",
+      connected: false,
+      next: "deepline auth register",
+      render: {
+        sections: [{ title: "auth status", lines: [...hostLines, "Status: unauthorized"] }],
+        actions: [{ label: "Run", command: "deepline auth register" }]
+      }
+    }, { json: jsonOutput });
     return EXIT_AUTH;
   }
   if (status >= 400) {
@@ -2294,23 +2331,7 @@ async function handleStatus(args) {
     },
     examples: Array.isArray(data.examples) ? data.examples : []
   };
-  if (jsonOutput) {
-    process.stdout.write(`${JSON.stringify(payload)}
-`);
-  } else {
-    console.log(`Status: ${payload.status}`);
-    console.log(`Rate limit tier: ${payload.rateLimitTier}`);
-    if (payload.workspace.name) console.log(`Workspace: ${payload.workspace.name}`);
-    if (payload.workspace.slug) console.log(`Workspace slug: ${payload.workspace.slug}`);
-    if (payload.workspace.id != null) console.log(`Org ID: ${payload.workspace.id}`);
-    if (payload.user.id != null) console.log(`User ID: ${payload.user.id}`);
-    if (payload.examples.length > 0) {
-      console.log("Examples:");
-      for (const example of payload.examples.slice(0, 3)) {
-        console.log(`  ${String(example)}`);
-      }
-    }
-  }
+  let savedApiKeyPath = null;
   if (reveal) {
     const apiKeyResp = String(data.api_key || apiKey);
     if (apiKeyResp) {
@@ -2319,9 +2340,31 @@ async function handleStatus(args) {
         DEEPLINE_API_KEY: apiKeyResp,
         DEEPLINE_CLAIM_TOKEN: ""
       }, baseUrl);
-      console.log(`Saved API key to ${envFilePath(baseUrl)}`);
+      savedApiKeyPath = envFilePath(baseUrl);
     }
   }
+  printCommandEnvelope({
+    ...payload,
+    ...savedApiKeyPath ? { saved_api_key_path: savedApiKeyPath } : {},
+    render: {
+      sections: [
+        {
+          title: "auth status",
+          lines: [
+            ...hostLines,
+            `Status: ${payload.status}`,
+            `Rate limit tier: ${payload.rateLimitTier}`,
+            ...payload.workspace.name ? [`Workspace: ${payload.workspace.name}`] : [],
+            ...payload.workspace.slug ? [`Workspace slug: ${payload.workspace.slug}`] : [],
+            ...payload.workspace.id != null ? [`Org ID: ${payload.workspace.id}`] : [],
+            ...payload.user.id != null ? [`User ID: ${payload.user.id}`] : [],
+            ...payload.examples.length > 0 ? ["Examples:", ...payload.examples.slice(0, 3).map((example) => `  ${String(example)}`)] : [],
+            ...savedApiKeyPath ? [`Saved API key to ${savedApiKeyPath}`] : []
+          ]
+        }
+      ]
+    }
+  }, { json: jsonOutput });
   return EXIT_OK;
 }
 function registerAuthCommands(program) {
@@ -2404,19 +2447,18 @@ import { stringify as stringify2 } from "csv-stringify/sync";
 function humanize(value) {
   return String(value || "").split("_").filter(Boolean).map((token) => token[0]?.toUpperCase() + token.slice(1)).join(" ") || "Unknown";
 }
-function printRecentUsage(entries) {
+function recentUsageLines(entries) {
   if (entries.length === 0) {
-    process.stdout.write("Recent activity: none yet\n");
-    return;
+    return ["Recent activity: none yet"];
   }
-  process.stdout.write("Recent activity:\n");
+  const lines = ["Recent activity:"];
   for (const entry of entries) {
     const op = `${humanize(entry.provider)} ${humanize(entry.operation)}`.trim();
     const charge = entry.billing_mode === "no_bill" ? "free" : `${entry.credits ?? 0} cr`;
     const status = entry.status || "completed";
-    process.stdout.write(`  ${op} | ${charge} | ${status} | ${entry.created_at || "unknown"}
-`);
+    lines.push(`${op} | ${charge} | ${status} | ${entry.created_at || "unknown"}`);
   }
+  return lines;
 }
 function summarizeLedgerRows(summary, rows) {
   const netDelta = rows.reduce((sum, row) => {
@@ -2469,49 +2511,49 @@ function defaultLedgerExportPath() {
 async function handleBalance(options) {
   const { http } = getAuthedHttpClient();
   const payload = await http.get("/api/v2/billing/balance");
-  if (shouldEmitJson(options.json)) return printJson(payload);
   const status = String(payload.balance_status || "");
-  if (status === "no_billing") {
-    process.stdout.write("Balance: 0 credits\n");
-    process.stdout.write("Billing: No billing account or payment method set up for this workspace.\n");
-    return;
-  }
-  process.stdout.write(`Balance: ${payload.balance ?? "(unknown)"} credits
-`);
+  const lines = status === "no_billing" ? [
+    "Balance: 0 credits",
+    "Billing: No billing account or payment method set up for this workspace."
+  ] : [`Balance: ${payload.balance ?? "(unknown)"} credits`];
+  printCommandEnvelope({
+    ...payload,
+    render: { sections: [{ title: "billing balance", lines }] }
+  }, { json: options.json });
+  return;
 }
 async function handleUsage(options) {
   const { http } = getAuthedHttpClient();
   const params = new URLSearchParams();
   if (options.limit) params.set("recent_limit", options.limit);
   if (options.offset) params.set("recent_offset", options.offset);
-  const suffix = params.size > 0 ? `?${params.toString()}` : "";
+  const suffix = Array.from(params).length > 0 ? `?${params.toString()}` : "";
   const payload = await http.get(`/api/v2/billing/usage${suffix}`);
-  if (shouldEmitJson(options.json)) return printJson(payload);
   const usage = payload.usage ?? {};
   const quota = payload.quota ?? {};
   const recent = payload.recent ?? {};
-  process.stdout.write(`Balance: ${payload.balance ?? "(unknown)"}
-`);
-  process.stdout.write(`Last 30 days spent: ${usage.month_spent_credits ?? "(unknown)"}
-`);
-  process.stdout.write(
-    `Monthly limit: ${quota.enabled ? quota.monthly_credits_limit ?? "(unknown)" : "off"}
-`
-  );
-  printRecentUsage(Array.isArray(recent.entries) ? recent.entries : []);
+  const lines = [
+    `Balance: ${payload.balance ?? "(unknown)"}`,
+    `Last 30 days spent: ${usage.month_spent_credits ?? "(unknown)"}`,
+    `Monthly limit: ${quota.enabled ? quota.monthly_credits_limit ?? "(unknown)" : "off"}`,
+    ...recentUsageLines(Array.isArray(recent.entries) ? recent.entries : [])
+  ];
+  printCommandEnvelope({
+    ...payload,
+    render: { sections: [{ title: "billing usage", lines }] }
+  }, { json: options.json });
 }
 async function handleLimit(options) {
   const { http } = getAuthedHttpClient();
   const payload = await http.get("/api/v2/billing/limit");
-  if (shouldEmitJson(options.json)) return printJson(payload);
-  if (payload.enabled) {
-    process.stdout.write(`Monthly limit: ${payload.monthly_credits_limit ?? "(unknown)"}
-`);
-    process.stdout.write(`Remaining before cap: ${payload.remaining_credits ?? "(unknown)"}
-`);
-    return;
-  }
-  process.stdout.write("Monthly limit: off\n");
+  const lines = payload.enabled ? [
+    `Monthly limit: ${payload.monthly_credits_limit ?? "(unknown)"}`,
+    `Remaining before cap: ${payload.remaining_credits ?? "(unknown)"}`
+  ] : ["Monthly limit: off"];
+  printCommandEnvelope({
+    ...payload,
+    render: { sections: [{ title: "billing limit", lines }] }
+  }, { json: options.json });
 }
 async function handleSetLimit(credits, options) {
   const { http } = getAuthedHttpClient();
@@ -2519,15 +2561,20 @@ async function handleSetLimit(credits, options) {
     method: "PUT",
     body: { monthly_credits_limit: Number.parseInt(credits, 10) }
   });
-  if (shouldEmitJson(options.json)) return printJson(payload);
-  process.stdout.write(`Monthly billing limit set to ${credits} credits.
-`);
+  printCommandEnvelope({
+    ...payload,
+    render: {
+      sections: [{ title: "billing limit", lines: [`Monthly billing limit set to ${credits} credits.`] }]
+    }
+  }, { json: options.json });
 }
 async function handleLimitOff(options) {
   const { http } = getAuthedHttpClient();
   const payload = await http.request("/api/v2/billing/limit", { method: "DELETE" });
-  if (shouldEmitJson(options.json)) return printJson(payload);
-  process.stdout.write("Monthly billing limit is now off.\n");
+  printCommandEnvelope({
+    ...payload,
+    render: { sections: [{ title: "billing limit", lines: ["Monthly billing limit is now off."] }] }
+  }, { json: options.json });
 }
 async function handleHistory(options) {
   const { http } = getAuthedHttpClient();
@@ -2546,13 +2593,20 @@ async function handleHistory(options) {
     };
   });
   const outputPath = await writeCsvRowsFile(`billing-history-${options.time}`, rows);
-  if (shouldEmitJson(options.json)) {
-    return printJson({ output_path: outputPath, row_count: rows.length, time_window: options.time });
-  }
-  process.stdout.write(`Billing history written to ${outputPath}
-`);
-  process.stdout.write(`${rows.length} row(s) exported.
-`);
+  printCommandEnvelope({
+    output_path: outputPath,
+    row_count: rows.length,
+    time_window: options.time,
+    render: {
+      sections: [
+        {
+          title: "billing history",
+          lines: [`Billing history written to ${outputPath}`, `${rows.length} row(s) exported.`]
+        }
+      ]
+    },
+    local: { output_path: outputPath }
+  }, { json: options.json });
 }
 async function handleLedgerExportAll(options) {
   const { http } = getAuthedHttpClient();
@@ -2584,20 +2638,25 @@ async function handleLedgerExportAll(options) {
     if (nextCursor === cursor) break;
     cursor = nextCursor;
   }
-  if (shouldEmitJson(options.json)) {
-    return printJson({
-      output_path: outputPath,
-      row_count: summary.row_count,
-      net_delta_credits: summary.net_delta_credits,
-      scope: "current_auth_context"
-    });
-  }
-  process.stdout.write(`Billing ledger written to ${outputPath}
-`);
-  process.stdout.write(`${summary.row_count} row(s) exported for the current auth context.
-`);
-  process.stdout.write(`Net ledger delta: ${summary.net_delta_credits} Deepline Credits
-`);
+  printCommandEnvelope({
+    output_path: outputPath,
+    row_count: summary.row_count,
+    net_delta_credits: summary.net_delta_credits,
+    scope: "current_auth_context",
+    render: {
+      sections: [
+        {
+          title: "billing ledger",
+          lines: [
+            `Billing ledger written to ${outputPath}`,
+            `${summary.row_count} row(s) exported for the current auth context.`,
+            `Net ledger delta: ${summary.net_delta_credits} Deepline Credits`
+          ]
+        }
+      ]
+    },
+    local: { output_path: outputPath }
+  }, { json: options.json });
 }
 async function handleCheckout(options) {
   const { http } = getAuthedHttpClient();
@@ -2606,20 +2665,22 @@ async function handleCheckout(options) {
     ...options.credits ? { credits: Number.parseInt(options.credits, 10) } : {},
     ...options.discountCode ? { discountCode: options.discountCode } : {}
   });
-  if (shouldEmitJson(options.json)) return printJson(payload);
   const url = String(payload.url || payload.checkout_url || "");
-  if (!options.noOpen && url) openInBrowser(url);
-  process.stdout.write(`${url || "Checkout session created."}
-`);
+  if (!options.json && !options.noOpen && url) openInBrowser(url);
+  printCommandEnvelope({
+    ...payload,
+    render: { sections: [{ title: "billing checkout", lines: [url || "Checkout session created."] }] }
+  }, { json: options.json });
 }
 async function handleRedeemCode(code, options) {
   const { http } = getAuthedHttpClient();
   const payload = await http.post("/api/v2/billing/checkout/verify", { code });
-  if (shouldEmitJson(options.json)) return printJson(payload);
   const url = String(payload.url || "");
-  if (!options.noOpen && url) openInBrowser(url);
-  process.stdout.write(`${url || "Code redeemed."}
-`);
+  if (!options.json && !options.noOpen && url) openInBrowser(url);
+  printCommandEnvelope({
+    ...payload,
+    render: { sections: [{ title: "billing code", lines: [url || "Code redeemed."] }] }
+  }, { json: options.json });
 }
 function registerBillingCommands(program) {
   const billing = program.command("billing").description("Inspect balance, usage, limits, and checkout flows.").addHelpText(
@@ -2821,6 +2882,25 @@ function isRecord2(value) {
 function isSerializedDataset(value) {
   return isRecord2(value) && value.kind === "dataset" && typeof value.count === "number" && Array.isArray(value.preview);
 }
+function pathParts(path) {
+  return path.split(".").map((part) => part.trim()).filter(Boolean);
+}
+function valueAtPath(root, path) {
+  let cursor = root;
+  for (const part of pathParts(path)) {
+    if (!isRecord2(cursor)) {
+      return void 0;
+    }
+    cursor = cursor[part];
+  }
+  return cursor;
+}
+function totalRowsForDataset(result, datasetPath) {
+  const metadata = isRecord2(result._metadata) ? result._metadata : null;
+  const parentPath = datasetPath.split(".").slice(0, -1).join(".");
+  const parent = parentPath ? valueAtPath({ result }, parentPath) : result;
+  return metadata?.totalRows ?? metadata?.rowCount ?? metadata?.count ?? (isRecord2(parent) ? parent.totalRows ?? parent.rowCount ?? parent.count : void 0) ?? result.totalRows ?? result.rowCount ?? result.count;
+}
 function rowArray(value) {
   if (!Array.isArray(value)) {
     return null;
@@ -2852,11 +2932,81 @@ function inferColumns(rows) {
   }
   return columns;
 }
-function extractCanonicalRowsInfo(statusOrResult) {
+function canonicalRowsInfoFromCandidate(input) {
+  const candidate = input;
+  if (isSerializedDataset(candidate.value)) {
+    const rawRows = rowArray(candidate.value.preview) ?? [];
+    const totalRows2 = readNumber(candidate.value.count) ?? rawRows.length;
+    const hasExplicitColumns = Array.isArray(candidate.value.columns) && candidate.value.columns.every((column) => typeof column === "string");
+    const rawColumns = hasExplicitColumns ? candidate.value.columns : inferColumns(rawRows);
+    const { rows: rows2, columns } = sanitizeCsvProjectionInfo({
+      rows: rawRows,
+      columns: rawColumns
+    });
+    return {
+      rows: rows2,
+      totalRows: totalRows2,
+      columns,
+      columnsExplicit: hasExplicitColumns,
+      complete: rows2.length === totalRows2,
+      source: candidate.source,
+      datasetId: typeof candidate.value.datasetId === "string" ? candidate.value.datasetId : null,
+      tableNamespace: typeof candidate.value.tableNamespace === "string" ? candidate.value.tableNamespace : null
+    };
+  }
+  if (candidate.serializedOnly) {
+    return null;
+  }
+  const rows = rowArray(candidate.value);
+  if (!rows) {
+    return null;
+  }
+  const totalRows = readNumber(candidate.total) ?? rows.length;
+  const sanitized = sanitizeCsvProjectionInfo({
+    rows,
+    columns: inferColumns(rows)
+  });
+  return {
+    rows: sanitized.rows,
+    totalRows,
+    columns: sanitized.columns,
+    complete: rows.length === totalRows,
+    source: candidate.source
+  };
+}
+function collectDatasetCandidates(input) {
+  if (input.depth && input.depth > 16) {
+    return;
+  }
+  if (isSerializedDataset(input.value)) {
+    input.output.push({
+      source: input.path,
+      value: input.value,
+      total: input.total
+    });
+    return;
+  }
+  if (!isRecord2(input.value)) {
+    return;
+  }
+  for (const [key, child] of Object.entries(input.value)) {
+    if (key === "preview" || key === "access") {
+      continue;
+    }
+    collectDatasetCandidates({
+      value: child,
+      path: `${input.path}.${key}`,
+      total: totalRowsForDataset(input.value, `${input.path}.${key}`),
+      output: input.output,
+      depth: (input.depth ?? 0) + 1
+    });
+  }
+}
+function collectCanonicalRowsInfos(statusOrResult) {
   const root = isRecord2(statusOrResult) ? statusOrResult : null;
   const result = isRecord2(root?.result) ? root.result : root;
   if (!result) {
-    return null;
+    return [];
   }
   const metadata = isRecord2(result._metadata) ? result._metadata : null;
   const totalFromMetadata = metadata?.totalRows ?? metadata?.rowCount ?? metadata?.count;
@@ -2876,41 +3026,57 @@ function extractCanonicalRowsInfo(statusOrResult) {
       { source: "result.output.results", value: result.output.results, total: outputTotalFromMetadata ?? result.output.totalRows ?? result.output.rowCount ?? result.output.count }
     );
   }
+  collectDatasetCandidates({
+    value: result,
+    path: "result",
+    total: totalFromMetadata,
+    output: candidates
+  });
+  const seen = /* @__PURE__ */ new Set();
+  const infos = [];
   for (const candidate of candidates) {
-    if (isSerializedDataset(candidate.value)) {
-      const rawRows = rowArray(candidate.value.preview) ?? [];
-      const totalRows2 = readNumber(candidate.value.count) ?? rawRows.length;
-      const rawColumns = Array.isArray(candidate.value.columns) && candidate.value.columns.every((column) => typeof column === "string") ? candidate.value.columns : inferColumns(rawRows);
-      const { rows: rows2, columns } = sanitizeCsvProjectionInfo({
-        rows: rawRows,
-        columns: rawColumns
-      });
-      return {
-        rows: rows2,
-        totalRows: totalRows2,
-        columns,
-        complete: rows2.length === totalRows2,
-        source: candidate.source
-      };
+    if (seen.has(candidate.source)) {
+      continue;
+    }
+    seen.add(candidate.source);
+    const info = canonicalRowsInfoFromCandidate(candidate);
+    if (info) {
+      infos.push(info);
     }
-    const rows = rowArray(candidate.value);
-    if (!rows) {
+  }
+  return infos;
+}
+function collectSerializedDatasetRowsInfos(statusOrResult) {
+  const root = isRecord2(statusOrResult) ? statusOrResult : null;
+  const result = isRecord2(root?.result) ? root.result : root;
+  if (!result) {
+    return [];
+  }
+  const candidates = [];
+  collectDatasetCandidates({
+    value: result,
+    path: "result",
+    output: candidates
+  });
+  const seen = /* @__PURE__ */ new Set();
+  const infos = [];
+  for (const candidate of candidates) {
+    if (seen.has(candidate.source)) {
       continue;
     }
-    const totalRows = readNumber(candidate.total) ?? rows.length;
-    const sanitized = sanitizeCsvProjectionInfo({
-      rows,
-      columns: inferColumns(rows)
+    seen.add(candidate.source);
+    const info = canonicalRowsInfoFromCandidate({
+      ...candidate,
+      serializedOnly: true
     });
-    return {
-      rows: sanitized.rows,
-      totalRows,
-      columns: sanitized.columns,
-      complete: rows.length === totalRows,
-      source: candidate.source
-    };
+    if (info) {
+      infos.push(info);
+    }
   }
-  return null;
+  return infos;
+}
+function extractCanonicalRowsInfo(statusOrResult) {
+  return collectCanonicalRowsInfos(statusOrResult)[0] ?? null;
 }
 function percentText(numerator, denominator) {
   return denominator > 0 ? `${numerator}/${denominator} (${Math.round(100 * numerator / denominator)}%)` : "0/0 (0%)";
@@ -3237,7 +3403,7 @@ function formatCell(value) {
   const text = typeof value === "object" ? JSON.stringify(value) : String(value);
   return text.length > 80 ? `${text.slice(0, 77)}...` : text;
 }
-function printTable(result) {
+function tableLines(result) {
   const rows = result.rows.filter(
     (row) => Boolean(row) && typeof row === "object" && !Array.isArray(row)
   );
@@ -3245,17 +3411,17 @@ function printTable(result) {
   const businessColumns = responseColumns.filter((column) => !column.startsWith("_"));
   const columns = businessColumns.length > 0 ? businessColumns : responseColumns;
   const hiddenColumns = responseColumns.filter((column) => !columns.includes(column));
-  console.log(
+  const lines = [
     `${result.command} returned ${result.row_count_returned} row(s)` + (result.truncated ? " (truncated)" : "")
-  );
+  ];
   if (hiddenColumns.length > 0) {
-    console.log(
+    lines.push(
       `Showing ${columns.length}/${responseColumns.length} columns; hidden metadata: ${hiddenColumns.join(", ")}`
     );
-    console.log("Use --json or select metadata columns explicitly when you need run ids/errors/stages.");
+    lines.push("Use --json or select metadata columns explicitly when you need run ids/errors/stages.");
   }
   if (rows.length === 0) {
-    return;
+    return lines;
   }
   const widths = columns.map(
     (column) => Math.min(
@@ -3266,13 +3432,14 @@ function printTable(result) {
       )
     )
   );
-  console.log(columns.map((column, index) => column.padEnd(widths[index])).join("  "));
-  console.log(widths.map((width) => "-".repeat(width)).join("  "));
+  lines.push(columns.map((column, index) => column.padEnd(widths[index])).join("  "));
+  lines.push(widths.map((width) => "-".repeat(width)).join("  "));
   for (const row of rows) {
-    console.log(
+    lines.push(
       columns.map((column, index) => formatCell(row[column]).padEnd(widths[index])).join("  ")
     );
   }
+  return lines;
 }
 async function handleDbQuery(args) {
   const sqlIndex = args.indexOf("--sql");
@@ -3286,18 +3453,18 @@ async function handleDbQuery(args) {
   const jsonOutput = argsWantJson(args);
   const client = new DeeplineClient();
   const result = await client.queryCustomerDb({ sql, maxRows });
-  if (jsonOutput) {
-    process.stdout.write(`${JSON.stringify(result)}
-`);
-    return 0;
-  }
-  printTable(result);
-  console.error(
-    `Tool equivalent: deepline tools execute query_customer_db --payload ${JSON.stringify({
-      sql,
-      ...maxRows ? { max_rows: maxRows } : {}
-    })} --json`
-  );
+  const toolCommand = `deepline tools execute query_customer_db --payload ${JSON.stringify({
+    sql,
+    ...maxRows ? { max_rows: maxRows } : {}
+  })} --json`;
+  printCommandEnvelope({
+    ...result,
+    next: { toolEquivalent: toolCommand },
+    render: {
+      sections: [{ title: "customer db query", lines: tableLines(result) }],
+      actions: [{ label: "Tool equivalent", command: toolCommand }]
+    }
+  }, { json: jsonOutput });
   return 0;
 }
 function registerDbCommands(program) {
@@ -3345,11 +3512,12 @@ async function handleFeedback(text, options) {
     ...options.command ? { command: options.command } : {},
     ...options.payload ? { payload: options.payload } : {}
   });
-  if (shouldEmitJson(options.json)) {
-    printJson(response);
-    return;
-  }
-  process.stdout.write("Feedback submitted. Thank you.\n");
+  printCommandEnvelope({
+    ...response,
+    render: {
+      sections: [{ title: "feedback", lines: ["Feedback submitted. Thank you."] }]
+    }
+  }, { json: options.json });
 }
 function registerFeedbackCommands(program) {
   const feedback = program.command("feedback").description("Submit CLI feedback to Deepline.").addHelpText(
@@ -3381,37 +3549,37 @@ Examples:
 async function fetchOrganizations(http, apiKey) {
   return http.post("/api/v2/auth/cli/organizations", { api_key: apiKey });
 }
-function printOrgList(orgs) {
-  for (const [index, org] of orgs.entries()) {
+function orgListLines(orgs) {
+  return orgs.map((org, index) => {
     const current = org.is_current ? " (current)" : "";
     const role = org.role ? ` [${org.role}]` : "";
-    process.stdout.write(`  ${index + 1}. ${org.name}${role}${current}
-`);
-  }
+    return `${index + 1}. ${org.name}${role}${current}`;
+  });
 }
 async function handleOrgList(options) {
   const config = resolveConfig();
   const http = new HttpClient(config);
   const payload = await fetchOrganizations(http, config.apiKey);
-  if (shouldEmitJson(options.json)) {
-    printJson(payload);
-    return;
-  }
-  process.stdout.write("Your organizations:\n");
-  printOrgList(payload.organizations);
+  printCommandEnvelope({
+    ...payload,
+    render: {
+      sections: [{ title: "Your organizations:", lines: orgListLines(payload.organizations) }]
+    }
+  }, { json: options.json });
 }
 async function handleOrgSwitch(selection, options) {
   const config = resolveConfig();
   const http = new HttpClient(config);
   const payload = await fetchOrganizations(http, config.apiKey);
   if (!selection && !options.orgId) {
-    if (shouldEmitJson(options.json)) {
-      printJson(payload);
-      return;
-    }
-    process.stdout.write("Your organizations:\n");
-    printOrgList(payload.organizations);
-    process.stdout.write("\nRun: deepline org switch <number>\n");
+    printCommandEnvelope({
+      ...payload,
+      next: { switch: "deepline org switch <number>" },
+      render: {
+        sections: [{ title: "Your organizations:", lines: orgListLines(payload.organizations) }],
+        actions: [{ label: "Run", command: "deepline org switch <number>" }]
+      }
+    }, { json: options.json });
     return;
   }
   let target = payload.organizations.find((org) => org.org_id === options.orgId);
@@ -3427,12 +3595,12 @@ async function handleOrgSwitch(selection, options) {
     throw new Error("Could not resolve the selected organization.");
   }
   if (target.is_current) {
-    if (shouldEmitJson(options.json)) {
-      printJson({ ok: true, unchanged: true, organization: target });
-      return;
-    }
-    process.stdout.write(`Already on ${target.name}.
-`);
+    printCommandEnvelope({
+      ok: true,
+      unchanged: true,
+      organization: target,
+      render: { sections: [{ title: "org switch", lines: [`Already on ${target.name}.`] }] }
+    }, { json: options.json });
     return;
   }
   const switched = await http.post(
@@ -3444,14 +3612,24 @@ async function handleOrgSwitch(selection, options) {
     DEEPLINE_ACTIVE_ORG_ID: switched.org_id,
     DEEPLINE_ACTIVE_ORG_NAME: switched.org_name
   });
-  if (shouldEmitJson(options.json)) {
-    printJson({ ok: true, host_env_path: hostEnvFilePath(config.baseUrl), ...switched });
-    return;
-  }
-  process.stdout.write(`Switched to ${switched.org_name}.
-`);
-  process.stdout.write(`Saved host auth in ${hostEnvFilePath(config.baseUrl)}
-`);
+  const { api_key: _apiKey, ...publicSwitched } = switched;
+  printCommandEnvelope({
+    ok: true,
+    host_env_path: hostEnvFilePath(config.baseUrl),
+    ...publicSwitched,
+    api_key_saved: true,
+    render: {
+      sections: [
+        {
+          title: "org switch",
+          lines: [
+            `Switched to ${switched.org_name}.`,
+            `Saved host auth in ${hostEnvFilePath(config.baseUrl)}`
+          ]
+        }
+      ]
+    }
+  }, { json: options.json });
 }
 function registerOrgCommands(program) {
   const org = program.command("org").description("List and switch organizations.").addHelpText(
@@ -5134,6 +5312,9 @@ function traceCliSync(phase, fields, run) {
     throw error;
   }
 }
+function sleep4(ms) {
+  return new Promise((resolve10) => setTimeout(resolve10, ms));
+}
 function parseReferencedPlayTarget(target) {
   const trimmed = target.trim();
   const slashIndex = trimmed.indexOf("/");
@@ -5358,15 +5539,6 @@ function fileInputBindingsFromStaticPipeline(staticPipeline) {
   );
   return inputField ? [{ inputPath: inputField }] : [];
 }
-function applyCsvShortcutInput(input) {
-  const csvValue = getDottedInputValue(input.runtimeInput, "csv");
-  if (csvValue == null || csvValue === "") return;
-  const candidate = input.bindings.find((binding) => binding.inputPath !== "csv")?.inputPath ?? input.fallbackInputPath ?? null;
-  if (!candidate || candidate === "csv") return;
-  const existing = getDottedInputValue(input.runtimeInput, candidate);
-  if (existing != null && existing !== "") return;
-  setDottedInputValue(input.runtimeInput, candidate, csvValue);
-}
 function isLocalFilePathValue(value) {
   if (typeof value !== "string" || !value.trim()) return false;
   if (/^[a-z][a-z0-9+.-]*:\/\//i.test(value.trim())) return false;
@@ -6034,25 +6206,38 @@ function formatReturnValue(result) {
   }
   return lines;
 }
-function buildOutputSummary(rowsInfo, runId, exportedPath) {
-  if (!rowsInfo) {
-    return exportedPath ? { csv_path: exportedPath } : null;
+function isDatasetHandle(value) {
+  return Boolean(
+    value && typeof value === "object" && !Array.isArray(value) && value.kind === "dataset"
+  );
+}
+function collectDatasetHandleLines(value, path = "result") {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return [];
   }
-  const isPartial = !rowsInfo.complete;
-  return {
-    kind: "rows",
-    rowCount: rowsInfo.totalRows,
-    previewRowCount: rowsInfo.rows.length,
-    ...isPartial ? {
-      isPartial: true,
-      previewCount: rowsInfo.rows.length,
-      totalCount: rowsInfo.totalRows
-    } : { isPartial: false },
-    complete: rowsInfo.complete,
-    columns: rowsInfo.columns,
-    source: rowsInfo.source,
-    ...exportedPath ? { csv_path: exportedPath } : {}
-  };
+  if (isDatasetHandle(value)) {
+    const record = value;
+    const count = typeof record.count === "number" ? record.count : typeof record.rowCount === "number" ? record.rowCount : null;
+    const preview = Array.isArray(record.preview) ? record.preview : [];
+    const lines2 = [
+      `  dataset ${typeof record.path === "string" ? record.path : path}: rows=${count === null ? "-" : formatInteger(count)} preview=${formatInteger(preview.length)}`
+    ];
+    if (typeof record.queryDatasetCommand === "string") {
+      lines2.push(`  query dataset: ${record.queryDatasetCommand}`);
+    }
+    if (typeof record.slowExportAsCsvCommand === "string") {
+      lines2.push(`  export CSV: ${record.slowExportAsCsvCommand}`);
+    }
+    return lines2;
+  }
+  const lines = [];
+  for (const [key, child] of Object.entries(value)) {
+    if (key === "preview" || key === "access") {
+      continue;
+    }
+    lines.push(...collectDatasetHandleLines(child, `${path}.${key}`));
+  }
+  return lines;
 }
 function buildRunWarnings(status, rowsInfo) {
   if (status.status === "completed" && rowsInfo?.totalRows === 0) {
@@ -6065,19 +6250,12 @@ function buildRunWarnings(status, rowsInfo) {
   }
   return [];
 }
-function buildRunNextCommands(runId, rowsInfo) {
-  const commands = {
+function buildRunNextCommands(runId) {
+  return {
     get: `deepline runs get ${runId} --json`,
     stop: `deepline runs stop ${runId} --reason "stale lock" --json`,
     logs: `deepline runs logs ${runId} --out run.log --json`
   };
-  if (!rowsInfo || rowsInfo.complete) {
-    commands.exportCsv = buildRunExportCommand(runId);
-  }
-  return commands;
-}
-function buildRunExportCommand(runId) {
-  return `deepline runs export ${runId} --out output.csv`;
 }
 var RUN_LOG_PREVIEW_LIMIT = 20;
 function getRecordField(value, key) {
@@ -6132,31 +6310,6 @@ function normalizeProgressForEnvelope(status, rowsInfo) {
     wait: status.wait ?? null
   };
 }
-function normalizeOutputsForEnvelope(rowsInfo, runId, exportedPath) {
-  if (!rowsInfo) {
-    return exportedPath ? [{ name: "output", kind: "file", path: exportedPath }] : [];
-  }
-  const isPartial = !rowsInfo.complete;
-  return [
-    {
-      name: "rows",
-      kind: "dataset",
-      rowCount: rowsInfo.totalRows,
-      columns: rowsInfo.columns,
-      preview: rowsInfo.rows.slice(0, 5),
-      previewRowCount: Math.min(rowsInfo.rows.length, 5),
-      previewLimit: 5,
-      ...isPartial ? {
-        isPartial: true,
-        previewCount: rowsInfo.rows.length,
-        totalCount: rowsInfo.totalRows
-      } : { isPartial: false },
-      complete: rowsInfo.complete,
-      source: rowsInfo.source,
-      ...exportedPath ? { csv_path: exportedPath } : {}
-    }
-  ];
-}
 function normalizeStepsForEnvelope(status) {
   const directSteps = getRecordField(status, "steps");
   if (Array.isArray(directSteps)) {
@@ -6241,23 +6394,17 @@ function compactPlayStatus(status, options) {
     status: status.status,
     run: normalizeRunStatusForEnvelope(status),
     progress: normalizeProgressForEnvelope(status, rowsInfo),
-    outputs: normalizeOutputsForEnvelope(
-      rowsInfo,
-      status.runId,
-      options?.exportedPath
-    ),
     steps: normalizeStepsForEnvelope(status),
     errors: normalizeErrorsForEnvelope(status, error),
     logs: normalizeLogsForEnvelope(status),
     ...error ? { error } : {},
     ...warnings.length > 0 ? { warnings } : {},
-    output: buildOutputSummary(rowsInfo, status.runId, options?.exportedPath) ?? result ?? null,
     ...result !== void 0 ? { result } : {},
+    ...options?.exportedPath ? { local: { csv_path: options.exportedPath } } : {},
     ...status.resultView ? { resultView: status.resultView } : {},
     ...datasetStats ? { dataset_stats: datasetStats } : {},
-    ...rowsInfo ? { previewRows: rowsInfo.rows.slice(0, 5) } : {},
     ...billing ? { billing } : {},
-    next: buildRunNextCommands(status.runId, rowsInfo)
+    next: buildRunNextCommands(status.runId)
   };
 }
 function enrichPlayStatusWithDatasetStats(status) {
@@ -6295,12 +6442,20 @@ function formatDatasetStatsLines(datasetStats) {
 }
 function writePlayResult(status, jsonOutput, options) {
   if (jsonOutput) {
-    process.stdout.write(
-      `${JSON.stringify(
-        options?.fullJson ? enrichPlayStatusWithDatasetStats(status) : compactPlayStatus(status, options)
-      )}
-`
-    );
+    const payload2 = options?.fullJson ? enrichPlayStatusWithDatasetStats(status) : compactPlayStatus(status, options);
+    printCommandEnvelope({
+      ...payload2,
+      render: {
+        sections: [
+          {
+            title: "run result",
+            lines: [
+              `${status.status ?? "running"}  ${status.runId ?? "unknown"}`
+            ]
+          }
+        ]
+      }
+    }, { json: true });
     return;
   }
   const result = status.result;
@@ -6317,22 +6472,8 @@ function writePlayResult(status, jsonOutput, options) {
     rowsInfo.columns,
     extractDatasetExecutionStats(status)
   ) : null;
-  const outputSummary = buildOutputSummary(
-    rowsInfo,
-    runId,
-    options?.exportedPath
-  );
-  if (outputSummary) {
-    const columns = Array.isArray(outputSummary.columns) ? outputSummary.columns.length : 0;
-    const path = typeof outputSummary.csv_path === "string" ? `  file=${outputSummary.csv_path}` : "";
-    lines.push(
-      `  output: rows=${formatInteger(outputSummary.rowCount)}  columns=${formatInteger(columns)}${path}`
-    );
-    if (outputSummary.isPartial === true) {
-      lines.push(
-        `  partial output: showing ${formatInteger(outputSummary.previewCount)} preview row(s) of ${formatInteger(outputSummary.totalCount)}`
-      );
-    }
+  if (options?.exportedPath) {
+    lines.push(`  exported CSV: file=${options.exportedPath}`);
   }
   for (const warning of warnings) {
     lines.push(`  warning: ${warning}`);
@@ -6345,29 +6486,184 @@ function writePlayResult(status, jsonOutput, options) {
   const renderedServerView = renderServerResultView(status.resultView);
   if (result) {
     lines.push(...formatReturnValue(result));
+    lines.push(...collectDatasetHandleLines(result));
   }
   if (renderedServerView.lines.length > 0) {
     lines.push(...renderedServerView.lines);
   }
   lines.push(...renderedServerView.actions);
-  console.log(lines.join("\n"));
+  const payload = options?.fullJson ? enrichPlayStatusWithDatasetStats(status) : compactPlayStatus(status, options);
+  printCommandEnvelope({
+    ...payload,
+    render: {
+      sections: [{ title: "run result", lines }]
+    }
+  }, { json: jsonOutput, text: `${lines.join("\n")}
+` });
+}
+var RUN_EXPORT_PAGE_SIZE = 5e3;
+var PLAY_RUN_OUT_EXPORT_ATTEMPTS = 8;
+var PLAY_RUN_OUT_EXPORT_RETRY_DELAY_MS = 1e3;
+function shellSingleQuote(value) {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+function runExportRetryCommand(runId, outPath, datasetPath) {
+  return `deepline runs export ${runId}${datasetPath ? ` --dataset ${shellSingleQuote(datasetPath)}` : ""} --out ${shellSingleQuote(resolve8(outPath))}`;
+}
+function extractRunPlayName(status) {
+  const run = status.run;
+  const candidates = [
+    status.playName,
+    status.name,
+    getRecordField(run, "playName"),
+    getRecordField(run, "name")
+  ];
+  for (const candidate of candidates) {
+    if (typeof candidate === "string" && candidate.trim()) {
+      return candidate.trim();
+    }
+  }
+  return null;
 }
-function exportPlayStatusRows(status, outPath) {
+function exportableSheetRow(row) {
+  if (!row || typeof row !== "object" || Array.isArray(row)) {
+    return null;
+  }
+  const record = row;
+  const data = record.data;
+  if (data && typeof data === "object" && !Array.isArray(data)) {
+    return data;
+  }
+  const fallback = { ...record };
+  for (const key of [
+    "key",
+    "status",
+    "cellMeta",
+    "inputIndex",
+    "runId",
+    "error",
+    "stage",
+    "provider",
+    "seq",
+    "createdAt",
+    "updatedAt"
+  ]) {
+    delete fallback[key];
+  }
+  return fallback;
+}
+async function fetchBackingDatasetRows(input) {
+  const playName = extractRunPlayName(input.status);
+  const tableNamespace = input.rowsInfo.tableNamespace?.trim();
+  if (!playName || !tableNamespace) {
+    return null;
+  }
+  const sheetRows = [];
+  let offset = 0;
+  let expectedTotal = input.rowsInfo.totalRows;
+  while (true) {
+    const page = await input.client.runs.exportDatasetRows({
+      playName,
+      tableNamespace,
+      runId: input.status.runId,
+      limit: RUN_EXPORT_PAGE_SIZE,
+      offset
+    });
+    sheetRows.push(...page.rows);
+    const summaryTotal = page.summary?.stats?.total;
+    if (typeof summaryTotal === "number" && Number.isFinite(summaryTotal)) {
+      expectedTotal = Math.max(expectedTotal, Math.trunc(summaryTotal));
+    }
+    if (page.rows.length < RUN_EXPORT_PAGE_SIZE || sheetRows.length >= expectedTotal) {
+      break;
+    }
+    offset += page.rows.length;
+  }
+  const rows = sheetRows.map(exportableSheetRow).filter((row) => Boolean(row));
+  if (rows.length < input.rowsInfo.totalRows) {
+    return null;
+  }
+  const columns = input.rowsInfo.columnsExplicit && input.rowsInfo.columns.length ? input.rowsInfo.columns : [...new Set(rows.flatMap((row) => Object.keys(row)))];
+  return {
+    ...input.rowsInfo,
+    rows,
+    columns,
+    totalRows: rows.length,
+    complete: true,
+    source: `${input.rowsInfo.source ?? "result.rows"} -> /api/v2/plays/${playName}/sheet?tableNamespace=${tableNamespace}`
+  };
+}
+async function exportPlayStatusRows(client, status, outPath, options = {}) {
   if (!outPath) {
     return null;
   }
-  const rowsInfo = extractCanonicalRowsInfo(status);
+  const availableRows = collectSerializedDatasetRowsInfos(status);
+  let rowsInfo = options.datasetPath ? availableRows.find((info) => info.source === options.datasetPath) ?? null : availableRows.length === 1 ? availableRows[0] : null;
+  if (!rowsInfo && options.datasetPath) {
+    const available = availableRows.map((info) => info.source).filter((source) => typeof source === "string");
+    throw new DeeplineError(
+      `Run ${status.runId} did not return a dataset at ${options.datasetPath}.` + (available.length > 0 ? ` Available datasets: ${available.join(", ")}.` : ""),
+      void 0,
+      "RUN_EXPORT_DATASET_NOT_FOUND",
+      { runId: status.runId, dataset: options.datasetPath, available }
+    );
+  }
+  if (!options.datasetPath && availableRows.length > 1) {
+    const available = availableRows.map((info) => info.source).filter((source) => typeof source === "string");
+    throw new DeeplineError(
+      `Run ${status.runId} returned multiple datasets. Choose one with --dataset <path>: ${available.join(", ")}.`,
+      void 0,
+      "RUN_EXPORT_DATASET_REQUIRED",
+      { runId: status.runId, available }
+    );
+  }
   if (!rowsInfo) {
     throw new DeeplineError(
       `Run ${status.runId} did not expose a row-shaped final output to export.`
     );
   }
+  const attempts = Math.max(1, Math.trunc(options.attempts ?? 1));
+  const retryDelayMs = Math.max(0, Math.trunc(options.retryDelayMs ?? 0));
+  for (let attempt = 1; attempt <= attempts; attempt += 1) {
+    if (rowsInfo.complete) {
+      return { path: writeCanonicalRowsCsv(rowsInfo, outPath), rowsInfo };
+    }
+    const fetchedRowsInfo = await fetchBackingDatasetRows({
+      client,
+      status,
+      rowsInfo
+    });
+    if (fetchedRowsInfo?.complete) {
+      return {
+        path: writeCanonicalRowsCsv(fetchedRowsInfo, outPath),
+        rowsInfo: fetchedRowsInfo
+      };
+    }
+    if (attempt < attempts && retryDelayMs > 0) {
+      await sleep4(retryDelayMs);
+    }
+  }
   if (!rowsInfo.complete) {
+    const retryCommand = runExportRetryCommand(
+      status.runId,
+      outPath,
+      options.datasetPath ?? rowsInfo.source
+    );
     throw new DeeplineError(
-      `Run output only includes ${rowsInfo.rows.length} preview row(s) of ${rowsInfo.totalRows}; full dataset export is not available from this status response yet.`
+      `Run output only includes ${rowsInfo.rows.length} preview row(s) of ${rowsInfo.totalRows}; the backing dataset was not ready to export yet. Retry with: ${retryCommand}`,
+      void 0,
+      "RUN_EXPORT_NOT_READY",
+      {
+        runId: status.runId,
+        previewRowCount: rowsInfo.rows.length,
+        totalRows: rowsInfo.totalRows,
+        tableNamespace: rowsInfo.tableNamespace ?? null,
+        dataset: options.datasetPath ?? rowsInfo.source,
+        retry_command: retryCommand
+      }
     );
   }
-  return writeCanonicalRowsCsv(rowsInfo, outPath);
+  return { path: writeCanonicalRowsCsv(rowsInfo, outPath), rowsInfo };
 }
 function renderServerResultView(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
@@ -6441,8 +6737,10 @@ function writeStartedPlayRun(input) {
     dashboardUrl: input.dashboardUrl
   };
   if (input.jsonOutput) {
-    process.stdout.write(`${JSON.stringify(payload)}
-`);
+    printCommandEnvelope({
+      ...payload,
+      render: { sections: [{ title: "play run", lines: [`Started ${input.playName}`, `run id: ${input.runId}`] }] }
+    }, { json: true });
     return;
   }
   const lines = [
@@ -6461,10 +6759,14 @@ function writeStartedPlayRun(input) {
     input.progress.writeLine(output, process.stdout);
     return;
   }
-  console.log(output);
+  printCommandEnvelope({
+    ...payload,
+    render: { sections: [{ title: "play run", lines }] }
+  }, { json: false, text: `${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]\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.";
+  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 --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;
@@ -6534,6 +6836,11 @@ function parsePlayRunOptions(args) {
       }
       continue;
     }
+    if (arg === "--csv" || arg.startsWith("--csv=")) {
+      throw new Error(
+        `--csv is not a plays run flag. Pass CSV paths through --input, for example: deepline plays run my.play.ts --input '{"file":"leads.csv"}' --watch`
+      );
+    }
     if (arg.startsWith("--")) {
       const { path, value } = parseInputFieldFlag(arg, args[index + 1]);
       input ??= {};
@@ -6719,11 +7026,6 @@ async function handleFileBackedRun(options) {
   const fileInputBindings = fileInputBindingsFromStaticPipeline(
     compilerManifest.staticPipeline
   );
-  applyCsvShortcutInput({
-    runtimeInput,
-    bindings: fileInputBindings,
-    fallbackInputPath: "file"
-  });
   const stagedFileInputs = await traceCliSpan(
     "cli.play_stage_inputs",
     {
@@ -6765,10 +7067,13 @@ async function handleFileBackedRun(options) {
         progress
       })
     );
-    const exportedPath = traceCliSync(
+    const exportResult = await traceCliSpan(
       "cli.play_export_rows",
       { targetKind: "file", playName },
-      () => exportPlayStatusRows(finalStatus, options.outPath)
+      () => exportPlayStatusRows(client, finalStatus, options.outPath, {
+        attempts: PLAY_RUN_OUT_EXPORT_ATTEMPTS,
+        retryDelayMs: PLAY_RUN_OUT_EXPORT_RETRY_DELAY_MS
+      })
     );
     if (finalStatus.status === "completed") {
       progress.complete();
@@ -6778,7 +7083,7 @@ async function handleFileBackedRun(options) {
     traceCliSync(
       "cli.play_write_result",
       { targetKind: "file", playName },
-      () => writePlayResult(finalStatus, options.jsonOutput, { exportedPath })
+      () => writePlayResult(finalStatus, options.jsonOutput, { exportedPath: exportResult?.path ?? null })
     );
     return finalStatus.status === "completed" ? 0 : 1;
   }
@@ -6868,10 +7173,6 @@ async function handleNamedRun(options) {
     ...fileInputBindingsFromPlaySchema(playDetail.play.inputSchema),
     ...fileInputBindingsFromStaticPipeline(playDetail.play.staticPipeline)
   ] : [];
-  applyCsvShortcutInput({
-    runtimeInput,
-    bindings: fileInputBindings
-  });
   const stagedFileInputs = await traceCliSpan(
     "cli.play_stage_inputs",
     {
@@ -6910,10 +7211,13 @@ async function handleNamedRun(options) {
         progress
       })
     );
-    const exportedPath = traceCliSync(
+    const exportResult = await traceCliSpan(
       "cli.play_export_rows",
       { targetKind: "name", playName },
-      () => exportPlayStatusRows(finalStatus, options.outPath)
+      () => exportPlayStatusRows(client, finalStatus, options.outPath, {
+        attempts: PLAY_RUN_OUT_EXPORT_ATTEMPTS,
+        retryDelayMs: PLAY_RUN_OUT_EXPORT_RETRY_DELAY_MS
+      })
     );
     if (finalStatus.status === "completed") {
       progress.complete();
@@ -6923,7 +7227,7 @@ async function handleNamedRun(options) {
     traceCliSync(
       "cli.play_write_result",
       { targetKind: "name", playName },
-      () => writePlayResult(finalStatus, options.jsonOutput, { exportedPath })
+      () => writePlayResult(finalStatus, options.jsonOutput, { exportedPath: exportResult?.path ?? null })
     );
     return finalStatus.status === "completed" ? 0 : 1;
   }
@@ -6992,7 +7296,7 @@ function parseRunIdPositional(args, usage) {
       }
       continue;
     }
-    if ((arg === "--out" || arg === "--reason") && args[index + 1]) {
+    if ((arg === "--out" || arg === "--reason" || arg === "--dataset") && args[index + 1]) {
       index += 1;
       continue;
     }
@@ -7054,26 +7358,15 @@ async function handleRunsList(args) {
     executionTime: run.executionTime,
     playName: run.memo?.playName ?? playName
   }));
-  if (argsWantJson(args)) {
-    process.stdout.write(
-      `${JSON.stringify({
-        runs,
-        count: runs.length,
-        next: {
-          get: runs[0]?.runId ? `deepline runs get ${runs[0].runId} --json` : null
-        }
-      })}
-`
-    );
-  } else {
-    if (runs.length === 0) {
-      console.log(`No runs found for ${playName}.`);
-    } else {
-      for (const run of runs) {
-        console.log(`${run.runId} ${run.status} ${formatTimestamp(run.startedAt)}`);
-      }
-    }
-  }
+  const lines = runs.length === 0 ? [`No runs found for ${playName}.`] : runs.map((run) => `${run.runId} ${run.status} ${formatTimestamp(run.startedAt)}`);
+  printCommandEnvelope({
+    runs,
+    count: runs.length,
+    next: {
+      get: runs[0]?.runId ? `deepline runs get ${runs[0].runId} --json` : null
+    },
+    render: { sections: [{ title: "runs", lines }] }
+  }, { json: argsWantJson(args) });
   return 0;
 }
 async function handleRunTail(args) {
@@ -7127,41 +7420,30 @@ async function handleRunLogs(args) {
   const logs = status.progress?.logs ?? [];
   if (outPath) {
     writeFileSync5(outPath, `${logs.join("\n")}${logs.length > 0 ? "\n" : ""}`);
-    if (argsWantJson(args)) {
-      process.stdout.write(
-        `${JSON.stringify({
-          runId: status.runId,
-          log_path: outPath,
-          lineCount: logs.length
-        })}
-`
-      );
-    } else {
-      console.log(`Wrote ${logs.length} log lines to ${outPath}`);
-    }
+    printCommandEnvelope({
+      runId: status.runId,
+      log_path: outPath,
+      lineCount: logs.length,
+      local: { log_path: outPath },
+      render: { sections: [{ title: "run logs", lines: [`Wrote ${logs.length} log lines to ${outPath}`] }] }
+    }, { json: argsWantJson(args) });
     return 0;
   }
   const entries = logs.slice(Math.max(0, logs.length - limit));
-  if (argsWantJson(args)) {
-    process.stdout.write(
-      `${JSON.stringify({
-        runId: status.runId,
-        totalCount: logs.length,
-        returnedCount: entries.length,
-        firstSequence: logs.length === 0 ? null : logs.length - entries.length + 1,
-        lastSequence: logs.length === 0 ? null : logs.length,
-        truncated: logs.length > entries.length,
-        hasMore: logs.length > entries.length,
-        entries,
-        next: {
-          export: `deepline runs logs ${status.runId} --out run.log --json`
-        }
-      })}
-`
-    );
-  } else {
-    process.stdout.write(`${entries.join("\n")}${entries.length > 0 ? "\n" : ""}`);
-  }
+  printCommandEnvelope({
+    runId: status.runId,
+    totalCount: logs.length,
+    returnedCount: entries.length,
+    firstSequence: logs.length === 0 ? null : logs.length - entries.length + 1,
+    lastSequence: logs.length === 0 ? null : logs.length,
+    truncated: logs.length > entries.length,
+    hasMore: logs.length > entries.length,
+    entries,
+    next: {
+      export: `deepline runs logs ${status.runId} --out run.log --json`
+    },
+    render: { sections: [{ title: "run logs", lines: entries }] }
+  }, { json: argsWantJson(args), text: `${entries.join("\n")}${entries.length > 0 ? "\n" : ""}` });
   return 0;
 }
 async function handleRunStop(args) {
@@ -7182,19 +7464,18 @@ async function handleRunStop(args) {
   }
   const client = new DeeplineClient();
   const result = await client.runs.stop(runId, { reason });
-  if (argsWantJson(args)) {
-    process.stdout.write(`${JSON.stringify(result)}
-`);
-  } else {
-    console.log(`Stopped ${result.runId}`);
-    if (result.hitlCancelledCount > 0) {
-      console.log(`  cancelled HITL waits: ${result.hitlCancelledCount}`);
-    }
-  }
+  const lines = [
+    `Stopped ${result.runId}`,
+    ...result.hitlCancelledCount > 0 ? [`cancelled HITL waits: ${result.hitlCancelledCount}`] : []
+  ];
+  printCommandEnvelope({
+    ...result,
+    render: { sections: [{ title: "run stop", lines }] }
+  }, { json: argsWantJson(args) });
   return 0;
 }
 async function handleRunExport(args) {
-  const usage = "Usage: deepline runs export <run-id> --out output.csv [--json]";
+  const usage = "Usage: deepline runs export <run-id> [--dataset result.rows] --out output.csv [--json]";
   let runId;
   try {
     runId = parseRunIdPositional(args, usage);
@@ -7203,10 +7484,15 @@ async function handleRunExport(args) {
     return 1;
   }
   let outPath = null;
+  let datasetPath = null;
   for (let index = 0; index < args.length; index += 1) {
     const arg = args[index];
     if (arg === "--out" && args[index + 1]) {
       outPath = resolve8(args[++index]);
+      continue;
+    }
+    if (arg === "--dataset" && args[index + 1]) {
+      datasetPath = args[++index];
     }
   }
   if (!outPath) {
@@ -7215,21 +7501,18 @@ async function handleRunExport(args) {
   }
   const client = new DeeplineClient();
   const status = await client.getPlayStatus(runId);
-  const exportedPath = exportPlayStatusRows(status, outPath);
-  if (argsWantJson(args)) {
-    const rowsInfo = extractCanonicalRowsInfo(status);
-    process.stdout.write(
-      `${JSON.stringify({
-        runId: status.runId,
-        csv_path: exportedPath,
-        rowCount: rowsInfo?.totalRows ?? null,
-        columns: rowsInfo?.columns ?? []
-      })}
-`
-    );
-  } else {
-    console.log(`Exported ${status.runId} to ${exportedPath}`);
-  }
+  const exportResult = await exportPlayStatusRows(client, status, outPath, {
+    datasetPath
+  });
+  printCommandEnvelope({
+    runId: status.runId,
+    ...datasetPath ? { dataset: datasetPath } : {},
+    csv_path: exportResult?.path ?? null,
+    rowCount: exportResult?.rowsInfo.totalRows ?? null,
+    columns: exportResult?.rowsInfo.columns ?? [],
+    local: { csv_path: exportResult?.path ?? null },
+    render: { sections: [{ title: "run export", lines: [`Exported ${status.runId} to ${exportResult?.path ?? outPath}`] }] }
+  }, { json: argsWantJson(args) });
   return 0;
 }
 async function handlePlayGet(args) {
@@ -7677,8 +7960,7 @@ Notes:
   Local files are bundled, preflighted, then run in Deepline cloud.
   Named plays run the live saved revision.
   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.
+  Example: --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.
@@ -7711,8 +7993,8 @@ 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 enrich.play.ts --input '{"file":"leads.csv"}' --watch --out leads-enriched.csv
   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
   deepline runs get <run-id>
 `
@@ -7730,8 +8012,9 @@ Examples:
     `
 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".
+  this for play-specific inputs like --limit 5 or --filters.title "GTM Engineer".
+  For CSV file inputs, prefer --input '{"file":"leads.csv"}' so the field name
+  matches the play's ctx.csv(input.file) contract.
 `
   ).action(async (target, options, command) => {
     const passthroughArgs = [...command.args];
@@ -7916,7 +8199,7 @@ Examples:
     `
 Concepts:
   A run is one execution instance of a play. It has status, progress, logs,
-  preview output, recovery metadata, and optional full row export.
+  returned result, dataset previews, recovery metadata, and optional dataset export.
   tail reads the live stream. logs fetches persisted logs after the fact.
   stop mutates cloud state by requesting cancellation.
 
@@ -7929,7 +8212,7 @@ 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.").addHelpText(
+  runs.command("get <runId>").description("Get status, progress, result, errors, and recovery metadata for a play run.").addHelpText(
     "after",
     `
 Notes:
@@ -8023,20 +8306,22 @@ Examples:
       ...options.json ? ["--json"] : []
     ]);
   });
-  runs.command("export <runId>").description("Export the completed row output for a play run to CSV.").addHelpText(
+  runs.command("export <runId>").description("Export a returned dataset handle 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.
+  Writes a returned dataset handle to the requested local CSV path. Use runs get
+  first to inspect dataset paths like result.rows or result.nested.contacts.
 
 Examples:
   deepline runs export play/my-play/run/20260501t000000-000 --out output.csv
+  deepline runs export play/my-play/run/20260501t000000-000 --dataset result.rows --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) => {
+  ).requiredOption("--out <path>", "Output CSV path").option("--dataset <path>", "Returned dataset handle path, such as result.rows").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (runId, options) => {
     process.exitCode = await handleRunExport([
       runId,
+      ...options.dataset ? ["--dataset", options.dataset] : [],
       "--out",
       options.out,
       ...options.json ? ["--json"] : []
@@ -8202,19 +8487,19 @@ function toListedTool(tool) {
 async function listTools(args) {
   const client = new DeeplineClient();
   const items = (await client.listTools()).map(toListedTool);
-  if (argsWantJson(args)) {
-    process.stdout.write(`${JSON.stringify(items)}
-`);
-    return 0;
-  }
-  console.log(`${items.length} tools available:
-`);
-  for (const item of items) {
-    const cats = item.categories.length ? ` [${item.categories.join(", ")}]` : "";
-    const listHint = item.listExtractorPaths?.length ? ` listExtractorPaths=${item.listExtractorPaths.join(",")}` : "";
-    console.log(`  ${item.toolId}${cats}`);
-    console.log(`    ${item.description}${listHint}`);
-  }
+  const render = {
+    sections: [
+      {
+        title: `${items.length} tools available:`,
+        lines: items.flatMap((item) => {
+          const cats = item.categories.length ? ` [${item.categories.join(", ")}]` : "";
+          const listHint = item.listExtractorPaths?.length ? ` listExtractorPaths=${item.listExtractorPaths.join(",")}` : "";
+          return [`${item.toolId}${cats}`, `  ${item.description}${listHint}`];
+        })
+      }
+    ]
+  };
+  printCommandEnvelope({ tools: items, count: items.length, render }, { json: argsWantJson(args) });
   return 0;
 }
 async function searchTools(queryInput, options = {}) {
@@ -8232,21 +8517,27 @@ async function searchTools(queryInput, options = {}) {
     includeSearchDebug: options.includeSearchDebug
   });
   const items = result.tools.map(toListedTool);
-  if (options.json || shouldEmitJson()) {
-    process.stdout.write(`${JSON.stringify({ ...result, tools: items })}
-`);
-    return 0;
-  }
-  console.log(`${items.length} tools found:
-`);
-  for (const item of items) {
-    const cats = item.categories.length ? ` [${item.categories.join(", ")}]` : "";
-    console.log(`  ${item.toolId}${cats}`);
-    console.log(`    ${item.description}`);
-    if (item.inputSchema) {
-      console.log("    inputSchema: yes");
+  const envelope = {
+    ...result,
+    tools: items,
+    count: items.length,
+    render: {
+      sections: [
+        {
+          title: `${items.length} tools found:`,
+          lines: items.flatMap((item) => {
+            const cats = item.categories.length ? ` [${item.categories.join(", ")}]` : "";
+            return [
+              `${item.toolId}${cats}`,
+              `  ${item.description}`,
+              ...item.inputSchema ? ["  inputSchema: yes"] : []
+            ];
+          })
+        }
+      ]
     }
-  }
+  };
+  printCommandEnvelope(envelope, { json: options.json || shouldEmitJson() });
   return 0;
 }
 function playIdentifiers(play) {
@@ -8578,6 +8869,9 @@ function samplePayload(samples, key) {
   if (!isRecord3(entry)) return void 0;
   return Object.prototype.hasOwnProperty.call(entry, "payload") ? entry.payload : entry;
 }
+function commandEnvelopeFromRawResponse(rawResponse) {
+  return isRecord3(rawResponse) ? { ...rawResponse } : { status: "completed", result: rawResponse };
+}
 function isPlayTool(tool) {
   const provider = typeof tool.provider === "string" ? tool.provider : "";
   return provider === "deepline_native" && Boolean(recordField(tool, "playExpansion", "play_expansion"));
@@ -8742,6 +9036,53 @@ export default definePlay(${JSON.stringify(playName)}, async (ctx) => {
     windowsCopyCommand: `New-Item -ItemType Directory -Force -Path ${powerShellQuote(projectDir.replace(/\//g, "\\"))} | Out-Null; Copy-Item -LiteralPath ${powerShellQuote(scriptPath)} -Destination ${powerShellQuote(`${projectDir.replace(/\//g, "\\")}\\${fileName}`)}`
   };
 }
+function buildToolExecuteBaseEnvelope(input) {
+  const envelope = commandEnvelopeFromRawResponse(input.rawResponse);
+  const summaryEntries = Object.entries(input.summary);
+  const output = input.listConversion ? {
+    kind: "list",
+    rowCount: input.listConversion.rows.length,
+    columns: Object.keys(input.listConversion.rows[0] ?? {}),
+    preview: input.listConversion.rows.slice(0, 5),
+    listStrategy: input.listConversion.strategy,
+    listSourcePath: input.listConversion.sourcePath
+  } : {
+    kind: summaryEntries.length > 0 ? "object" : "raw",
+    summary: input.summary
+  };
+  const actions = input.listConversion ? [
+    {
+      label: "next",
+      command: "move starter script into a project folder and expand it into a Deepline play"
+    }
+  ] : [];
+  return {
+    ...envelope,
+    output,
+    ...summaryEntries.length > 0 ? { summary: input.summary } : {},
+    next: input.listConversion ? {
+      expandToPlay: "Use stable map and step keys so reruns are idempotent: completed rows are reused, and only missing or stale work runs again."
+    } : {},
+    render: {
+      sections: input.listConversion ? [
+        {
+          title: "output",
+          lines: [
+            `${input.listConversion.rows.length} row(s) extracted from ${input.listConversion.sourcePath ?? "auto-detected list"}`,
+            `columns: ${JSON.stringify(Object.keys(input.listConversion.rows[0] ?? {}))}`,
+            `preview: ${JSON.stringify(input.listConversion.rows.slice(0, 5))}`
+          ]
+        }
+      ] : [
+        {
+          title: "result",
+          lines: summaryEntries.length > 0 ? summaryEntries.map(([key, value]) => `${key}=${String(value)}`) : [JSON.stringify(input.rawResponse, null, 2)]
+        }
+      ],
+      actions
+    }
+  };
+}
 async function executeTool(args) {
   let parsed;
   try {
@@ -8774,24 +9115,45 @@ async function executeTool(args) {
     listExtractorPaths: metadata.listExtractorPaths ?? []
   });
   const summary = extractSummaryFields(rawResponse);
+  const baseEnvelope = buildToolExecuteBaseEnvelope({
+    toolId: parsed.toolId,
+    rawResponse,
+    listConversion,
+    summary
+  });
   if (parsed.outputFormat === "json" || parsed.outputFormat === "auto" && shouldEmitJson()) {
-    process.stdout.write(`${JSON.stringify(rawResponse, null, 2)}
-`);
+    printCommandEnvelope(baseEnvelope, { json: true });
     return 0;
   }
   if (parsed.outputFormat === "json_file") {
     const jsonPath = writeJsonOutputFile(rawResponse, `payload_${parsed.toolId}`);
-    console.log(jsonPath);
+    printCommandEnvelope(
+      {
+        ...baseEnvelope,
+        local: {
+          ...isRecord3(baseEnvelope.local) ? baseEnvelope.local : {},
+          payload_file: jsonPath
+        }
+      },
+      { json: true }
+    );
     return 0;
   }
   if (!listConversion) {
     if (parsed.outputFormat === "csv" || parsed.outputFormat === "csv_file") {
       const jsonPath = writeJsonOutputFile(rawResponse, `payload_${parsed.toolId}`);
-      console.log(jsonPath);
+      printCommandEnvelope(
+        {
+          ...baseEnvelope,
+          local: {
+            payload_file: jsonPath
+          }
+        },
+        { json: parsed.outputFormat === "csv_file" || shouldEmitJson() }
+      );
       return 0;
     }
-    process.stdout.write(`${JSON.stringify(rawResponse, null, 2)}
-`);
+    printCommandEnvelope(baseEnvelope, { json: false });
     return 0;
   }
   const csv = writeCsvOutputFile(listConversion.rows, `${parsed.toolId}_output`);
@@ -8800,8 +9162,51 @@ async function executeTool(args) {
     payload: parsed.params,
     rows: listConversion.rows
   });
+  const materializedEnvelope = {
+    ...baseEnvelope,
+    local: {
+      extracted_csv: csv.path,
+      extracted_csv_rows: csv.rowCount,
+      extracted_csv_columns: csv.columns,
+      preview: csv.preview,
+      starter_script: seededScript.path,
+      project_dir: seededScript.projectDir,
+      copy_to_project: {
+        macos_linux: seededScript.macCopyCommand,
+        windows_powershell: seededScript.windowsCopyCommand
+      }
+    },
+    render: {
+      sections: [
+        {
+          title: `${csv.path} (${csv.rowCount} rows)`,
+          lines: [
+            ...csv.columns.length > 0 ? [`columns: ${JSON.stringify(csv.columns)}`] : [],
+            ...Object.keys(summary).length > 0 ? [`summary: ${Object.entries(summary).map(([key, value]) => `${key}=${String(value)}`).join(", ")}`] : [],
+            `preview: ${JSON.stringify(csv.preview)}`,
+            `starter script: ${seededScript.path}`
+          ]
+        }
+      ],
+      actions: [
+        {
+          label: "next",
+          command: "Move the script into a project folder and expand it into a Deepline play. Use stable map and step keys so reruns are idempotent: completed rows are reused, and only missing or stale work runs again."
+        },
+        {
+          label: "macOS/Linux",
+          command: seededScript.macCopyCommand
+        },
+        {
+          label: "Windows PowerShell",
+          command: seededScript.windowsCopyCommand
+        }
+      ]
+    }
+  };
   if (parsed.outputFormat === "csv_file") {
-    process.stdout.write(`${JSON.stringify({
+    printCommandEnvelope({
+      ...materializedEnvelope,
       extracted_csv: csv.path,
       extracted_csv_rows: csv.rowCount,
       extracted_csv_columns: csv.columns,
@@ -8815,28 +9220,24 @@ async function executeTool(args) {
         windows_powershell: seededScript.windowsCopyCommand
       },
       summary
-    })}
-`);
+    }, { json: true });
     return 0;
   }
   if (parsed.noPreview) {
-    console.log(csv.path);
+    printCommandEnvelope(
+      {
+        ...materializedEnvelope,
+        local: {
+          ...materializedEnvelope.local ?? {},
+          output_path: csv.path
+        }
+      },
+      { json: shouldEmitJson(), text: `${csv.path}
+` }
+    );
     return 0;
   }
-  console.log(`${csv.path} (${csv.rowCount} rows)`);
-  if (csv.columns.length > 0) {
-    console.log(`columns: ${JSON.stringify(csv.columns)}`);
-  }
-  if (Object.keys(summary).length > 0) {
-    console.log(`summary: ${Object.entries(summary).map(([key, value]) => `${key}=${String(value)}`).join(", ")}`);
-  }
-  console.log(`preview: ${JSON.stringify(csv.preview)}`);
-  console.log(`starter script: ${seededScript.path}`);
-  console.log(
-    "next: Move the script into a project folder and expand it into a Deepline play. Use stable map and step keys so reruns are idempotent: completed rows are reused, and only missing or stale work runs again."
-  );
-  console.log(`macOS/Linux: ${seededScript.macCopyCommand}`);
-  console.log(`Windows PowerShell: ${seededScript.windowsCopyCommand}`);
+  printCommandEnvelope(materializedEnvelope, { json: false });
   return 0;
 }
 
@@ -8910,23 +9311,36 @@ function runCommand(command, args) {
 }
 async function handleUpdate(options) {
   const plan = resolveUpdatePlan();
+  const render = {
+    sections: [
+      {
+        title: "update",
+        lines: plan.kind === "source" ? [
+          "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}`
+        ] : [`Updating Deepline SDK/CLI with: ${plan.manualCommand}`]
+      }
+    ]
+  };
   if (options.json) {
-    process.stdout.write(`${JSON.stringify(plan)}
-`);
+    printCommandEnvelope({ ...plan, render }, { json: true });
     return 0;
   }
   if (options.printCommand) {
-    process.stdout.write(`${plan.manualCommand}
-`);
+    printCommandEnvelope(
+      {
+        ...plan,
+        render: {
+          sections: [{ title: "update command", lines: [plan.manualCommand] }]
+        }
+      },
+      { json: false, text: `${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}
-`
-    );
+    printCommandEnvelope({ ...plan, render }, { json: false });
     return 0;
   }
   process.stderr.write(`Updating Deepline SDK/CLI with: ${plan.manualCommand}
@@ -9239,7 +9653,7 @@ Exit codes:
   registerDbCommands(program);
   registerFeedbackCommands(program);
   registerUpdateCommand(program);
-  program.command("health").description("Check server health.").addHelpText(
+  program.command("health").description("Check server health.").option("--json", "Force JSON output.").addHelpText(
     "after",
     `
 Notes: