@typeship-ax/cli 0.23.1 → 0.24.0

package/dist/cli.js

@@ -21,13 +21,15 @@ import { fileURLToPath } from "node:url";
 import { TypeshipClient, formatDebugEvent } from "./index.js";
 import { asApiResult, mediaTypeForPath, validateAgainstSchema, ValidationError } from "./core/http.js";
 import { SCHEMAS, DEFS } from "./schemas.js";
-import { GLOBALS, OMITTED_OPS, OPS, buildArgs, findOp, missingRequired } from "./ops.js";
-import { MCP_CLIENTS, requiredScopes, agentGuide, agentBlock, agentInstructionsFile, agentMode, bundleProperty, claimProperty, classifyApiError, classifyAuthFailure, collectionProperty, detectHarness, envelope, exitCodeFor, findMcpClient, installSkills, mcpConfigured, pendingClaims, recordClaim, summarizeDoctor, upsertAgentBlock, writeBundle, writeMcpConfig, } from "./cli-agent.js";
+import { GLOBALS, INPUT_TYPES, OMITTED_OPS, OPS, buildArgs, findOp, missingRequired } from "./ops.js";
+import { MCP_CLIENTS, requiredScopes, agentGuide, agentBlock, agentInstructionsFile, agentMode, bundleProperty, claimProperty, classifyApiError, classifyAuthFailure, collectionProperty, detectHarness, envelope, exitCodeFor, findMcpClient, formatRequestPreview, installSkills, mcpConfigured, pendingClaims, recordClaim, requestPreview, summarizeDoctor, upsertAgentBlock, writeBundle, writeMcpConfig, } from "./cli-agent.js";
 import { relativeDate } from "./dates.js";
 import { checkValue } from "./arguments.js";
 import { docsReadCommand, docsReadTarget, fetchDocsText, resolveDocsContentUrl, searchConnectedGuides } from "./docs.js";
 import { projectFields, unmatchedFields, unmatchedFieldsMessage } from "./fields.js";
+import { renderTable } from "./table.js";
 import { SEARCH_PAGE_SIZE, rankOperations } from "./search.js";
+import { argumentPathText, findInputType, inputTypeText, namedTypesIn } from "./type-docs.js";
 const BIN = "typeship";
 /** The MCP server's key in client configs: the API's name, even when this
  * command was renamed away from a vendor's. It reads this command's login. */
