@hardfin/cli 0.0.2-dev.10 → 0.0.2-dev.12

package/dist/cli.js

@@ -2,12 +2,13 @@
 import { createRequire } from "node:module";
 import { Command, Option } from "commander";
 import { z } from "zod";
-import { chmodSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, writeSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
+import { chmodSync, closeSync, existsSync, mkdirSync, openAsBlob, openSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, writeSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
 import { arch, cpus, homedir, release, totalmem, type, version } from "node:os";
-import { spawnSync } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 import { createServer } from "node:http";
 import { createHash, randomBytes } from "node:crypto";
+import { createInterface } from "node:readline";
 //#region src/command/registry.ts
 /** ExitCode is what the process returns, and what an agent branches on. */
 const ExitCode = {
@@ -197,24 +198,34 @@ function toGuide(commands, version) {
 		"## Commands",
 		""
 	];
-	for (const command of commands) {
-		lines.push(`### \`hardfin ${command.name}\``, "", command.description ?? command.summary, "");
-		if (command.arguments.length > 0) {
-			lines.push("| Argument | Required | Holds |", "| --- | --- | --- |");
-			for (const argument of command.arguments) lines.push(`| \`${argument.name}\` | ${argument.required ? "yes" : "no"} | ${argument.description} |`);
-			lines.push("");
-		}
-		if (command.flags.length > 0) {
-			lines.push("| Flag | Takes | Does |", "| --- | --- | --- |");
-			for (const flag of command.flags) {
-				const name = flag.short ? `-${flag.short}, --${flag.name}` : `--${flag.name}`;
-				lines.push(`| \`${name}\` | ${flag.valueName ?? "nothing"} | ${flag.description} |`);
-			}
-			lines.push("");
+	for (const command of commands.filter((command) => !command.hidden)) lines.push(...toCommandLines(command, []));
+	return lines.join("\n");
+}
+/** toCommandLines describes one command and everything nested under it. */
+function toCommandLines(command, parents) {
+	const path = [...parents, command.name];
+	const lines = [
+		`### \`hardfin ${path.join(" ")}\``,
+		"",
+		command.description ?? command.summary,
+		""
+	];
+	if (command.arguments.length > 0) {
+		lines.push("| Argument | Required | Holds |", "| --- | --- | --- |");
+		for (const argument of command.arguments) lines.push(`| \`${argument.name}\` | ${argument.required ? "yes" : "no"} | ${argument.description} |`);
+		lines.push("");
+	}
+	if (command.flags.length > 0) {
+		lines.push("| Flag | Takes | Does |", "| --- | --- | --- |");
+		for (const flag of command.flags) {
+			const name = flag.short ? `-${flag.short}, --${flag.name}` : `--${flag.name}`;
+			lines.push(`| \`${name}\` | ${flag.valueName ?? "nothing"} | ${flag.description} |`);
 		}
-		for (const example of command.examples) lines.push(`${example.description}:`, "", "```sh", example.command, "```", "");
+		lines.push("");
 	}
-	return lines.join("\n");
+	for (const example of command.examples) lines.push(`${example.description}:`, "", "```sh", example.command, "```", "");
+	for (const subcommand of command.subcommands ?? []) lines.push(...toCommandLines(subcommand, path));
+	return lines;
 }
 async function runAgentGuide(input) {
 	if (input.flags["json"] === true) {
@@ -603,11 +614,11 @@ async function request(options) {
 		"X-API-Version": API_VERSION,
 		Accept: "application/json"
 	};
-	if (options.body !== void 0) headers["Content-Type"] = "application/json";
+	if (options.body !== void 0 && options.form === void 0) headers["Content-Type"] = "application/json";
 	const response = await fetch(url, {
 		method: options.method,
 		headers,
-		body: options.body === void 0 ? void 0 : JSON.stringify(options.body)
+		body: options.form ?? (options.body === void 0 ? void 0 : JSON.stringify(options.body))
 	});
 	const envelope = toEnvelope(await response.text());
 	if (!response.ok && envelope === void 0) throw new RequestFailure(response.status, [{
@@ -760,6 +771,132 @@ function toBody$1(source) {
 	}
 }
 //#endregion
+//#region src/command/completion.ts
+const SHELLS = [
+	"bash",
+	"zsh",
+	"fish",
+	"powershell"
+];
+const completionCommand = defineCommand({
+	name: "completion",
+	summary: "Print the shell script that completes hardfin commands",
+	description: "Writes a script for your shell. The script asks this CLI what may follow what you have typed, so completions never fall behind the commands.",
+	arguments: [{
+		name: "shell",
+		description: `The shell to write for: ${SHELLS.join(", ")}`,
+		required: true
+	}],
+	flags: [],
+	examples: [
+		{
+			description: "Complete in this shell, now",
+			command: "source <(hardfin completion zsh)"
+		},
+		{
+			description: "Complete in every new shell",
+			command: "hardfin completion zsh > ~/.hardfin-completion.zsh"
+		},
+		{
+			description: "Complete in bash",
+			command: "source <(hardfin completion bash)"
+		}
+	],
+	run: runCompletion
+});
+/** The hidden command a completion script asks, which keeps one implementation for every shell. */
+const completeCommand = defineCommand({
+	name: "__complete",
+	summary: "Answer what may follow the words typed so far",
+	hidden: true,
+	arguments: [{
+		name: "words",
+		description: "The words typed so far",
+		required: false,
+		variadic: true
+	}],
+	flags: [{
+		name: "json",
+		description: "Accepted for consistency, and ignored",
+		schema: z.boolean()
+	}],
+	examples: [],
+	run: async (input) => {
+		writeData(toCandidates(input.commands, input.args).join("\n"));
+		return ExitCode.OK;
+	}
+});
+/**
+* toCandidates answers what may follow the words typed so far. A word starting with a dash
+* asks for the current command's flags, and anything else asks for its subcommands.
+*/
+function toCandidates(commands, words) {
+	const partial = words[words.length - 1] ?? "";
+	const walked = toWalked(commands, words.slice(0, -1));
+	if (partial.startsWith("-")) return toFlagNames(walked.command).filter((name) => name.startsWith(partial));
+	if (walked.isUnknown) return [];
+	return (walked.command?.subcommands ?? walked.remaining).map((command) => command.name).filter((name) => !name.startsWith("__")).filter((name) => name.startsWith(partial));
+}
+function toWalked(commands, words) {
+	let remaining = commands;
+	let command;
+	for (const word of words) {
+		if (word.startsWith("-") || command?.arguments.length) continue;
+		const found = remaining.find((entry) => entry.name === word);
+		if (!found) return {
+			command,
+			remaining,
+			isUnknown: true
+		};
+		command = found;
+		remaining = found.subcommands ?? [];
+	}
+	return {
+		command,
+		remaining,
+		isUnknown: false
+	};
+}
+function toFlagNames(command) {
+	return [...(command?.flags ?? []).map((flag) => `--${flag.name}`), "--help"];
+}
+async function runCompletion(input) {
+	const shell = String(input.args[0] ?? "");
+	if (!SHELLS.includes(shell)) {
+		writeFailure(`${shell || "no shell"} is not one this CLI writes for. Choose ${SHELLS.join(", ")}`, input.isJSON);
+		return ExitCode.USAGE;
+	}
+	writeData(toScript(shell));
+	return ExitCode.OK;
+}
+/** toScript writes a shell's completion, each one asking __complete for the candidates. */
+function toScript(shell) {
+	if (shell === "bash") return `# hardfin completion for bash
+_hardfin_complete() {
+  local words
+  words=("\${COMP_WORDS[@]:1}")
+  COMPREPLY=($(hardfin __complete -- "\${words[@]}" 2>/dev/null))
+}
+complete -F _hardfin_complete hardfin`;
+	if (shell === "zsh") return `# hardfin completion for zsh
+_hardfin_complete() {
+  local -a candidates
+  candidates=(\${(f)"$(hardfin __complete -- \${words[2,-1]} 2>/dev/null)"})
+  compadd -a candidates
+}
+compdef _hardfin_complete hardfin`;
+	if (shell === "fish") return `# hardfin completion for fish
+complete -c hardfin -f -a "(hardfin __complete -- (commandline -opc)[2..-1] 2>/dev/null)"`;
+	return `# hardfin completion for PowerShell
+Register-ArgumentCompleter -Native -CommandName hardfin -ScriptBlock {
+  param($wordToComplete, $commandAst, $cursorPosition)
+  $words = $commandAst.CommandElements | Select-Object -Skip 1 | ForEach-Object { $_.ToString() }
+  hardfin __complete -- @words 2>$null | ForEach-Object {
+    [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_)
+  }
+}`;
+}
+//#endregion
 //#region src/command/config.ts
 const configCommand = defineCommand({
 	name: "config",
@@ -1310,11 +1447,195 @@ async function runLogout(input) {
 	return ExitCode.OK;
 }
 //#endregion
+//#region src/mcp/server.ts
+const PROTOCOL_VERSION = "2025-06-18";
+const GUIDE_URI = "hardfin://guide";
+const COMMANDS_URI = "hardfin://commands";
+/**
+* One tool, because every tool a server lists sits in the agent's context for the whole
+* session. The commands themselves are resources, which cost nothing until one is read.
+*/
+const TOOL = {
+	name: "hardfin",
+	description: "Run a Hardfin CLI command against the Hardfin API. Pass the arguments as a list, such as [\"asset\", \"list\", \"--limit\", \"5\"]. Run [\"--help\"] for the commands, or read the hardfin://guide resource.",
+	inputSchema: {
+		type: "object",
+		properties: { args: {
+			type: "array",
+			items: { type: "string" },
+			description: "The arguments to hardfin, without the program name"
+		} },
+		required: ["args"]
+	}
+};
+/** toResponse answers one request, and answers nothing to a notification. */
+async function toResponse(request, commands, run) {
+	const answer = (result) => ({
+		jsonrpc: "2.0",
+		id: request.id ?? null,
+		result
+	});
+	switch (request.method) {
+		case "initialize": return answer({
+			protocolVersion: toProtocolVersion(request.params),
+			capabilities: {
+				tools: {},
+				resources: {}
+			},
+			serverInfo: {
+				name: "hardfin",
+				version: version$1
+			}
+		});
+		case "tools/list": return answer({ tools: [TOOL] });
+		case "resources/list": return answer({ resources: [{
+			uri: GUIDE_URI,
+			name: "Hardfin CLI guide",
+			description: "Every command, its flags, and the exit codes",
+			mimeType: "text/markdown"
+		}, {
+			uri: COMMANDS_URI,
+			name: "Hardfin CLI commands",
+			description: "The command tree as JSON",
+			mimeType: "application/json"
+		}] });
+		case "resources/read": return answer(toResource(String(request.params?.["uri"] ?? ""), commands));
+		case "tools/call": return answer(await toToolResult(request.params, run));
+		case "ping": return answer({});
+		default:
+			if (request.id === void 0 || request.id === null) return;
+			return {
+				jsonrpc: "2.0",
+				id: request.id,
+				error: {
+					code: -32601,
+					message: `${request.method} is not a method this server offers`
+				}
+			};
+	}
+}
+function toProtocolVersion(params) {
+	const asked = params?.["protocolVersion"];
+	return typeof asked === "string" ? asked : PROTOCOL_VERSION;
+}
+function toResource(uri, commands) {
+	if (uri === GUIDE_URI) return { contents: [{
+		uri,
+		mimeType: "text/markdown",
+		text: toGuide(commands, version$1)
+	}] };
+	if (uri === COMMANDS_URI) return { contents: [{
+		uri,
+		mimeType: "application/json",
+		text: JSON.stringify(toTree(commands), null, 2)
+	}] };
+	return {
+		contents: [],
+		isError: true
+	};
+}
+/** toTree names every command and what it takes, without the schemas a tool list would carry. */
+function toTree(commands) {
+	return commands.map((command) => ({
+		name: command.name,
+		summary: command.summary,
+		arguments: command.arguments.map((argument) => argument.name),
+		flags: command.flags.map((flag) => flag.valueName ? `--${flag.name} <${flag.valueName}>` : `--${flag.name}`),
+		subcommands: command.subcommands ? toTree(command.subcommands) : void 0
+	}));
+}
+async function toToolResult(params, run) {
+	const args = (params?.["arguments"])?.args;
+	if (!Array.isArray(args) || args.some((entry) => typeof entry !== "string")) return {
+		content: [{
+			type: "text",
+			text: "args must be a list of strings, such as [\"asset\", \"list\"]"
+		}],
+		isError: true
+	};
+	const outcome = await run(args);
+	return {
+		content: [{
+			type: "text",
+			text: [outcome.stdout, outcome.stderr].filter((part) => part.trim() !== "").join("\n") || `hardfin exited ${outcome.code}`
+		}],
+		isError: outcome.code !== 0
+	};
+}
+/** toCliRunner runs the CLI itself, so a tool call parses exactly as a terminal would. */
+function toCliRunner() {
+	return (args) => new Promise((resolve) => {
+		const child = spawn(process.execPath, [process.argv[1] ?? "", ...args], { env: {
+			...process.env,
+			HARDFIN_NO_BROWSER: "1"
+		} });
+		let stdout = "";
+		let stderr = "";
+		child.stdout.on("data", (chunk) => {
+			stdout += chunk.toString();
+		});
+		child.stderr.on("data", (chunk) => {
+			stderr += chunk.toString();
+		});
+		child.on("close", (code) => resolve({
+			stdout,
+			stderr,
+			code: code ?? 1
+		}));
+	});
+}
+/** serve answers requests on stdin until the client closes it. */
+async function serve(commands, run = toCliRunner()) {
+	const lines = createInterface({ input: process.stdin });
+	for await (const line of lines) {
+		if (line.trim() === "") continue;
+		let response;
+		try {
+			response = await toResponse(JSON.parse(line), commands, run);
+		} catch (error) {
+			response = {
+				jsonrpc: "2.0",
+				id: null,
+				error: {
+					code: -32700,
+					message: error instanceof Error ? error.message : String(error)
+				}
+			};
+		}
+		if (response) process.stdout.write(`${JSON.stringify(response)}\n`);
+	}
+}
+//#endregion
+//#region src/command/mcp.ts
+const mcpCommand = defineCommand({
+	name: "mcp",
+	summary: "Serve this CLI to an agent over the Model Context Protocol",
+	description: "Speaks the Model Context Protocol on standard input and output. It offers one tool, because every tool an agent is told about occupies its context for the whole session, and serves the commands as resources the agent reads only when it needs them.",
+	arguments: [],
+	flags: [{
+		name: "json",
+		description: "Accepted for consistency, and ignored, because the protocol decides the output",
+		schema: z.boolean()
+	}],
+	examples: [{
+		description: "Register with an agent",
+		command: "hardfin mcp"
+	}, {
+		description: "Add it to Claude Code",
+		command: "claude mcp add hardfin -- hardfin mcp"
+	}],
+	run: runMcp
+});
+async function runMcp(input) {
+	await serve(input.commands);
+	return ExitCode.OK;
+}
+//#endregion
 //#region src/command/operation.ts
-const INPUT_FLAG = {
-	name: "input",
-	description: "A file holding the JSON request body, or - for stdin",
-	valueName: "file",
+const FILE_FLAG = {
+	name: "file",
+	description: "The file to upload",
+	valueName: "path",
 	schema: z.string()
 };
 const JSON_FLAG = {
@@ -1324,15 +1645,22 @@ const JSON_FLAG = {
 };
 /** defineOperation turns one endpoint into the command that calls it. */
 function defineOperation(operation) {
-	const flags = [...operation.queryFlags, JSON_FLAG];
-	if (operation.takesBody) flags.splice(flags.length - 1, 0, INPUT_FLAG);
+	const flags = [
+		...operation.queryFlags,
+		...operation.bodyFlags,
+		...operation.upload ? [...operation.upload.fields, FILE_FLAG] : [],
+		JSON_FLAG
+	];
 	return {
 		name: operation.name,
 		summary: operation.summary,
 		description: operation.description ?? operation.summary,
 		arguments: operation.pathParameters,
 		flags,
-		examples: [],
+		examples: operation.example ? [{
+			description: operation.summary,
+			command: operation.example
+		}] : [],
 		run: (input) => runOperation(operation, input)
 	};
 }
@@ -1342,13 +1670,24 @@ async function runOperation(operation, input) {
 		writeFailure(`this command takes ${operation.pathParameters.length} argument(s)`, input.isJSON);
 		return ExitCode.USAGE;
 	}
-	let body;
-	if (typeof input.flags["input"] === "string") {
-		body = toBody(input.flags["input"]);
-		if (body === void 0) {
-			writeFailure(`${input.flags["input"]} does not hold JSON`, input.isJSON);
+	const missing = operation.bodyFlags.concat(operation.upload?.fields ?? []).filter((flag) => flag.required && input.flags[toOptionKey(flag.name)] === void 0);
+	if (missing.length > 0) {
+		writeFailure(`this command needs ${missing.map((flag) => `--${flag.name}`).join(", ")}`, input.isJSON);
+		return ExitCode.USAGE;
+	}
+	const body = toBody(operation, input.flags);
+	if (body instanceof Error) {
+		writeFailure(body.message, input.isJSON);
+		return ExitCode.USAGE;
+	}
+	let form;
+	if (operation.upload) {
+		const built = await toForm(operation.upload, input.flags);
+		if (built instanceof Error) {
+			writeFailure(built.message, input.isJSON);
 			return ExitCode.USAGE;
 		}
+		form = built;
 	}
 	try {
 		writeData((await request({
@@ -1357,7 +1696,8 @@ async function runOperation(operation, input) {
 			method: operation.method,
 			path,
 			query: toQuery(operation, input.flags),
-			body
+			body,
+			form
 		})).data);
 		return ExitCode.OK;
 	} catch (error) {
@@ -1394,13 +1734,65 @@ function toQuery(operation, flags) {
 function toOptionKey(name) {
 	return name.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
 }
-function toBody(source) {
-	const text = source === "-" ? readFileSync(0, "utf8") : readFileSync(source, "utf8");
+/** toForm builds the file part and its fields, which an upload endpoint takes. */
+async function toForm(upload, flags) {
+	const path = flags["file"];
+	if (typeof path !== "string") return /* @__PURE__ */ new Error("this command needs --file, the file to upload");
+	const form = new FormData();
 	try {
-		return JSON.parse(text);
+		form.append(upload.filePart, await openAsBlob(path), basename(path));
 	} catch {
-		return;
+		return /* @__PURE__ */ new Error(`${path} cannot be read`);
+	}
+	for (const field of upload.fields) {
+		const value = flags[toOptionKey(field.name)];
+		if (value !== void 0) form.append(field.jsonPath[0] ?? field.name, String(value));
+	}
+	return form;
+}
+/** toBody builds the request body from the flags, one field at a time. */
+function toBody(operation, flags) {
+	const body = {};
+	let hasField = false;
+	for (const flag of operation.bodyFlags) {
+		const value = flags[toOptionKey(flag.name)];
+		if (value === void 0) continue;
+		if (flag.element) {
+			const elements = toElements(flag, Array.isArray(value) ? value.map(String) : [String(value)]);
+			if (elements instanceof Error) return elements;
+			set(body, flag.jsonPath, elements);
+			hasField = true;
+			continue;
+		}
+		set(body, flag.jsonPath, value);
+		hasField = true;
+	}
+	return hasField ? body : void 0;
+}
+/** toElements reads the key=value pairs a repeated flag carries for one array element. */
+function toElements(flag, values) {
+	const elements = [];
+	for (const value of values) {
+		const element = {};
+		for (const pair of value.split(",")) {
+			const split = pair.indexOf("=");
+			if (split < 1) return /* @__PURE__ */ new Error(`--${flag.name} takes ${flag.element?.join("=, ")}=, such as --${flag.name} ${flag.element?.[0]}=value`);
+			const key = pair.slice(0, split);
+			if (flag.element && !flag.element.includes(key)) return /* @__PURE__ */ new Error(`--${flag.name} has no field ${key}. It takes ${flag.element.join(", ")}`);
+			element[key] = pair.slice(split + 1);
+		}
+		elements.push(element);
+	}
+	return elements;
+}
+/** set writes a value at its path, building the objects a nested field needs. */
+function set(body, path, value) {
+	let holder = body;
+	for (const name of path.slice(0, -1)) {
+		holder[name] = holder[name] ?? {};
+		holder = holder[name];
 	}
+	holder[path[path.length - 1] ?? ""] = value;
 }
 //#endregion
 //#region src/command/surface.generated.ts
@@ -1415,6 +1807,7 @@ const surfaceCommands = [
 			defineOperation({
 				name: "list",
 				summary: "Get asset listing",
+				example: "hardfin asset list --limit 10",
 				method: "GET",
 				path: "/asset",
 				pathParameters: [],
@@ -1598,16 +1991,170 @@ const surfaceCommands = [
 						])
 					}
 				],
-				takesBody: false
+				bodyFlags: []
 			}),
 			defineOperation({
 				name: "create",
 				summary: "Create asset",
+				example: "hardfin asset create --item-id <value> --serial <value>",
 				method: "POST",
 				path: "/asset",
 				pathParameters: [],
 				queryFlags: [],
-				takesBody: true
+				bodyFlags: [
+					{
+						name: "allocated-indirect",
+						jsonPath: ["allocatedIndirect"],
+						description: "One unit's share of overhead, a cost component",
+						valueName: "value",
+						schema: z.string()
+					},
+					{
+						name: "bill-of-materials",
+						jsonPath: ["billOfMaterials"],
+						description: "The parts cost of one unit, a cost component",
+						valueName: "value",
+						schema: z.string()
+					},
+					{
+						name: "depreciation-model",
+						jsonPath: ["depreciationModel"],
+						description: "The method one unit is depreciated by, or null to clear it",
+						valueName: "value",
+						schema: z.enum([
+							"DOUBLE_DECLINING",
+							"STRAIGHT_LINE",
+							"SUM_YEAR",
+							"UNIT_OF_PRODUCTION"
+						])
+					},
+					{
+						name: "description",
+						jsonPath: ["description"],
+						description: "A free-form description of the asset",
+						valueName: "value",
+						schema: z.string()
+					},
+					{
+						name: "direct-labor",
+						jsonPath: ["directLabor"],
+						description: "The labor cost to build one unit, a cost component",
+						valueName: "value",
+						schema: z.string()
+					},
+					{
+						name: "freight-inbound",
+						jsonPath: ["freightInbound"],
+						description: "The shipping cost to receive one unit, a cost component",
+						valueName: "value",
+						schema: z.string()
+					},
+					{
+						name: "freight-outbound",
+						jsonPath: ["freightOutbound"],
+						description: "The shipping cost to deploy one unit, a deployment cost component",
+						valueName: "value",
+						schema: z.string()
+					},
+					{
+						name: "functional-status",
+						jsonPath: ["functionalStatus"],
+						description: "The asset's starting functional status, FUNCTIONAL when absent, which cannot be SCRAPPED",
+						valueName: "value",
+						schema: z.enum([
+							"FUNCTIONAL",
+							"NEEDS_REVIEW",
+							"NON-FUNCTIONAL",
+							"SCRAPPED"
+						])
+					},
+					{
+						name: "in-inventory-date",
+						jsonPath: ["inInventoryDate"],
+						description: "The day the asset entered inventory, which cannot be in the future",
+						valueName: "value",
+						schema: z.string()
+					},
+					{
+						name: "in-service-date",
+						jsonPath: ["inServiceDate"],
+						description: "The day the asset was put into service, which Hardfin sets itself when absent",
+						valueName: "value",
+						schema: z.string()
+					},
+					{
+						name: "installation",
+						jsonPath: ["installation"],
+						description: "The cost to install one unit, a deployment cost component",
+						valueName: "value",
+						schema: z.string()
+					},
+					{
+						name: "interest",
+						jsonPath: ["interest"],
+						description: "The financing cost of one unit, a cost component",
+						valueName: "value",
+						schema: z.string()
+					},
+					{
+						name: "item-id",
+						jsonPath: ["itemId"],
+						description: "The ID of the catalog item the asset is a unit of",
+						valueName: "value",
+						required: true,
+						schema: z.string()
+					},
+					{
+						name: "location-id",
+						jsonPath: ["locationId"],
+						description: "The ID of the location the asset enters inventory at",
+						valueName: "value",
+						schema: z.string()
+					},
+					{
+						name: "salvage-value",
+						jsonPath: ["salvageValue"],
+						description: "The value one unit keeps at the end of its useful life, or null to clear it",
+						valueName: "value",
+						schema: z.string()
+					},
+					{
+						name: "serial",
+						jsonPath: ["serial"],
+						description: "The asset's serial number, unique within its item",
+						valueName: "value",
+						required: true,
+						schema: z.string()
+					},
+					{
+						name: "simple-cost-basis",
+						jsonPath: ["simpleCostBasis"],
+						description: "A single cost for one unit, which cannot be sent together with the cost components",
+						valueName: "value",
+						schema: z.string()
+					},
+					{
+						name: "tariffs",
+						jsonPath: ["tariffs"],
+						description: "The import duty paid on one unit, a cost component",
+						valueName: "value",
+						schema: z.string()
+					},
+					{
+						name: "tax",
+						jsonPath: ["tax"],
+						description: "The tax paid on one unit, a cost component",
+						valueName: "value",
+						schema: z.string()
+					},
+					{
+						name: "useful-life",
+						jsonPath: ["usefulLife"],
+						description: "The number of months one unit is depreciated over, or null to clear it",
+						valueName: "number",
+						schema: z.coerce.number()
+					}
+				]
 			}),
 			{
 				name: "move",
@@ -1624,11 +2171,28 @@ const surfaceCommands = [
 					subcommands: [defineOperation({
 						name: "create",
 						summary: "Execute asset move",
+						example: "hardfin asset move execute create",
 						method: "POST",
 						path: "/asset/move/execute",
 						pathParameters: [],
 						queryFlags: [],
-						takesBody: true
+						bodyFlags: [{
+							name: "move",
+							jsonPath: ["moves"],
+							description: "The moves to carry out",
+							valueName: "assetId=,deliverAt=",
+							repeatable: true,
+							element: [
+								"assetId",
+								"deliverAt",
+								"deliverAtTimezone",
+								"destinationId",
+								"originId",
+								"shipAt",
+								"shipAtTimezone"
+							],
+							schema: z.array(z.string())
+						}]
 					})]
 				}, {
 					name: "plan",
@@ -1639,17 +2203,32 @@ const surfaceCommands = [
 					subcommands: [defineOperation({
 						name: "create",
 						summary: "Plan asset move",
+						example: "hardfin asset move plan create",
 						method: "POST",
 						path: "/asset/move/plan",
 						pathParameters: [],
 						queryFlags: [],
-						takesBody: true
+						bodyFlags: [{
+							name: "move",
+							jsonPath: ["moves"],
+							description: "The moves to plan",
+							valueName: "assetId=,deliverAt=",
+							repeatable: true,
+							element: [
+								"assetId",
+								"deliverAt",
+								"id",
+								"shipAt"
+							],
+							schema: z.array(z.string())
+						}]
 					})]
 				}]
 			},
 			defineOperation({
 				name: "get",
 				summary: "Get asset",
+				example: "hardfin asset get ast_4f9xk2mq7plr8stz",
 				method: "GET",
 				path: "/asset/{assetKey}",
 				pathParameters: [{
@@ -1658,11 +2237,12 @@ const surfaceCommands = [
 					required: true
 				}],
 				queryFlags: [],
-				takesBody: false
+				bodyFlags: []
 			}),
 			defineOperation({
 				name: "update",
 				summary: "Patch asset",
+				example: "hardfin asset update ast_4f9xk2mq7plr8stz",
 				method: "PATCH",
 				path: "/asset/{assetKey}",
 				pathParameters: [{
@@ -1671,7 +2251,57 @@ const surfaceCommands = [
 					required: true
 				}],
 				queryFlags: [],
-				takesBody: true
+				bodyFlags: [
+					{
+						name: "description",
+						jsonPath: ["description"],
+						description: "The asset's new description, or null to clear it",
+						valueName: "value",
+						schema: z.string()
+					},
+					{
+						name: "functional-status",
+						jsonPath: ["functionalStatus"],
+						description: "The asset's new functional status, which cannot be SCRAPPED because scrapping has its own endpoint",
+						valueName: "value",
+						schema: z.enum([
+							"FUNCTIONAL",
+							"NEEDS_REVIEW",
+							"NON-FUNCTIONAL",
+							"SCRAPPED"
+						])
+					},
+					{
+						name: "in-inventory-date",
+						jsonPath: ["inInventoryDate"],
+						description: "The day the asset entered inventory, which cannot be in the future",
+						valueName: "value",
+						schema: z.string()
+					},
+					{
+						name: "initial-location-id",
+						jsonPath: ["initialLocationId"],
+						description: "The ID of the location the asset entered inventory at",
+						valueName: "value",
+						schema: z.string()
+					},
+					{
+						name: "metadata",
+						jsonPath: ["metadata"],
+						description: "New values for the asset's custom fields, each naming its field",
+						valueName: "fieldId=,value=",
+						repeatable: true,
+						element: ["fieldId", "value"],
+						schema: z.array(z.string())
+					},
+					{
+						name: "serial",
+						jsonPath: ["serial"],
+						description: "The asset's new serial number, which cannot be empty",
+						valueName: "value",
+						schema: z.string()
+					}
+				]
 			}),
 			{
 				name: "accounting",
@@ -1682,6 +2312,7 @@ const surfaceCommands = [
 				subcommands: [defineOperation({
 					name: "update",
 					summary: "Update asset accounting",
+					example: "hardfin asset accounting update ast_4f9xk2mq7plr8stz",
 					method: "PATCH",
 					path: "/asset/{assetKey}/accounting",
 					pathParameters: [{
@@ -1690,7 +2321,117 @@ const surfaceCommands = [
 						required: true
 					}],
 					queryFlags: [],
-					takesBody: true
+					bodyFlags: [
+						{
+							name: "allocated-indirect",
+							jsonPath: ["allocatedIndirect"],
+							description: "One unit's share of overhead, a cost component",
+							valueName: "value",
+							schema: z.string()
+						},
+						{
+							name: "bill-of-materials",
+							jsonPath: ["billOfMaterials"],
+							description: "The parts cost of one unit, a cost component",
+							valueName: "value",
+							schema: z.string()
+						},
+						{
+							name: "depreciation-model",
+							jsonPath: ["depreciationModel"],
+							description: "The method one unit is depreciated by, or null to clear it",
+							valueName: "value",
+							schema: z.enum([
+								"DOUBLE_DECLINING",
+								"STRAIGHT_LINE",
+								"SUM_YEAR",
+								"UNIT_OF_PRODUCTION"
+							])
+						},
+						{
+							name: "direct-labor",
+							jsonPath: ["directLabor"],
+							description: "The labor cost to build one unit, a cost component",
+							valueName: "value",
+							schema: z.string()
+						},
+						{
+							name: "freight-inbound",
+							jsonPath: ["freightInbound"],
+							description: "The shipping cost to receive one unit, a cost component",
+							valueName: "value",
+							schema: z.string()
+						},
+						{
+							name: "freight-outbound",
+							jsonPath: ["freightOutbound"],
+							description: "The shipping cost to deploy one unit, a deployment cost component",
+							valueName: "value",
+							schema: z.string()
+						},
+						{
+							name: "in-service-date",
+							jsonPath: ["inServiceDate"],
+							description: "The day the asset was put into service and began depreciating, or null to clear it",
+							valueName: "value",
+							schema: z.string()
+						},
+						{
+							name: "installation",
+							jsonPath: ["installation"],
+							description: "The cost to install one unit, a deployment cost component",
+							valueName: "value",
+							schema: z.string()
+						},
+						{
+							name: "interest",
+							jsonPath: ["interest"],
+							description: "The financing cost of one unit, a cost component",
+							valueName: "value",
+							schema: z.string()
+						},
+						{
+							name: "is-in-service-date-managed-automatically",
+							jsonPath: ["isInServiceDateManagedAutomatically"],
+							description: "Whether Hardfin sets the in-service date itself, which sending an in-service date turns off",
+							schema: z.boolean()
+						},
+						{
+							name: "salvage-value",
+							jsonPath: ["salvageValue"],
+							description: "The value one unit keeps at the end of its useful life, or null to clear it",
+							valueName: "value",
+							schema: z.string()
+						},
+						{
+							name: "simple-cost-basis",
+							jsonPath: ["simpleCostBasis"],
+							description: "A single cost for one unit, which cannot be sent together with the cost components",
+							valueName: "value",
+							schema: z.string()
+						},
+						{
+							name: "tariffs",
+							jsonPath: ["tariffs"],
+							description: "The import duty paid on one unit, a cost component",
+							valueName: "value",
+							schema: z.string()
+						},
+						{
+							name: "tax",
+							jsonPath: ["tax"],
+							description: "The tax paid on one unit, a cost component",
+							valueName: "value",
+							schema: z.string()
+						},
+						{
+							name: "useful-life",
+							jsonPath: ["usefulLife"],
+							description: "The number of months one unit is depreciated over, or null to clear it",
+							valueName: "number",
+							schema: z.coerce.number()
+						}
+					]
 				}), {
 					name: "in-service-management",
 					summary: "In service management commands",
@@ -1700,6 +2441,7 @@ const surfaceCommands = [
 					subcommands: [defineOperation({
 						name: "update",
 						summary: "Toggle in service date management",
+						example: "hardfin asset accounting in-service-management update ast_4f9xk2mq7plr8stz --automatic <value>",
 						method: "PATCH",
 						path: "/asset/{assetKey}/accounting/in-service-management",
 						pathParameters: [{
@@ -1708,7 +2450,13 @@ const surfaceCommands = [
 							required: true
 						}],
 						queryFlags: [],
-						takesBody: true
+						bodyFlags: [{
+							name: "automatic",
+							jsonPath: ["automatic"],
+							description: "Whether Hardfin sets the asset's in-service date itself",
+							required: true,
+							schema: z.boolean()
+						}]
 					})]
 				}]
 			},
@@ -1721,6 +2469,7 @@ const surfaceCommands = [
 				subcommands: [defineOperation({
 					name: "create",
 					summary: "Create asset cost adjustment",
+					example: "hardfin asset cost-adjustment create ast_4f9xk2mq7plr8stz --adjustment-type <value> --amount <value> --effective-date <value>",
 					method: "POST",
 					path: "/asset/{assetKey}/cost-adjustment",
 					pathParameters: [{
@@ -1729,7 +2478,57 @@ const surfaceCommands = [
 						required: true
 					}],
 					queryFlags: [],
-					takesBody: true
+					bodyFlags: [
+						{
+							name: "adjustment-type",
+							jsonPath: ["adjustmentType"],
+							description: "Whether the adjustment adds to the asset's cost basis or writes it down",
+							valueName: "value",
+							required: true,
+							schema: z.enum(["CAPITALIZATION", "IMPAIRMENT"])
+						},
+						{
+							name: "amount",
+							jsonPath: ["amount"],
+							description: "How much the adjustment changes the cost basis by, which must be greater than zero",
+							valueName: "value",
+							required: true,
+							schema: z.string()
+						},
+						{
+							name: "effective-date",
+							jsonPath: ["effectiveDate"],
+							description: "The day the adjustment takes effect, which cannot be in the future",
+							valueName: "value",
+							required: true,
+							schema: z.string()
+						},
+						{
+							name: "notes",
+							jsonPath: ["notes"],
+							description: "Free-form detail about the adjustment, which a reason of OTHER requires",
+							valueName: "value",
+							schema: z.string()
+						},
+						{
+							name: "reason",
+							jsonPath: ["reason"],
+							description: "Why the adjustment was made, which must be one its adjustment type allows",
+							valueName: "value",
+							required: true,
+							schema: z.enum([
+								"ADDITION",
+								"BETTERMENT",
+								"DAMAGE",
+								"INSTALLATION",
+								"LIFE_EXTENSION",
+								"MARKET_DECLINE",
+								"OBSOLESCENCE",
+								"OTHER",
+								"REGULATORY"
+							])
+						}
+					]
 				})]
 			},
 			{
@@ -1741,6 +2540,7 @@ const surfaceCommands = [
 				subcommands: [defineOperation({
 					name: "list",
 					summary: "Get asset event list",
+					example: "hardfin asset event list ast_4f9xk2mq7plr8stz",
 					method: "GET",
 					path: "/asset/{assetKey}/event",
 					pathParameters: [{
@@ -1749,7 +2549,7 @@ const surfaceCommands = [
 						required: true
 					}],
 					queryFlags: [],
-					takesBody: false
+					bodyFlags: []
 				})]
 			},
 			{
@@ -1761,6 +2561,7 @@ const surfaceCommands = [
 				subcommands: [defineOperation({
 					name: "list",
 					summary: "Get asset event group listing",
+					example: "hardfin asset event-group list ast_4f9xk2mq7plr8stz",
 					method: "GET",
 					path: "/asset/{assetKey}/event-group",
 					pathParameters: [{
@@ -1781,10 +2582,11 @@ const surfaceCommands = [
 						valueName: "value",
 						schema: z.string()
 					}],
-					takesBody: false
+					bodyFlags: []
 				}), defineOperation({
 					name: "get",
 					summary: "Get asset event group",
+					example: "hardfin asset event-group get ast_4f9xk2mq7plr8stz aeg_3mx8kq2plr7stz4w",
 					method: "GET",
 					path: "/asset/{assetKey}/event-group/{eventGroupKey}",
 					pathParameters: [{
@@ -1797,7 +2599,7 @@ const surfaceCommands = [
 						required: true
 					}],
 					queryFlags: [],
-					takesBody: false
+					bodyFlags: []
 				})]
 			},
 			{
@@ -1809,6 +2611,7 @@ const surfaceCommands = [
 				subcommands: [defineOperation({
 					name: "list",
 					summary: "Get asset files",
+					example: "hardfin asset file list ast_4f9xk2mq7plr8stz",
 					method: "GET",
 					path: "/asset/{assetKey}/file",
 					pathParameters: [{
@@ -1817,10 +2620,11 @@ const surfaceCommands = [
 						required: true
 					}],
 					queryFlags: [],
-					takesBody: false
+					bodyFlags: []
 				}), defineOperation({
 					name: "delete",
 					summary: "Delete asset file",
+					example: "hardfin asset file delete ast_4f9xk2mq7plr8stz file_7hq2mx9pkr4stz8w",
 					method: "DELETE",
 					path: "/asset/{assetKey}/file/{fileKey}",
 					pathParameters: [{
@@ -1833,7 +2637,7 @@ const surfaceCommands = [
 						required: true
 					}],
 					queryFlags: [],
-					takesBody: false
+					bodyFlags: []
 				})]
 			},
 			{
@@ -1845,6 +2649,7 @@ const surfaceCommands = [
 				subcommands: [defineOperation({
 					name: "list",
 					summary: "Get asset functional status history",
+					example: "hardfin asset functional-status list ast_4f9xk2mq7plr8stz",
 					method: "GET",
 					path: "/asset/{assetKey}/functional-status",
 					pathParameters: [{
@@ -1853,7 +2658,7 @@ const surfaceCommands = [
 						required: true
 					}],
 					queryFlags: [],
-					takesBody: false
+					bodyFlags: []
 				})]
 			},
 			{
@@ -1866,6 +2671,7 @@ const surfaceCommands = [
 					defineOperation({
 						name: "list",
 						summary: "Get asset ownership history",
+						example: "hardfin asset ownership list ast_4f9xk2mq7plr8stz",
 						method: "GET",
 						path: "/asset/{assetKey}/ownership",
 						pathParameters: [{
@@ -1874,11 +2680,12 @@ const surfaceCommands = [
 							required: true
 						}],
 						queryFlags: [],
-						takesBody: false
+						bodyFlags: []
 					}),
 					defineOperation({
 						name: "create",
 						summary: "Create asset ownership",
+						example: "hardfin asset ownership create ast_4f9xk2mq7plr8stz --customer-id <value> --date <value>",
 						method: "POST",
 						path: "/asset/{assetKey}/ownership",
 						pathParameters: [{
@@ -1887,11 +2694,36 @@ const surfaceCommands = [
 							required: true
 						}],
 						queryFlags: [],
-						takesBody: true
+						bodyFlags: [
+							{
+								name: "customer-id",
+								jsonPath: ["customerId"],
+								description: "The ID of the customer that takes ownership of the asset",
+								valueName: "value",
+								required: true,
+								schema: z.string()
+							},
+							{
+								name: "date",
+								jsonPath: ["date"],
+								description: "The day the customer takes ownership, which cannot be in the future",
+								valueName: "value",
+								required: true,
+								schema: z.string()
+							},
+							{
+								name: "sale-price",
+								jsonPath: ["salePrice"],
+								description: "What the customer paid for the asset, which cannot be negative",
+								valueName: "value",
+								schema: z.string()
+							}
+						]
 					}),
 					defineOperation({
 						name: "clear",
 						summary: "Clear the ownership an asset holds today",
+						example: "hardfin asset ownership clear ast_4f9xk2mq7plr8stz --date <value>",
 						method: "DELETE",
 						path: "/asset/{assetKey}/ownership",
 						pathParameters: [{
@@ -1900,11 +2732,19 @@ const surfaceCommands = [
 							required: true
 						}],
 						queryFlags: [],
-						takesBody: true
+						bodyFlags: [{
+							name: "date",
+							jsonPath: ["date"],
+							description: "The day your organization takes the asset back, which cannot be in the future",
+							valueName: "value",
+							required: true,
+							schema: z.string()
+						}]
 					}),
 					defineOperation({
 						name: "get",
 						summary: "Get asset ownership segment",
+						example: "hardfin asset ownership get ast_4f9xk2mq7plr8stz aown_8kq2mx7plr4stz9w",
 						method: "GET",
 						path: "/asset/{assetKey}/ownership/{segmentKey}",
 						pathParameters: [{
@@ -1917,11 +2757,12 @@ const surfaceCommands = [
 							required: true
 						}],
 						queryFlags: [],
-						takesBody: false
+						bodyFlags: []
 					}),
 					defineOperation({
 						name: "update",
 						summary: "Patch asset ownership segment",
+						example: "hardfin asset ownership update ast_4f9xk2mq7plr8stz aown_8kq2mx7plr4stz9w",
 						method: "PATCH",
 						path: "/asset/{assetKey}/ownership/{segmentKey}",
 						pathParameters: [{
@@ -1934,11 +2775,34 @@ const surfaceCommands = [
 							required: true
 						}],
 						queryFlags: [],
-						takesBody: true
+						bodyFlags: [
+							{
+								name: "customer-id",
+								jsonPath: ["customerId"],
+								description: "The ID of the customer that owned the asset during the segment",
+								valueName: "value",
+								schema: z.string()
+							},
+							{
+								name: "date",
+								jsonPath: ["date"],
+								description: "The day the segment's owner took ownership, which cannot be in the future",
+								valueName: "value",
+								schema: z.string()
+							},
+							{
+								name: "sale-price",
+								jsonPath: ["salePrice"],
+								description: "What the owner paid for the asset, which cannot be negative",
+								valueName: "value",
+								schema: z.string()
+							}
+						]
 					}),
 					defineOperation({
 						name: "delete",
 						summary: "Delete asset ownership segment",
+						example: "hardfin asset ownership delete ast_4f9xk2mq7plr8stz aown_8kq2mx7plr4stz9w",
 						method: "DELETE",
 						path: "/asset/{assetKey}/ownership/{segmentKey}",
 						pathParameters: [{
@@ -1951,7 +2815,7 @@ const surfaceCommands = [
 							required: true
 						}],
 						queryFlags: [],
-						takesBody: false
+						bodyFlags: []
 					})
 				]
 			},
@@ -1964,6 +2828,7 @@ const surfaceCommands = [
 				subcommands: [defineOperation({
 					name: "create",
 					summary: "Scrap asset",
+					example: "hardfin asset scrap create ast_4f9xk2mq7plr8stz --disposal-date <value>",
 					method: "POST",
 					path: "/asset/{assetKey}/scrap",
 					pathParameters: [{
@@ -1972,7 +2837,30 @@ const surfaceCommands = [
 						required: true
 					}],
 					queryFlags: [],
-					takesBody: true
+					bodyFlags: [
+						{
+							name: "disposal-date",
+							jsonPath: ["disposalDate"],
+							description: "The day the asset was scrapped",
+							valueName: "value",
+							required: true,
+							schema: z.string()
+						},
+						{
+							name: "disposal-price",
+							jsonPath: ["disposalPrice"],
+							description: "What the scrapped asset was sold for, or null when it was not sold",
+							valueName: "value",
+							schema: z.string()
+						},
+						{
+							name: "disposal-reason",
+							jsonPath: ["disposalReason"],
+							description: "Why the asset was scrapped",
+							valueName: "value",
+							schema: z.string()
+						}
+					]
 				})]
 			},
 			{
@@ -1984,6 +2872,7 @@ const surfaceCommands = [
 				subcommands: [defineOperation({
 					name: "create",
 					summary: "Unscrap asset",
+					example: "hardfin asset unscrap create ast_4f9xk2mq7plr8stz",
 					method: "POST",
 					path: "/asset/{assetKey}/unscrap",
 					pathParameters: [{
@@ -1992,7 +2881,7 @@ const surfaceCommands = [
 						required: true
 					}],
 					queryFlags: [],
-					takesBody: false
+					bodyFlags: []
 				})]
 			},
 			{
@@ -2004,6 +2893,7 @@ const surfaceCommands = [
 				subcommands: [defineOperation({
 					name: "list",
 					summary: "Get asset URL links",
+					example: "hardfin asset url-link list ast_4f9xk2mq7plr8stz",
 					method: "GET",
 					path: "/asset/{assetKey}/url-link",
 					pathParameters: [{
@@ -2012,10 +2902,11 @@ const surfaceCommands = [
 						required: true
 					}],
 					queryFlags: [],
-					takesBody: false
+					bodyFlags: []
 				}), defineOperation({
 					name: "create",
 					summary: "Create asset URL link",
+					example: "hardfin asset url-link create ast_4f9xk2mq7plr8stz --url <value>",
 					method: "POST",
 					path: "/asset/{assetKey}/url-link",
 					pathParameters: [{
@@ -2024,7 +2915,20 @@ const surfaceCommands = [
 						required: true
 					}],
 					queryFlags: [],
-					takesBody: true
+					bodyFlags: [{
+						name: "name",
+						jsonPath: ["name"],
+						description: "The link's display name, or null to show the address instead",
+						valueName: "value",
+						schema: z.string()
+					}, {
+						name: "url",
+						jsonPath: ["url"],
+						description: "The address the link points to",
+						valueName: "value",
+						required: true,
+						schema: z.string()
+					}]
 				})]
 			},
 			{
@@ -2036,6 +2940,7 @@ const surfaceCommands = [
 				subcommands: [defineOperation({
 					name: "create",
 					summary: "Create asset useful life revision",
+					example: "hardfin asset useful-life-revision create ast_4f9xk2mq7plr8stz --effective-date <value> --reason <value> --useful-life-months <number>",
 					method: "POST",
 					path: "/asset/{assetKey}/useful-life-revision",
 					pathParameters: [{
@@ -2044,7 +2949,47 @@ const surfaceCommands = [
 						required: true
 					}],
 					queryFlags: [],
-					takesBody: true
+					bodyFlags: [
+						{
+							name: "effective-date",
+							jsonPath: ["effectiveDate"],
+							description: "The day the revised useful life takes effect, which cannot be in the future",
+							valueName: "value",
+							required: true,
+							schema: z.string()
+						},
+						{
+							name: "notes",
+							jsonPath: ["notes"],
+							description: "Free-form detail about the revision, which a reason of OTHER requires",
+							valueName: "value",
+							schema: z.string()
+						},
+						{
+							name: "reason",
+							jsonPath: ["reason"],
+							description: "Why the useful life was revised",
+							valueName: "value",
+							required: true,
+							schema: z.enum([
+								"CHANGE_IN_USE",
+								"DAMAGE",
+								"OBSOLESCENCE",
+								"OTHER",
+								"REASSESSMENT",
+								"REFURBISHMENT",
+								"REGULATORY"
+							])
+						},
+						{
+							name: "useful-life-months",
+							jsonPath: ["usefulLifeMonths"],
+							description: "The asset's revised useful life in months",
+							valueName: "number",
+							required: true,
+							schema: z.coerce.number()
+						}
+					]
 				})]
 			}
 		]
@@ -2059,6 +3004,7 @@ const surfaceCommands = [
 			defineOperation({
 				name: "list",
 				summary: "Get customers",
+				example: "hardfin customer list --limit 10",
 				method: "GET",
 				path: "/customer",
 				pathParameters: [],
@@ -2130,33 +3076,106 @@ const surfaceCommands = [
 						schema: z.string()
 					}
 				],
-				takesBody: false
+				bodyFlags: []
 			}),
 			defineOperation({
 				name: "create",
 				summary: "Create customer",
+				example: "hardfin customer create --name <value>",
 				method: "POST",
 				path: "/customer",
 				pathParameters: [],
 				queryFlags: [],
-				takesBody: true
-			}),
-			defineOperation({
-				name: "get",
-				summary: "Get customer",
-				method: "GET",
-				path: "/customer/{customerKey}",
-				pathParameters: [{
-					name: "customerKey",
-					description: "The customer's key",
-					required: true
-				}],
-				queryFlags: [],
-				takesBody: false
-			}),
+				bodyFlags: [
+					{
+						name: "billing-address",
+						jsonPath: ["billingAddress"],
+						description: "The address invoices are sent to",
+						valueName: "value",
+						schema: z.string()
+					},
+					{
+						name: "billing-contact-email",
+						jsonPath: ["billingContact", "email"],
+						description: "The billing contact's email address",
+						valueName: "value",
+						schema: z.string()
+					},
+					{
+						name: "billing-contact-name",
+						jsonPath: ["billingContact", "name"],
+						description: "The billing contact's name",
+						valueName: "value",
+						schema: z.string()
+					},
+					{
+						name: "billing-contact-phone",
+						jsonPath: ["billingContact", "phone"],
+						description: "The billing contact's phone number",
+						valueName: "value",
+						schema: z.string()
+					},
+					{
+						name: "comment",
+						jsonPath: ["comment"],
+						description: "A free-form note about the customer",
+						valueName: "value",
+						schema: z.string()
+					},
+					{
+						name: "domain",
+						jsonPath: ["domain"],
+						description: "The customer's web domain, used to look up its logo",
+						valueName: "value",
+						schema: z.string()
+					},
+					{
+						name: "external-id",
+						jsonPath: ["externalId"],
+						description: "The customer's identifier in another system",
+						valueName: "value",
+						schema: z.string()
+					},
+					{
+						name: "is-customer",
+						jsonPath: ["isCustomer"],
+						description: "Whether the company is a customer",
+						schema: z.boolean()
+					},
+					{
+						name: "is-supplier",
+						jsonPath: ["isSupplier"],
+						description: "Whether the company is a supplier",
+						schema: z.boolean()
+					},
+					{
+						name: "name",
+						jsonPath: ["name"],
+						description: "The customer's display name",
+						valueName: "value",
+						required: true,
+						schema: z.string()
+					}
+				]
+			}),
+			defineOperation({
+				name: "get",
+				summary: "Get customer",
+				example: "hardfin customer get cust_V1StGXR8Z5jdHi6B",
+				method: "GET",
+				path: "/customer/{customerKey}",
+				pathParameters: [{
+					name: "customerKey",
+					description: "The customer's key",
+					required: true
+				}],
+				queryFlags: [],
+				bodyFlags: []
+			}),
 			defineOperation({
 				name: "update",
 				summary: "Patch customer",
+				example: "hardfin customer update cust_V1StGXR8Z5jdHi6B",
 				method: "PATCH",
 				path: "/customer/{customerKey}",
 				pathParameters: [{
@@ -2165,7 +3184,82 @@ const surfaceCommands = [
 					required: true
 				}],
 				queryFlags: [],
-				takesBody: true
+				bodyFlags: [
+					{
+						name: "billing-address",
+						jsonPath: ["billingAddress"],
+						description: "The address invoices are sent to",
+						valueName: "value",
+						schema: z.string()
+					},
+					{
+						name: "billing-contact-email",
+						jsonPath: ["billingContact", "email"],
+						description: "The billing contact's email address",
+						valueName: "value",
+						schema: z.string()
+					},
+					{
+						name: "billing-contact-name",
+						jsonPath: ["billingContact", "name"],
+						description: "The billing contact's name",
+						valueName: "value",
+						schema: z.string()
+					},
+					{
+						name: "billing-contact-phone",
+						jsonPath: ["billingContact", "phone"],
+						description: "The billing contact's phone number",
+						valueName: "value",
+						schema: z.string()
+					},
+					{
+						name: "comment",
+						jsonPath: ["comment"],
+						description: "A free-form note about the customer",
+						valueName: "value",
+						schema: z.string()
+					},
+					{
+						name: "domain",
+						jsonPath: ["domain"],
+						description: "The customer's web domain, used to look up its logo",
+						valueName: "value",
+						schema: z.string()
+					},
+					{
+						name: "external-id",
+						jsonPath: ["externalId"],
+						description: "The customer's identifier in another system",
+						valueName: "value",
+						schema: z.string()
+					},
+					{
+						name: "is-archived",
+						jsonPath: ["isArchived"],
+						description: "Whether the customer is archived",
+						schema: z.boolean()
+					},
+					{
+						name: "is-customer",
+						jsonPath: ["isCustomer"],
+						description: "Whether the company is a customer",
+						schema: z.boolean()
+					},
+					{
+						name: "is-supplier",
+						jsonPath: ["isSupplier"],
+						description: "Whether the company is a supplier",
+						schema: z.boolean()
+					},
+					{
+						name: "name",
+						jsonPath: ["name"],
+						description: "The customer's display name",
+						valueName: "value",
+						schema: z.string()
+					}
+				]
 			})
 		]
 	},
@@ -2178,14 +3272,44 @@ const surfaceCommands = [
 		subcommands: [defineOperation({
 			name: "create",
 			summary: "Upload file",
+			example: "hardfin file create --file-type <value> --for-entity <value> --file photo.jpg",
 			method: "POST",
 			path: "/file",
 			pathParameters: [],
 			queryFlags: [],
-			takesBody: true
+			bodyFlags: [],
+			upload: {
+				filePart: "data",
+				fields: [
+					{
+						name: "file-type",
+						jsonPath: ["fileType"],
+						description: "The kind of file uploaded, which is ASSET_FILE, the only kind the API uploads",
+						valueName: "value",
+						required: true,
+						schema: z.string()
+					},
+					{
+						name: "for-entity",
+						jsonPath: ["forEntity"],
+						description: "The ID of the asset the file is attached to",
+						valueName: "value",
+						required: true,
+						schema: z.string()
+					},
+					{
+						name: "is-public",
+						jsonPath: ["isPublic"],
+						description: "Whether any organization's API key may download the file, which is false unless sent as true",
+						valueName: "value",
+						schema: z.string()
+					}
+				]
+			}
 		}), defineOperation({
 			name: "get",
 			summary: "Get file",
+			example: "hardfin file get file_7hq2mx9pkr4stz8w",
 			method: "GET",
 			path: "/file/{fileKey}",
 			pathParameters: [{
@@ -2199,7 +3323,7 @@ const surfaceCommands = [
 				description: "True when the file downloads as an attachment rather than opening inline",
 				schema: z.boolean()
 			}],
-			takesBody: false
+			bodyFlags: []
 		})]
 	},
 	{
@@ -2212,6 +3336,7 @@ const surfaceCommands = [
 			defineOperation({
 				name: "list",
 				summary: "Get items",
+				example: "hardfin item list --limit 10",
 				method: "GET",
 				path: "/item",
 				pathParameters: [],
@@ -2286,20 +3411,129 @@ const surfaceCommands = [
 						schema: z.string()
 					}
 				],
-				takesBody: false
+				bodyFlags: []
 			}),
 			defineOperation({
 				name: "create",
 				summary: "Create item",
+				example: "hardfin item create --name <value> --sku <value> --type <value>",
 				method: "POST",
 				path: "/item",
 				pathParameters: [],
 				queryFlags: [],
-				takesBody: true
+				bodyFlags: [
+					{
+						name: "accepts-bulk-serials",
+						jsonPath: ["acceptsBulkSerials"],
+						description: "Whether a BULK item records serial numbers on its units, which SERVICE and DEVICE items ignore",
+						schema: z.boolean()
+					},
+					{
+						name: "description",
+						jsonPath: ["description"],
+						description: "A free-form description of the item",
+						valueName: "value",
+						schema: z.string()
+					},
+					{
+						name: "name",
+						jsonPath: ["name"],
+						description: "The item's display name",
+						valueName: "value",
+						required: true,
+						schema: z.string()
+					},
+					{
+						name: "sku",
+						jsonPath: ["sku"],
+						description: "The item's stock keeping unit, unique within your organization",
+						valueName: "value",
+						required: true,
+						schema: z.string()
+					},
+					{
+						name: "type",
+						jsonPath: ["type"],
+						description: "SERVICE for a non-physical item, DEVICE for a physical item tracked by serial number, or BULK for a part tracked by quantity",
+						valueName: "value",
+						required: true,
+						schema: z.enum([
+							"BULK",
+							"DEVICE",
+							"SERVICE"
+						])
+					},
+					{
+						name: "unit-of-measure",
+						jsonPath: ["unitOfMeasure"],
+						description: "The unit a BULK item's quantities are counted in, which SERVICE and DEVICE items ignore",
+						valueName: "value",
+						schema: z.enum([
+							"BG",
+							"BO",
+							"BX",
+							"C62",
+							"CMK",
+							"CMT",
+							"CR",
+							"CS",
+							"CT",
+							"DMQ",
+							"DR",
+							"DZN",
+							"EA",
+							"EN",
+							"FOT",
+							"FTK",
+							"FTQ",
+							"GLL",
+							"GRM",
+							"GRO",
+							"H87",
+							"INH",
+							"INK",
+							"INQ",
+							"KG",
+							"KGM",
+							"KMT",
+							"KT",
+							"LBR",
+							"LO",
+							"LTR",
+							"MGM",
+							"MLT",
+							"MMK",
+							"MMT",
+							"MTK",
+							"MTQ",
+							"MTR",
+							"ONZ",
+							"OZA",
+							"PK",
+							"PR",
+							"PTI",
+							"PX",
+							"QTI",
+							"RL",
+							"RO",
+							"SET",
+							"SMI",
+							"ST",
+							"STN",
+							"SV",
+							"TNE",
+							"TU",
+							"YDK",
+							"YDQ",
+							"YRD"
+						])
+					}
+				]
 			}),
 			defineOperation({
 				name: "get",
 				summary: "Get item",
+				example: "hardfin item get item_7Hq2Lm9XcR4tWz8K",
 				method: "GET",
 				path: "/item/{itemKey}",
 				pathParameters: [{
@@ -2308,11 +3542,12 @@ const surfaceCommands = [
 					required: true
 				}],
 				queryFlags: [],
-				takesBody: false
+				bodyFlags: []
 			}),
 			defineOperation({
 				name: "update",
 				summary: "Update item",
+				example: "hardfin item update item_7Hq2Lm9XcR4tWz8K",
 				method: "PATCH",
 				path: "/item/{itemKey}",
 				pathParameters: [{
@@ -2321,7 +3556,65 @@ const surfaceCommands = [
 					required: true
 				}],
 				queryFlags: [],
-				takesBody: true
+				bodyFlags: [
+					{
+						name: "accepts-bulk-serials",
+						jsonPath: ["acceptsBulkSerials"],
+						description: "Whether a BULK item records serial numbers on its units, read only beside type",
+						schema: z.boolean()
+					},
+					{
+						name: "description",
+						jsonPath: ["description"],
+						description: "The item's new description, or null to clear it",
+						valueName: "value",
+						schema: z.string()
+					},
+					{
+						name: "field",
+						jsonPath: ["fields"],
+						description: "New positions for a DEVICE item's fields",
+						valueName: "fieldId=,order=",
+						repeatable: true,
+						element: [
+							"fieldId",
+							"order",
+							"section"
+						],
+						schema: z.array(z.string())
+					},
+					{
+						name: "is-archived",
+						jsonPath: ["isArchived"],
+						description: "Whether the item is archived, which cannot be null",
+						schema: z.boolean()
+					},
+					{
+						name: "name",
+						jsonPath: ["name"],
+						description: "The item's new display name, which cannot be empty",
+						valueName: "value",
+						schema: z.string()
+					},
+					{
+						name: "sku",
+						jsonPath: ["sku"],
+						description: "The item's new stock keeping unit, which cannot be empty and must be unique within your organization",
+						valueName: "value",
+						schema: z.string()
+					},
+					{
+						name: "type",
+						jsonPath: ["type"],
+						description: "The type to convert the item to, when the item's assets and inventory history allow the conversion",
+						valueName: "value",
+						schema: z.enum([
+							"BULK",
+							"DEVICE",
+							"SERVICE"
+						])
+					}
+				]
 			}),
 			{
 				name: "accounting",
@@ -2332,6 +3625,7 @@ const surfaceCommands = [
 				subcommands: [defineOperation({
 					name: "update",
 					summary: "Update item accounting",
+					example: "hardfin item accounting update item_7Hq2Lm9XcR4tWz8K",
 					method: "PATCH",
 					path: "/item/{itemKey}/accounting",
 					pathParameters: [{
@@ -2340,7 +3634,104 @@ const surfaceCommands = [
 						required: true
 					}],
 					queryFlags: [],
-					takesBody: true
+					bodyFlags: [
+						{
+							name: "allocated-indirect",
+							jsonPath: ["allocatedIndirect"],
+							description: "One unit's share of overhead, a cost component",
+							valueName: "value",
+							schema: z.string()
+						},
+						{
+							name: "bill-of-materials",
+							jsonPath: ["billOfMaterials"],
+							description: "The parts cost of one unit, a cost component",
+							valueName: "value",
+							schema: z.string()
+						},
+						{
+							name: "depreciation-model",
+							jsonPath: ["depreciationModel"],
+							description: "The method one unit is depreciated by, or null to clear it",
+							valueName: "value",
+							schema: z.enum([
+								"DOUBLE_DECLINING",
+								"STRAIGHT_LINE",
+								"SUM_YEAR",
+								"UNIT_OF_PRODUCTION"
+							])
+						},
+						{
+							name: "direct-labor",
+							jsonPath: ["directLabor"],
+							description: "The labor cost to build one unit, a cost component",
+							valueName: "value",
+							schema: z.string()
+						},
+						{
+							name: "freight-inbound",
+							jsonPath: ["freightInbound"],
+							description: "The shipping cost to receive one unit, a cost component",
+							valueName: "value",
+							schema: z.string()
+						},
+						{
+							name: "freight-outbound",
+							jsonPath: ["freightOutbound"],
+							description: "The shipping cost to deploy one unit, a deployment cost component",
+							valueName: "value",
+							schema: z.string()
+						},
+						{
+							name: "installation",
+							jsonPath: ["installation"],
+							description: "The cost to install one unit, a deployment cost component",
+							valueName: "value",
+							schema: z.string()
+						},
+						{
+							name: "interest",
+							jsonPath: ["interest"],
+							description: "The financing cost of one unit, a cost component",
+							valueName: "value",
+							schema: z.string()
+						},
+						{
+							name: "salvage-value",
+							jsonPath: ["salvageValue"],
+							description: "The value one unit keeps at the end of its useful life, or null to clear it",
+							valueName: "value",
+							schema: z.string()
+						},
+						{
+							name: "simple-cost-basis",
+							jsonPath: ["simpleCostBasis"],
+							description: "A single cost for one unit, which cannot be sent together with the cost components",
+							valueName: "value",
+							schema: z.string()
+						},
+						{
+							name: "tariffs",
+							jsonPath: ["tariffs"],
+							description: "The import duty paid on one unit, a cost component",
+							valueName: "value",
+							schema: z.string()
+						},
+						{
+							name: "tax",
+							jsonPath: ["tax"],
+							description: "The tax paid on one unit, a cost component",
+							valueName: "value",
+							schema: z.string()
+						},
+						{
+							name: "useful-life",
+							jsonPath: ["usefulLife"],
+							description: "The number of months one unit is depreciated over, or null to clear it",
+							valueName: "number",
+							schema: z.coerce.number()
+						}
+					]
 				})]
 			},
 			{
@@ -2353,6 +3744,7 @@ const surfaceCommands = [
 					defineOperation({
 						name: "create",
 						summary: "Create item field",
+						example: "hardfin item field create item_7Hq2Lm9XcR4tWz8K --field-type <value> --label <value> --order <number>",
 						method: "POST",
 						path: "/item/{itemKey}/field",
 						pathParameters: [{
@@ -2361,11 +3753,54 @@ const surfaceCommands = [
 							required: true
 						}],
 						queryFlags: [],
-						takesBody: true
+						bodyFlags: [
+							{
+								name: "field-type",
+								jsonPath: ["fieldType"],
+								description: "The kind of value the field holds",
+								valueName: "value",
+								required: true,
+								schema: z.enum([
+									"BOOLEAN",
+									"DATE",
+									"DATE_TIME",
+									"INTEGER",
+									"MULTILINE_TEXT",
+									"NUMBER",
+									"TEXT",
+									"TIME"
+								])
+							},
+							{
+								name: "label",
+								jsonPath: ["label"],
+								description: "The field's display name",
+								valueName: "value",
+								required: true,
+								schema: z.string()
+							},
+							{
+								name: "order",
+								jsonPath: ["order"],
+								description: "The field's position within its section, starting at 0",
+								valueName: "number",
+								required: true,
+								schema: z.coerce.number()
+							},
+							{
+								name: "section",
+								jsonPath: ["section"],
+								description: "The group the field is shown in, starting at 0",
+								valueName: "number",
+								required: true,
+								schema: z.coerce.number()
+							}
+						]
 					}),
 					defineOperation({
 						name: "update",
 						summary: "Update item field",
+						example: "hardfin item field update item_7Hq2Lm9XcR4tWz8K pfield_2wn8kq4lxp7rtz3m",
 						method: "PATCH",
 						path: "/item/{itemKey}/field/{fieldKey}",
 						pathParameters: [{
@@ -2378,11 +3813,18 @@ const surfaceCommands = [
 							required: true
 						}],
 						queryFlags: [],
-						takesBody: true
+						bodyFlags: [{
+							name: "label",
+							jsonPath: ["label"],
+							description: "The field's new display name, which cannot be empty",
+							valueName: "value",
+							schema: z.string()
+						}]
 					}),
 					defineOperation({
 						name: "delete",
 						summary: "Delete item field",
+						example: "hardfin item field delete item_7Hq2Lm9XcR4tWz8K pfield_2wn8kq4lxp7rtz3m",
 						method: "DELETE",
 						path: "/item/{itemKey}/field/{fieldKey}",
 						pathParameters: [{
@@ -2395,7 +3837,7 @@ const surfaceCommands = [
 							required: true
 						}],
 						queryFlags: [],
-						takesBody: false
+						bodyFlags: []
 					})
 				]
 			}
@@ -2411,6 +3853,7 @@ const surfaceCommands = [
 			defineOperation({
 				name: "list",
 				summary: "Get location listing",
+				example: "hardfin location list --limit 10",
 				method: "GET",
 				path: "/location",
 				pathParameters: [],
@@ -2499,20 +3942,136 @@ const surfaceCommands = [
 						schema: z.array(z.string())
 					}
 				],
-				takesBody: false
+				bodyFlags: []
 			}),
 			defineOperation({
 				name: "create",
 				summary: "Create location",
+				example: "hardfin location create",
 				method: "POST",
 				path: "/location",
 				pathParameters: [],
 				queryFlags: [],
-				takesBody: true
+				bodyFlags: [
+					{
+						name: "address-line1",
+						jsonPath: ["address", "addressLine1"],
+						description: "The first line of the street address",
+						valueName: "value",
+						schema: z.string()
+					},
+					{
+						name: "address-line2",
+						jsonPath: ["address", "addressLine2"],
+						description: "The second line of the street address, such as a suite",
+						valueName: "value",
+						schema: z.string()
+					},
+					{
+						name: "address-city",
+						jsonPath: ["address", "city"],
+						description: "The city",
+						valueName: "value",
+						schema: z.string()
+					},
+					{
+						name: "address-country",
+						jsonPath: ["address", "country"],
+						description: "The country",
+						valueName: "value",
+						schema: z.string()
+					},
+					{
+						name: "address-formatted-address",
+						jsonPath: ["address", "formattedAddress"],
+						description: "The whole address on one line",
+						valueName: "value",
+						schema: z.string()
+					},
+					{
+						name: "address-postal-code",
+						jsonPath: ["address", "postalCode"],
+						description: "The postal or ZIP code",
+						valueName: "value",
+						schema: z.string()
+					},
+					{
+						name: "address-state",
+						jsonPath: ["address", "state"],
+						description: "The state or region",
+						valueName: "value",
+						schema: z.string()
+					},
+					{
+						name: "consignee",
+						jsonPath: ["consignee"],
+						description: "The ID of the customer a zone is designated for, such as for reservations, provisioning or a 3PL",
+						valueName: "value",
+						schema: z.string()
+					},
+					{
+						name: "customer-id",
+						jsonPath: ["customerId"],
+						description: "The ID of the customer to assign a site to, or null for your organization's own site",
+						valueName: "value",
+						schema: z.string()
+					},
+					{
+						name: "description",
+						jsonPath: ["description"],
+						description: "A free-form description of a zone",
+						valueName: "value",
+						schema: z.string()
+					},
+					{
+						name: "is-inventory",
+						jsonPath: ["isInventory"],
+						description: "Whether assets at the location count as inventory for reporting",
+						schema: z.boolean()
+					},
+					{
+						name: "is-inventory-override",
+						jsonPath: ["isInventoryOverride"],
+						description: "Whether a zone sets its own isInventory rather than inheriting its parent site's, which a site refuses",
+						schema: z.boolean()
+					},
+					{
+						name: "is-transient",
+						jsonPath: ["isTransient"],
+						description: "Whether assets make only occasional or temporary stops at the location, which hides it from location lists by default",
+						schema: z.boolean()
+					},
+					{
+						name: "name",
+						jsonPath: ["name"],
+						description: "The location's display name",
+						valueName: "value",
+						schema: z.string()
+					},
+					{
+						name: "parent-location-id",
+						jsonPath: ["parentLocationId"],
+						description: "The ID of the site a zone belongs to, required for a zone and refused for a site",
+						valueName: "value",
+						schema: z.string()
+					},
+					{
+						name: "type",
+						jsonPath: ["type"],
+						description: "SITE for a site, or ZONE for a zone within a site",
+						valueName: "value",
+						schema: z.enum([
+							"SITE",
+							"UNKNOWN",
+							"ZONE"
+						])
+					}
+				]
 			}),
 			defineOperation({
 				name: "get",
 				summary: "Get location",
+				example: "hardfin location get loc_4f9Xk2mQ7pLr8sTz",
 				method: "GET",
 				path: "/location/{locationKey}",
 				pathParameters: [{
@@ -2521,11 +4080,12 @@ const surfaceCommands = [
 					required: true
 				}],
 				queryFlags: [],
-				takesBody: false
+				bodyFlags: []
 			}),
 			defineOperation({
 				name: "update",
 				summary: "Patch location",
+				example: "hardfin location update loc_4f9Xk2mQ7pLr8sTz",
 				method: "PATCH",
 				path: "/location/{locationKey}",
 				pathParameters: [{
@@ -2534,7 +4094,120 @@ const surfaceCommands = [
 					required: true
 				}],
 				queryFlags: [],
-				takesBody: true
+				bodyFlags: [
+					{
+						name: "address-line1",
+						jsonPath: ["address", "addressLine1"],
+						description: "The first line of the street address",
+						valueName: "value",
+						schema: z.string()
+					},
+					{
+						name: "address-line2",
+						jsonPath: ["address", "addressLine2"],
+						description: "The second line of the street address, such as a suite",
+						valueName: "value",
+						schema: z.string()
+					},
+					{
+						name: "address-city",
+						jsonPath: ["address", "city"],
+						description: "The city",
+						valueName: "value",
+						schema: z.string()
+					},
+					{
+						name: "address-country",
+						jsonPath: ["address", "country"],
+						description: "The country",
+						valueName: "value",
+						schema: z.string()
+					},
+					{
+						name: "address-formatted-address",
+						jsonPath: ["address", "formattedAddress"],
+						description: "The whole address on one line",
+						valueName: "value",
+						schema: z.string()
+					},
+					{
+						name: "address-postal-code",
+						jsonPath: ["address", "postalCode"],
+						description: "The postal or ZIP code",
+						valueName: "value",
+						schema: z.string()
+					},
+					{
+						name: "address-state",
+						jsonPath: ["address", "state"],
+						description: "The state or region",
+						valueName: "value",
+						schema: z.string()
+					},
+					{
+						name: "consignee",
+						jsonPath: ["consignee"],
+						description: "The ID of the customer a zone is designated for, such as for reservations, provisioning or a 3PL",
+						valueName: "value",
+						schema: z.string()
+					},
+					{
+						name: "customer-id",
+						jsonPath: ["customerId"],
+						description: "The ID of the customer to assign a site to, or null for your organization's own site",
+						valueName: "value",
+						schema: z.string()
+					},
+					{
+						name: "description",
+						jsonPath: ["description"],
+						description: "A free-form description of a zone",
+						valueName: "value",
+						schema: z.string()
+					},
+					{
+						name: "is-archived",
+						jsonPath: ["isArchived"],
+						description: "Whether the location is archived, and archiving a site archives its zones",
+						schema: z.boolean()
+					},
+					{
+						name: "is-inventory",
+						jsonPath: ["isInventory"],
+						description: "Whether assets at the location count as inventory for reporting",
+						schema: z.boolean()
+					},
+					{
+						name: "is-inventory-override",
+						jsonPath: ["isInventoryOverride"],
+						description: "Whether a zone sets its own isInventory rather than inheriting its parent site's, which a site refuses",
+						schema: z.boolean()
+					},
+					{
+						name: "is-transient",
+						jsonPath: ["isTransient"],
+						description: "Whether assets make only occasional or temporary stops at the location, which hides it from location lists by default",
+						schema: z.boolean()
+					},
+					{
+						name: "name",
+						jsonPath: ["name"],
+						description: "The location's display name",
+						valueName: "value",
+						schema: z.string()
+					},
+					{
+						name: "type",
+						jsonPath: ["type"],
+						description: "SITE for a site, or ZONE for a zone within a site",
+						valueName: "value",
+						schema: z.enum([
+							"SITE",
+							"UNKNOWN",
+							"ZONE"
+						])
+					}
+				]
 			}),
 			{
 				name: "zones",
@@ -2545,6 +4218,7 @@ const surfaceCommands = [
 				subcommands: [defineOperation({
 					name: "list",
 					summary: "Get zones",
+					example: "hardfin location zones list loc_4f9Xk2mQ7pLr8sTz",
 					method: "GET",
 					path: "/location/{locationKey}/zones",
 					pathParameters: [{
@@ -2563,7 +4237,7 @@ const surfaceCommands = [
 							"true"
 						])
 					}],
-					takesBody: false
+					bodyFlags: []
 				})]
 			}
 		]
@@ -2578,6 +4252,7 @@ const surfaceCommands = [
 			defineOperation({
 				name: "get",
 				summary: "Get URL link by key",
+				example: "hardfin url-link get link_7hq2mx9pcr4stz8w",
 				method: "GET",
 				path: "/url-link/{linkKey}",
 				pathParameters: [{
@@ -2586,11 +4261,12 @@ const surfaceCommands = [
 					required: true
 				}],
 				queryFlags: [],
-				takesBody: false
+				bodyFlags: []
 			}),
 			defineOperation({
 				name: "update",
 				summary: "Update URL link",
+				example: "hardfin url-link update link_7hq2mx9pcr4stz8w",
 				method: "PATCH",
 				path: "/url-link/{linkKey}",
 				pathParameters: [{
@@ -2599,11 +4275,24 @@ const surfaceCommands = [
 					required: true
 				}],
 				queryFlags: [],
-				takesBody: true
+				bodyFlags: [{
+					name: "name",
+					jsonPath: ["name"],
+					description: "The link's display name, or null to show the address instead",
+					valueName: "value",
+					schema: z.string()
+				}, {
+					name: "url",
+					jsonPath: ["url"],
+					description: "The address the link points to, which cannot be empty or null",
+					valueName: "value",
+					schema: z.string()
+				}]
 			}),
 			defineOperation({
 				name: "delete",
 				summary: "Delete URL link",
+				example: "hardfin url-link delete link_7hq2mx9pcr4stz8w",
 				method: "DELETE",
 				path: "/url-link/{linkKey}",
 				pathParameters: [{
@@ -2612,7 +4301,7 @@ const surfaceCommands = [
 					required: true
 				}],
 				queryFlags: [],
-				takesBody: false
+				bodyFlags: []
 			})
 		]
 	}
@@ -2898,7 +4587,10 @@ const commands = [
 	...surfaceCommands,
 	apiCommand,
 	configCommand,
-	agentGuideCommand
+	agentGuideCommand,
+	completionCommand,
+	mcpCommand,
+	completeCommand
 ];
 //#endregion
 //#region src/command/validate.ts
@@ -2914,7 +4606,7 @@ function toRejectedFlag(command, flags) {
 //#region src/cli.ts
 const program = new Command();
 program.name("hardfin").description("Call the Hardfin API from a terminal or an agent").version(version$1, "-v, --version").option("--api-url <url>", "The API to call, whose host also holds the authorization server").option("--issuer-url <url>", "The authorization server, when it does not sit at the API's host").showHelpAfterError().enablePositionalOptions();
-for (const command of commands) program.addCommand(toProgram(command));
+for (const command of commands) program.addCommand(toProgram(command), { hidden: command.hidden });
 await program.parseAsync(process.argv);
 /** toProgram wires one registry command into the parser. */
 function toProgram(command) {
@@ -2932,7 +4624,7 @@ function toProgram(command) {
 		program.addOption(option);
 	}
 	for (const example of command.examples) program.addHelpText("after", `\n${example.description}:\n  $ ${example.command}`);
-	for (const subcommand of command.subcommands ?? []) program.addCommand(toProgram(subcommand));
+	for (const subcommand of command.subcommands ?? []) program.addCommand(toProgram(subcommand), { hidden: subcommand.hidden });
 	if (!command.run) return program;
 	program.action(async (...parsed) => {
 		const flags = parsed[parsed.length - 2] ?? {};