@@ -39,6 +41,8 @@ const AUTH_SCALARS = [{ "option": "bearerToken", "flag": "token", "env": "TYPESH
 const HOSTED_MCP_HEADERS = { "Authorization": "Bearer ${TYPESHIP_TOKEN}" };
 const HOSTED_MCP_NOTE = null;
 const BASIC = null;
+/** Header and query names the API's key schemes use: --dry-run redacts them. */
+const CREDENTIAL_NAMES = [];
 /** The spec declares no security, so the token is offered, never required. */
 const AUTH_UNDECLARED = false;
 /** Repeated --header "Name: value" flags for this invocation. */
@@ -47,7 +51,7 @@ let HEADER_FLAGS = [];
 const EXCLUDED_OPS = 0;
 /** Generated CLI operations that are intentionally unavailable to MCP. */
 const MCP_EXCLUDED_OPS = 0;
-const VERSION = "0.23.1";
+const VERSION = "0.24.0";
 const API_VERSION = "1.0.0";
 const SPEC_FORMAT = "openapi";
 const IDENTITY_POLICY = {};
@@ -92,7 +96,7 @@ const API_TITLE = "Typeship";
  * API parameter with the same name (`accounts list --cursor <c>`) still
  * takes its value. Boolean API parameters are recognized once the command
  * is known. */
-const CORE_BOOLEAN_FLAGS = new Set(["all", "version", "non-interactive", "debug", "validate", "yes", "force", "json"]);
+const CORE_BOOLEAN_FLAGS = new Set(["all", "version", "non-interactive", "debug", "validate", "yes", "force", "json", "dry-run"]);
 const BUILTIN_BOOLEAN_FLAGS = {
     login: ["with-token", "no-browser", "device"],
     logout: ["local"],
@@ -235,29 +239,44 @@ function out(value) {
 }
 /** --fields a,b.c: the dotted paths to keep in API results (null = everything). Set in main(). */
 let FIELDS = null;
+/** --format table: print API results as text for a person instead of JSON. Opt-in only; set in main(). */
+let TABLE = false;
+/** An API result on stdout: JSON, or the --format table view of the same value. */
+function printResult(value, resource, collectionField = null) {
+    if (!TABLE) {
+        out(value);
+        return;
+    }
+    process.stdout.write(renderTable(value, { width: process.stdout.columns || 120, heading: (text) => paintOut("bold", text), collectionField, resource }));
+}
 /** Whether the command being run writes: an --fields mistake on a write
  * must not tempt anyone into running it again. Set in main(). */
 let FIELDS_AFTER_WRITE = false;
 /** Keep only FIELDS of a result: arrays item by item, objects by dotted path;
  * scalars untouched. A path that matches nothing is an error naming the keys
- * that exist, never a silent {}. */
-function project(value, perItem) {
+ * that exist, never a silent {}; one the response schema declares (an
+ * optional key no item has) is simply absent. */
+function project(value, perItem, schema) {
     if (FIELDS === null)
         return value;
-    const unmatched = unmatchedFields(value, FIELDS);
+    const unmatched = unmatchedFields(value, FIELDS, schema);
     if (unmatched.length > 0)
         failUnmatchedFields(unmatched, perItem, value);
     return projectFields(value, FIELDS);
 }
+/** The declared schema of the list a result holds under `key`. */
+function listSchemaOf(schema, key) {
+    return schema?.properties?.[key];
+}
 /** --fields over a stream (--all, events): paths no item has matched yet.
  * The stream is printed as it arrives, so the check fails at its end. */
-function streamFieldsCheck() {
+function streamFieldsCheck(schema) {
     let pending = null;
     return {
         item(value) {
             if (FIELDS === null)
                 return value;
-            const unmatched = unmatchedFields(value, FIELDS);
+            const unmatched = unmatchedFields(value, FIELDS, schema);
             pending = pending === null ? unmatched : pending.filter((p) => unmatched.some((u) => u.path === p.path));
             return projectFields(value, FIELDS);
         },
@@ -271,10 +290,13 @@ function failUnmatchedFields(unmatched, perItem, result) {
     return failWith({
         code: "FIELDS_UNMATCHED",
         message: unmatchedFieldsMessage(unmatched, perItem),
-        nextSteps: FIELDS_AFTER_WRITE
-            ? ["This command has already run; do not run it again to change --fields." + (result !== undefined ? " Its full result is in detail.result." : "")]
-            : ["Run the command again with --fields from the available keys" + (perItem ? " (fields apply to each item)" : "") + ", or without --fields for the whole result."],
-        detail: { unmatched, ...(FIELDS_AFTER_WRITE && result !== undefined ? { result } : {}) },
+        nextSteps: [
+            FIELDS_AFTER_WRITE
+                ? "This command has already run; do not run it again to change --fields." + (result !== undefined ? " Its full result is in detail.result." : "")
+                : result !== undefined ? "The full result is in detail.result; use it rather than running the command again." : "",
+            (FIELDS_AFTER_WRITE ? "Next time, use" : "To project a later run, use") + " --fields from the available keys" + (perItem ? " (fields apply to each item)" : "") + ", or omit --fields for the whole result.",
+        ].filter((step) => step !== ""),
+        detail: { unmatched, ...(result !== undefined ? { result } : {}) },
     });
 }
 /** Thrown after scheduling exit so sync callers stop; main() swallows it. */
@@ -1152,60 +1174,172 @@ function commandSummaries() {
     }));
 }
 /**
- * help --json: a compact command index. Full schemas live behind the
- * per-operation docs command so discovery does not spend an agent's context
- * window on every response shape before it has chosen an operation.
+ * help --json: discovery as data, bounded so one call cannot fill an agent's
+ * context window on a large API. The default is an index of resources and
+ * command names; "help <resource> --json" pages through one resource's
+ * commands with their methods, paths and summaries; "help <resource>
+ * <command> --json" is one command with its flags; "help --json --all" is
+ * every command with every flag. Full schemas stay behind the docs command.
  */
-function helpJson() {
+const HELP_INDEX_NAMES = 40;
+const HELP_INDEX_BYTES = 16_000;
+const HELP_PAGE_SIZE = 50;
+function helpHeader(detail) {
+    return { schema_version: "3", detail, name: BIN, version: VERSION, api: API_TITLE, api_version: API_VERSION, spec_format: SPEC_FORMAT };
+}
+function helpDiscovery() {
+    return {
+        resource: BIN + " help <resource> --json",
+        command: BIN + " help <resource> <command> --json",
+        search: BIN + " docs search <term> --json",
+        operation: BIN + " docs <resource> <command> --json",
+        all: BIN + " help --json --all",
+        note: "Find a command by resource or search, read its flags with help <resource> <command> --json, and its complete schemas with docs. --all prints every command with every flag at once.",
+    };
+}
+function helpCoverage() {
+    return EXCLUDED_OPS > 0 ? { coverage: { generated_operations: OPS.length, total_operations: OPS.length + EXCLUDED_OPS } } : {};
+}
+function opsByResource() {
     const byResource = new Map();
-    for (const c of commandSummaries()) {
-        const list = byResource.get(c.resource) ?? [];
-        list.push(c);
-        byResource.set(c.resource, list);
+    for (const op of OPS) {
+        const list = byResource.get(op.command[0]) ?? [];
+        list.push(op);
+        byResource.set(op.command[0], list);
     }
+    return byResource;
+}
+/** One command with its flags: an entry of help --json --all. */
+function helpEntry(op, summary) {
     return {
-        schema_version: "2",
-        name: BIN,
-        version: VERSION,
-        api: API_TITLE,
-        api_version: API_VERSION,
-        spec_format: SPEC_FORMAT,
+        command: op.command[1],
+        method: summary.method,
+        path: summary.path,
+        ...(summary.summary ? { summary: summary.summary } : {}),
+        paginated: summary.paginated,
+        safety: op.safety,
+        destructive: summary.destructive,
+        auth: summary.auth,
+        positional: op.params.filter((p) => p.kind === "path").map((p) => p.name),
+        flags: summary.flags,
+        details_command: BIN + " docs " + op.command[0] + " " + op.command[1] + " --json",
+    };
+}
+function helpAll() {
+    const summaries = commandSummaries();
+    const byResource = opsByResource();
+    return {
+        ...helpHeader("all"),
         usage: BIN + " <resource> <command> [args] [--flags]",
-        resources: [...byResource.entries()].map(([resource, commands]) => ({
+        resources: [...byResource.entries()].map(([resource, ops]) => ({
             resource,
-            commands: commands.map((c) => {
-                const op = OPS.find((o) => o.command[0] === resource && o.command[1] === c.command);
-                return {
-                    command: c.command,
-                    method: c.method,
-                    path: c.path,
-                    ...(c.summary ? { summary: c.summary } : {}),
-                    paginated: c.paginated,
-                    safety: op.safety,
-                    destructive: c.destructive,
-                    auth: c.auth,
-                    positional: op.params.filter((p) => p.kind === "path").map((p) => p.name),
-                    flags: c.flags,
-                    details_command: BIN + " docs " + resource + " " + c.command + " --json",
-                };
-            }),
+            commands: ops.map((op) => helpEntry(op, summaries[OPS.indexOf(op)])),
         })),
-        ...(EXCLUDED_OPS > 0 ? {
-            coverage: {
-                generated_operations: OPS.length,
-                total_operations: OPS.length + EXCLUDED_OPS,
-            },
-        } : {}),
-        discovery: {
-            search: BIN + " docs search <term> --json",
-            operation: BIN + " docs <resource> <command> --json",
-            note: "Choose an operation from this index, then read only that operation's complete schemas and example arguments.",
-        },
+        ...helpCoverage(),
+        discovery: helpDiscovery(),
         builtins: BUILTIN_COMMANDS,
-        global_flags: ["--help", "--version", "--debug", "--non-interactive", "--mode agent|human", "--yes", "--force", "--color on|off|auto", "--credentials @<JSON-file>|-", "--header 'Name: value'", "--timeout <seconds>", "--base-url <url>", "--profile <name>", "--data '<json>' | @<file> | -", "--fields <a,b.c>", "--all", "--validate", "--out <dir>", ...AUTH_SCALARS.map((a) => "--" + a.flag + " <value>")],
+        global_flags: ["--help", "--version", "--debug", "--non-interactive", "--mode agent|human", "--yes", "--force", "--color on|off|auto", "--credentials @<JSON-file>|-", "--header 'Name: value'", "--timeout <seconds>", "--base-url <url>", "--profile <name>", "--data '<json>' | @<file> | -", "--fields <a,b.c>", "--all", "--validate", "--dry-run", "--out <dir>", ...AUTH_SCALARS.map((a) => "--" + a.flag + " <value>")],
         auth_env_vars: agentContext().authEnvVars,
     };
 }
+/** Resources and command names. Past HELP_INDEX_BYTES a resource keeps only its count. */
+function helpIndex() {
+    const all = helpAll();
+    let bytes = 0;
+    let overBudget = false;
+    let truncated = false;
+    const resources = [...opsByResource().entries()].map(([resource, ops]) => {
+        const names = ops.map((op) => op.command[1]);
+        const entry = { resource, command_count: names.length, commands: names.slice(0, HELP_INDEX_NAMES) };
+        const size = JSON.stringify(entry).length;
+        if (overBudget || bytes + size > HELP_INDEX_BYTES) {
+            overBudget = truncated = true;
+            return { resource, command_count: names.length };
+        }
+        bytes += size;
+        if (names.length > HELP_INDEX_NAMES)
+            truncated = true;
+        return entry;
+    });
+    return {
+        ...helpHeader("index"),
+        usage: all.usage,
+        command_count: OPS.length,
+        resource_count: resources.length,
+        resources,
+        ...(truncated ? { truncated: "Some resources list only their first " + HELP_INDEX_NAMES + " command names or only a count. Run " + BIN + " help <resource> --json for a resource's commands." } : {}),
+        ...helpCoverage(),
+        discovery: all.discovery,
+        builtins: all.builtins,
+        global_flags: all.global_flags,
+        auth_env_vars: all.auth_env_vars,
+    };
+}
+function helpTarget(resource, method) {
+    const ops = opsByResource().get(resource);
+    if (!ops) {
+        const omitted = omittedCommand(resource, method);
+        if (omitted)
+            failOmitted(omitted);
+        const suggestion = didYouMean(resource, opsByResource().keys());
+        fail(2, "Unknown command: " + resource + "." + (suggestion ? " Did you mean '" + BIN + " help " + suggestion + " --json'?" : ""), undefined, ["Run '" + BIN + " help --json' for the resources and their commands."]);
+    }
+    if (method === undefined)
+        return ops;
+    const op = findOp(resource, method);
+    if (!op) {
+        const omitted = omittedCommand(resource, method);
+        if (omitted)
+            failOmitted(omitted);
+        const suggestion = didYouMean(method, ops.map((o) => o.command[1]));
+        fail(2, "Unknown command: " + resource + " " + method + "." + (suggestion ? " Did you mean '" + BIN + " help " + resource + " " + suggestion + " --json'?" : ""), undefined, ["Run '" + BIN + " help " + resource + " --json' for its commands."]);
+    }
+    return [op];
+}
+async function cmdHelpJson(parsed) {
+    const [, resource, method, extra] = parsed.positionals;
+    if (extra !== undefined)
+        fail(2, "help --json takes at most a resource and a command.", undefined, ["Run '" + BIN + " help --json' for the index."]);
+    const all = parsed.flags.get("all") === true;
+    const pageFlag = parsed.flags.get("page");
+    const page = pageFlag === undefined ? 1 : Number(pageFlag);
+    if (!Number.isInteger(page) || page < 1)
+        fail(2, "--page expects a whole number from 1.");
+    if (resource === undefined) {
+        if (pageFlag !== undefined)
+            fail(2, "--page applies to help <resource> --json.");
+        out(all ? helpAll() : helpIndex());
+        await flushExit(0);
+    }
+    const ops = helpTarget(resource, method);
+    const summaries = commandSummaries();
+    if (method !== undefined) {
+        out({ ...helpHeader("command"), resource, ...helpEntry(ops[0], summaries[OPS.indexOf(ops[0])]) });
+        await flushExit(0);
+    }
+    if (all) {
+        out({ ...helpHeader("resource"), resource, command_count: ops.length, commands: ops.map((op) => helpEntry(op, summaries[OPS.indexOf(op)])) });
+        await flushExit(0);
+    }
+    const pages = Math.max(1, Math.ceil(ops.length / HELP_PAGE_SIZE));
+    if (page > pages)
+        fail(2, "--page " + page + " is past the last page (" + pages + ") of " + resource + ".", undefined, ["Run '" + BIN + " help " + resource + " --json' for the first page."]);
+    const commands = ops.slice((page - 1) * HELP_PAGE_SIZE, page * HELP_PAGE_SIZE).map((op) => {
+        const s = summaries[OPS.indexOf(op)];
+        return { command: op.command[1], method: s.method, path: s.path, ...(s.summary ? { summary: s.summary } : {}), paginated: s.paginated, safety: op.safety, positional: op.params.filter((p) => p.kind === "path").map((p) => p.name) };
+    });
+    out({
+        ...helpHeader("resource"),
+        resource,
+        command_count: ops.length,
+        page,
+        pages,
+        commands,
+        ...(page < pages ? { next_command: BIN + " help " + resource + " --json --page " + (page + 1) } : {}),
+        discovery: { command: BIN + " help " + resource + " <command> --json", operation: BIN + " docs " + resource + " <command> --json", all: BIN + " help " + resource + " --json --all" },
+    });
+    await flushExit(0);
+}
 async function cmdAgentGuide(parsed) {
     if (parsed.help) {
         process.stdout.write(BIN + " agent-guide [--format json] — how an agent should drive this CLI: conventions, first command, docs, MCP, skills, next steps. JSON.\n");
@@ -1581,7 +1715,7 @@ function completionFlagsFor(op) {
     }
     return { flags, values };
 }
-const COMPLETION_GLOBAL_FLAGS = ["--help", "--version", "--non-interactive", "--color", "--credentials", "--header", "--timeout", "--base-url", "--profile", "--data", "--fields", "--all", "--validate", "--debug", "--mode", "--yes", "--force", "--out", ...AUTH_SCALARS.map((a) => "--" + a.flag)];
+const COMPLETION_GLOBAL_FLAGS = ["--help", "--version", "--non-interactive", "--color", "--credentials", "--header", "--timeout", "--base-url", "--profile", "--data", "--fields", "--all", "--validate", "--dry-run", "--debug", "--mode", "--yes", "--force", "--out", ...AUTH_SCALARS.map((a) => "--" + a.flag)];
 const BUILTIN_WORDS = {
     config: ["list", "get", "set", "unset", "path"],
     completion: ["bash", "zsh", "fish"],
@@ -1742,7 +1876,9 @@ function referenceFor(op, includeSchemas = false) {
         lines.push("", paintOut("bold", label + ":"));
         for (const p of params) {
             const name = p.kind === "path" ? "<" + p.name + ">" : "--" + p.flag;
-            lines.push("  " + padPaint("cyan", name, 30) + typeLabel(p) + (p.required ? " " + paintOut("yellow", "(required)") : ""));
+            // An object flag reads as its named type, which docs read explains.
+            const named = objectTypeName(op, p);
+            lines.push("  " + padPaint("cyan", name, 30) + (named ? INPUT_TYPES.args[op.tool][p.name] : typeLabel(p)) + (p.required ? " " + paintOut("yellow", "(required)") : ""));
             const values = p.type === "array" ? p.items?.enum : p.enum;
             if (values && values.join("|").length > 24)
                 lines.push("      one of: " + values.join(", "));
@@ -1766,10 +1902,31 @@ function referenceFor(op, includeSchemas = false) {
             lines.push("", paintOut("bold", "Output schema:"), JSON.stringify(op.outputSchema, null, 2));
     }
     else {
+        const nested = op.params.find((p) => objectTypeName(op, p) || p.type === "object" || (p.type === "array" && p.items?.type === "object"));
+        if (nested) {
+            const named = objectTypeName(op, nested);
+            lines.push("", "Nested fields: " + BIN + " docs " + op.command.join(" ") + " --path " + nested.name + " gives a flag's type and all its fields; extend the path (" + nested.name + ".<field>) to go deeper."
+                + (named ? " Named types: " + BIN + " docs read " + named + "." : ""));
+        }
         lines.push("", "Add --schema for the complete input/output schemas, or --json for the machine contract.");
     }
     return lines.join("\n");
 }
+/** The named input object a flag takes (IssueFilter), when it has one. */
+function objectTypeName(op, p) {
+    return namedTypesIn(INPUT_TYPES, INPUT_TYPES.args[op.tool]?.[p.name]).find((name) => INPUT_TYPES.types[name].fields);
+}
+function docsTypeHint(name) {
+    return BIN + " docs read " + name;
+}
+/** docs --path: one nested argument, or a usage error naming the fields. */
+async function docsPathExit(root, path) {
+    const found = argumentPathText(INPUT_TYPES, root, path, docsTypeHint);
+    if (!found.ok)
+        fail(2, found.message + (found.available.length > 0 ? " Fields: " + found.available.join(", ") + "." : ""));
+    process.stdout.write(found.text + "\n");
+    return flushExit(0);
+}
 /** Opens a browser for a person; under an agent it prints the URL instead of opening anything. */
 function openInBrowser(url, parsed) {
     if (parsed && nonInteractive(parsed)) {
@@ -1788,11 +1945,12 @@ async function cmdDocs(parsed) {
             "",
             "  " + BIN + " docs                          overview",
             "  " + BIN + " docs <resource> <command>     operation contract and example",
+            "      --path <a.b>                          one nested argument's type and fields",
             "      --schema                              include input/output JSON Schema",
             "      --json                                print the machine contract as JSON",
             "  " + BIN + " docs search <term>            search reference and guides",
             "      --json / --format json                 print structured matches and availability",
-            "  " + BIN + " docs read <page>              print a docs-site page in the terminal",
+            "  " + BIN + " docs read <page>              print a named input type or a docs-site page",
             "  " + BIN + " docs --web                    open the docs site in a browser",
             "",
             "Guides come from the docs site's llms.txt (set with '" + BIN + " config set docs-url <url>').",
@@ -1864,6 +2022,14 @@ async function cmdDocs(parsed) {
         const page = parsed.positionals[2];
         if (page === undefined)
             fail(2, "docs read expects a page path or URL");
+        const typeName = findInputType(INPUT_TYPES, page);
+        if (typeName) {
+            const path = parsed.flags.get("path");
+            if (typeof path === "string" && path.trim())
+                await docsPathExit({ type: typeName }, path);
+            process.stdout.write(inputTypeText(INPUT_TYPES, typeName, docsTypeHint) + "\n");
+            await flushExit(0);
+        }
         let target = page;
         if (!/^https?:\/\//.test(target)) {
             const index = await fetchDocs("llms.txt");
@@ -1903,6 +2069,9 @@ async function cmdDocs(parsed) {
             }, null, 2) + "\n");
             await flushExit(0);
         }
+        const path = parsed.flags.get("path");
+        if (typeof path === "string" && path.trim())
+            await docsPathExit({ tool: op.tool, inputSchema: op.inputSchema, label: op.command.join(" ") }, path);
         process.stdout.write(referenceFor(op, parsed.flags.get("schema") === true) + "\n");
         await flushExit(0);
     }
@@ -2088,7 +2257,7 @@ function printRoot(stream = process.stdout) {
     }
     const width = termWidth();
     const lines = [];
-    lines.push(paintOut("bold", BIN) + ": " + "Typeship API" + " (v" + "1.0.0" + "), package " + "0.23.1");
+    lines.push(paintOut("bold", BIN) + ": " + "Typeship API" + " (v" + "1.0.0" + "), package " + "0.24.0");
     lines.push("");
     lines.push(paintOut("bold", "Usage:") + " " + BIN + " <resource> <command> [args] [--flags]");
     lines.push("");
@@ -2111,7 +2280,7 @@ function printRoot(stream = process.stdout) {
         lines.push(...labeled(paintOut("yellow", "Coverage:") + " ", "this build includes " + OPS.length + " of " + (OPS.length + EXCLUDED_OPS) + " operations; api.json lists the rest", width, 14));
     }
     lines.push("");
-    const flagsText = "-v/--version, -h/--help, --debug, --non-interactive, --color on|off|auto, --base-url <url>, --profile <name>, --credentials @<file>|-, --header \"Name: value\", --timeout <seconds>, --data '<json>', --fields <a,b.c>, --all (paginated lists), --validate (schema-check parameters and JSON bodies)" +
+    const flagsText = "-v/--version, -h/--help, --debug, --non-interactive, --color on|off|auto, --base-url <url>, --profile <name>, --credentials @<file>|-, --header \"Name: value\", --timeout <seconds>, --data '<json>', --fields <a,b.c>, --all (paginated lists), --format table (results as text), --validate (schema-check parameters and JSON bodies), --dry-run (print the request, send nothing)" +
         (AUTH_SCALARS.length > 0 ? ", " + AUTH_SCALARS.map((a) => "--" + a.flag + " <value>").join(", ") : "");
     lines.push(...labeled(paintOut("bold", "Global flags:") + " ", flagsText, width, 14).map((l, i) => (i === 0 ? l : l)));
     lines.push(...labeled("Credential env vars: ", [
@@ -2179,6 +2348,9 @@ function commandExtras(op) {
     extras.push(["--fields <a,b.c>", "keep only these fields of the result" + (op.paginated ? " (per item)" : collectionField ? " (per item in " + collectionField + ")" : "")]);
     if ((op.fileBundleProperty ?? bundleProperty(op.outputSchema)) !== null)
         extras.push(["--out <dir>", "write the response's files ({path, content}) into a directory"]);
+    extras.push(["--dry-run", "print the resolved request (method, URL, headers, body) with credentials redacted; nothing is sent" + (op.safety === "destructive" ? ", so no --force is needed" : "")]);
+    if (!op.rawResponse && !op.sse)
+        extras.push(["--format table", "print the result as a table for reading instead of JSON"]);
     if (op.safety === "destructive")
         extras.push(["--force, -y", "destructive: required without a terminal, skips the prompt with one"]);
     return extras;
@@ -2442,6 +2614,73 @@ function validateParameters(op, values, flags) {
 let LAST_CLIENT_HAD_CREDENTIAL = false;
 /** The last client's Basic credentials, for path arguments that default to the username. */
 let LAST_CLIENT_BASIC = {};
+/** --dry-run: the client's fetch records the first request and sends
+ * nothing. Set before makeClient; secrets are the credential values it
+ * resolved, redacted wherever they appear in the preview. */
+let DRY_RUN = null;
+class DryRunStop extends Error {
+}
+function dryRunCapture() {
+    const capture = {
+        secrets: [],
+        fetch: async (input, init) => {
+            if (!capture.request) {
+                const headers = {};
+                new Headers(init?.headers).forEach((value, name) => { headers[name] = value; });
+                capture.request = { method: init?.method ?? "GET", url: typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url, headers, body: init?.body ?? undefined };
+            }
+            throw new DryRunStop("dry run: not sent");
+        },
+    };
+    return capture;
+}
+/** Every credential value a client was built with (not a Basic username,
+ * which is an account identifier such as Twilio's AccountSid). */
+function credentialSecrets(options) {
+    const found = [];
+    const walk = (value, key) => {
+        if (typeof value === "string") {
+            if (key !== "username")
+                found.push(value);
+            return;
+        }
+        if (value && typeof value === "object")
+            for (const [k, v] of Object.entries(value))
+                walk(v, k);
+    };
+    for (const a of AUTH_SCALARS)
+        walk(options[a.option], a.option);
+    walk(options.basicAuth, "basicAuth");
+    walk(options.credentials, "credentials");
+    walk(options.bearerToken, "bearerToken");
+    return found;
+}
+/** Drive the command's call until its request reaches the dry-run fetch,
+ * then print that request (JSON in agent mode, text for a person) and exit.
+ * A failure before any request (a --validate violation) is reported as usual. */
+async function printDryRun(parsed, callResult) {
+    let failure;
+    try {
+        const pending = callResult;
+        if (typeof pending.then === "function")
+            await callResult;
+        else if (typeof pending[Symbol.asyncIterator] === "function")
+            await pending[Symbol.asyncIterator]().next();
+    }
+    catch (e) {
+        failure = e;
+    }
+    const request = DRY_RUN?.request;
+    if (!request) {
+        failApi(failure ?? new Error("--dry-run: the command made no request"), LAST_CLIENT_HAD_CREDENTIAL);
+    }
+    const preview = await requestPreview(request, { sensitiveNames: CREDENTIAL_NAMES, secrets: DRY_RUN.secrets });
+    if (isAgentMode(parsed))
+        out(preview);
+    else
+        process.stdout.write(formatRequestPreview(preview));
+    return await flushExit(0);
+}
 /** The configured Basic-auth username: the named scheme's, else basicAuth's. */
 function credentialUsername(scheme) {
     const named = LAST_CLIENT_BASIC.credentials?.[scheme];
@@ -2677,6 +2916,12 @@ async function makeClient(flags, op, candidate, forIdentity = false) {
     const extraHeaders = extraRequestHeaders();
     if (Object.keys(extraHeaders).length)
         options.onRequest = (context) => { applyExtraHeaders(context.headers, extraHeaders); };
+    // --dry-run swaps fetch on this client only: an OAuth refresh (and its
+    // identity check) still uses the real transport, the command does not.
+    if (DRY_RUN && !forIdentity) {
+        DRY_RUN.secrets = credentialSecrets(options);
+        return new TypeshipClient({ ...options, fetch: DRY_RUN.fetch, maxRetries: 0 });
+    }
     return new TypeshipClient(options);
 }
 function editDistance(a, b) {
@@ -2735,16 +2980,20 @@ async function main() {
     if (!parsed.help && ["login", "init"].includes(parsed.positionals[0] ?? ""))
         expectedLoginIdentity(parsed.flags);
     if (parsed.positionals[0] === "help") {
-        // help --json: the command surface as data (agents read this once).
+        // help [<resource> [<command>]] --json: bounded discovery as data; --all is exhaustive.
         if (parsed.flags.get("json") === true || parsed.flags.get("format") === "json") {
-            out(helpJson());
-            await flushExit(0);
+            await cmdHelpJson(parsed);
         }
         parsed.positionals.shift();
         parsed.help = true;
     }
-    if (parsed.flags.get("format") !== undefined && parsed.flags.get("format") !== "json") {
-        fail(2, "--format json is the only format; output is always JSON.");
+    const formatFlag = parsed.flags.get("format");
+    if (formatFlag !== undefined && formatFlag !== "json" && formatFlag !== "table") {
+        fail(2, "--format takes json (the default) or table.");
+    }
+    TABLE = formatFlag === "table";
+    if (TABLE && !parsed.help && (BUILTIN_COMMANDS.includes(parsed.positionals[0] ?? "") || parsed.positionals.length === 0)) {
+        fail(2, "--format table applies to API commands; " + (parsed.positionals[0] ? BIN + " " + parsed.positionals[0] : BIN) + " prints JSON.");
     }
     if (parsed.flags.has("version") || parsed.positionals[0] === "version") {
         // "acme 1.0.0 (acme 1.0.0)" would say the name twice; when the API's
@@ -2874,7 +3123,7 @@ async function main() {
     // Mirrors opReservedFlags() in the generator: API parameters never use these
     // names (colliding ones are emitted as --<kind>-<name>), so an unknown flag
     // check can be exact.
-    const RESERVED_FLAGS = new Set(["data", "credentials", "header", "timeout", "all", "select", "base-url", "profile", "debug", "validate", "non-interactive", "color", "version", "help", "yes", "force", "mode", "format", "json", "out", "fields", ...AUTH_SCALARS.map((a) => a.flag), ...(BASIC ? ["username", "password"] : []), ...GLOBALS.map((g) => g.flag)]);
+    const RESERVED_FLAGS = new Set(["data", "credentials", "header", "timeout", "all", "select", "base-url", "profile", "debug", "validate", "dry-run", "non-interactive", "color", "version", "help", "yes", "force", "mode", "format", "json", "out", "fields", ...AUTH_SCALARS.map((a) => a.flag), ...(BASIC ? ["username", "password"] : []), ...GLOBALS.map((g) => g.flag)]);
     for (const spec of op.params) {
         if (spec.kind === "path")
             continue;
@@ -2971,6 +3220,20 @@ async function main() {
     if (!op.paginated && parsed.flags.get("all") === true) {
         fail(2, op.command.join(" ") + " does not paginate, so --all has nothing to walk. Run it without --all; it returns the whole response.");
     }
+    // --dry-run resolves everything a real call would (arguments, defaults,
+    // credentials, the body encoding) and prints the request instead of
+    // sending it. A destructive command needs no --force: nothing runs.
+    if (parsed.flags.get("dry-run") === true) {
+        if (op.paginated && parsed.flags.get("all") === true)
+            fail(2, "--dry-run previews one request; run it without --all to see the first page's.");
+        DRY_RUN = dryRunCapture();
+    }
+    // A table needs the whole result: streams (--all, events) and raw bodies stay as they are.
+    if (TABLE) {
+        const streams = parsed.flags.get("all") === true || op.sse || (op.streamMethod !== undefined && values[op.streamMethod.flag] === op.streamMethod.value);
+        if (streams || op.rawResponse)
+            fail(2, "--format table needs one complete JSON result; " + op.command.join(" ") + (op.rawResponse ? " returns a raw body." : " streams NDJSON here.") + " Drop --format table" + (parsed.flags.get("all") === true ? " or --all." : "."));
+    }
     const client = await makeClient(parsed.flags, op);
     for (const spec of pathSpecs) {
         if (!spec.credential || values[spec.name] !== undefined)
@@ -2984,7 +3247,7 @@ async function main() {
     // Destructive commands need --force. A person gets asked; an agent gets
     // an action_required envelope with the exact command to run, so nothing
     // is deleted on a guess.
-    if (op.safety === "destructive" && !assumeYes(parsed)) {
+    if (op.safety === "destructive" && !assumeYes(parsed) && !DRY_RUN) {
         // Credential flags are replaced by placeholders: the rerun is shown to
         // agents and logged, so it must never repeat a key.
         const secretFlags = new Set([...AUTH_SCALARS.map((a) => "--" + a.flag), "--header"]);
@@ -3016,8 +3279,10 @@ async function main() {
     // as NDJSON as they arrive, instead of failing on the event stream.
     const streaming = op.streamMethod !== undefined && values[op.streamMethod.flag] === op.streamMethod.value;
     const callResult = target[streaming ? op.streamMethod.method : op.method](...args);
+    if (DRY_RUN)
+        await printDryRun(parsed, callResult);
     if (op.paginated && parsed.flags.get("all") === true) {
-        const fieldsCheck = streamFieldsCheck();
+        const fieldsCheck = streamFieldsCheck(listSchemaOf(op.outputSchema, "items")?.items);
         try {
             for await (const item of callResult) {
                 process.stdout.write(JSON.stringify(fieldsCheck.item(item)) + "\n");
@@ -3051,7 +3316,7 @@ async function main() {
     if (result.ok) {
         if (op.sse || streaming) {
             // Server-sent events as NDJSON, one line per event, until the stream ends.
-            const fieldsCheck = streamFieldsCheck();
+            const fieldsCheck = streamFieldsCheck(undefined);
             try {
                 for await (const event of result.data) {
                     process.stdout.write(JSON.stringify(fieldsCheck.item(event)) + "\n");
@@ -3100,18 +3365,18 @@ async function main() {
             // agent never has to reconstruct the cursor flag.
             const page = result.data;
             const next = page.nextPageParams();
-            out({
-                items: project(page.items, true),
+            printResult({
+                items: project(page.items, true, listSchemaOf(op.outputSchema, "items")),
                 hasMore: next !== null,
                 ...(next !== null ? { nextPage: next, nextCommand: nextCommandFor(op, pathValues, next) } : {}),
                 ...(page.response.requestId ? { request_id: page.response.requestId } : {}),
-            });
+            }, op.command[0]);
         }
         else if (FIELDS !== null && collectionField !== null && result.data !== null && typeof result.data === "object" && !Array.isArray(result.data) && Array.isArray(result.data[collectionField])) {
             // Batch-style collection envelopes ({data: [...]}) use item-relative
             // fields, matching paginated results, while retaining envelope metadata.
             const data = result.data;
-            out({ ...data, [collectionField]: project(data[collectionField], true) });
+            printResult({ ...data, [collectionField]: project(data[collectionField], true, listSchemaOf(op.outputSchema, collectionField)) }, op.command[0], collectionField);
         }
         else if (outDir !== undefined && bundleField !== null) {
             // --out: a file-shaped response (an array of {path, content}) lands
@@ -3120,10 +3385,10 @@ async function main() {
             const files = data[bundleField] ?? [];
             const written = writeBundle(outDir, files);
             const { [bundleField]: _omitted, ...rest } = data;
-            out({ ...project(rest, false), out: written });
+            printResult({ ...project(rest, false, op.outputSchema), out: written }, op.command[0]);
         }
         else {
-            out(result.data === undefined || result.data === null ? { ok: true } : project(result.data, Array.isArray(result.data)));
+            printResult(result.data === undefined || result.data === null ? { ok: true } : project(result.data, Array.isArray(result.data), op.outputSchema), op.command[0], collectionField);
         }
         await flushExit(0);
     }