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

package/dist/cli.js

@@ -2,8 +2,8 @@
 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 { spawn, spawnSync } from "node:child_process";
 import { createServer } from "node:http";
@@ -198,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) {
@@ -604,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, [{
@@ -761,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",
@@ -1496,10 +1632,10 @@ async function runMcp(input) {
 }
 //#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 = {
@@ -1509,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)
 	};
 }
@@ -1527,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({
@@ -1542,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) {
@@ -1579,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
@@ -1600,6 +1807,7 @@ const surfaceCommands = [
 			defineOperation({
 				name: "list",
 				summary: "Get asset listing",
+				example: "hardfin asset list --limit 10",
 				method: "GET",
 				path: "/asset",
 				pathParameters: [],
@@ -1783,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",
@@ -1809,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",
@@ -1824,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: [{
@@ -1843,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: [{
@@ -1856,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",
@@ -1867,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: [{
@@ -1875,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",
@@ -1885,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: [{
@@ -1893,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()
+						}]
 					})]
 				}]
 			},
@@ -1906,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: [{
@@ -1914,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"
+							])
+						}
+					]
 				})]
 			},
 			{
@@ -1926,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: [{
@@ -1934,7 +2549,7 @@ const surfaceCommands = [
 						required: true
 					}],
 					queryFlags: [],
-					takesBody: false
+					bodyFlags: []
 				})]
 			},
 			{
@@ -1946,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: [{
@@ -1966,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: [{
@@ -1982,7 +2599,7 @@ const surfaceCommands = [
 						required: true
 					}],
 					queryFlags: [],
-					takesBody: false
+					bodyFlags: []
 				})]
 			},
 			{
@@ -1994,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: [{
@@ -2002,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: [{
@@ -2018,7 +2637,7 @@ const surfaceCommands = [
 						required: true
 					}],
 					queryFlags: [],
-					takesBody: false
+					bodyFlags: []
 				})]
 			},
 			{
@@ -2030,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: [{
@@ -2038,7 +2658,7 @@ const surfaceCommands = [
 						required: true
 					}],
 					queryFlags: [],
-					takesBody: false
+					bodyFlags: []
 				})]
 			},
 			{
@@ -2051,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: [{
@@ -2059,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: [{
@@ -2072,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: [{
@@ -2085,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: [{
@@ -2102,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: [{
@@ -2119,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: [{
@@ -2136,7 +2815,7 @@ const surfaceCommands = [
 							required: true
 						}],
 						queryFlags: [],
-						takesBody: false
+						bodyFlags: []
 					})
 				]
 			},
@@ -2149,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: [{
@@ -2157,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()
+						}
+					]
 				})]
 			},
 			{
@@ -2169,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: [{
@@ -2177,7 +2881,7 @@ const surfaceCommands = [
 						required: true
 					}],
 					queryFlags: [],
-					takesBody: false
+					bodyFlags: []
 				})]
 			},
 			{
@@ -2189,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: [{
@@ -2197,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: [{
@@ -2209,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()
+					}]
 				})]
 			},
 			{
@@ -2221,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: [{
@@ -2229,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()
+						}
+					]
 				})]
 			}
 		]
@@ -2244,6 +3004,7 @@ const surfaceCommands = [
 			defineOperation({
 				name: "list",
 				summary: "Get customers",
+				example: "hardfin customer list --limit 10",
 				method: "GET",
 				path: "/customer",
 				pathParameters: [],
@@ -2315,20 +3076,92 @@ 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
+				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: [{
@@ -2337,11 +3170,12 @@ const surfaceCommands = [
 					required: true
 				}],
 				queryFlags: [],
-				takesBody: false
+				bodyFlags: []
 			}),
 			defineOperation({
 				name: "update",
 				summary: "Patch customer",
+				example: "hardfin customer update cust_V1StGXR8Z5jdHi6B",
 				method: "PATCH",
 				path: "/customer/{customerKey}",
 				pathParameters: [{
@@ -2350,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()
+					}
+				]
 			})
 		]
 	},
@@ -2363,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: [{
@@ -2384,7 +3323,7 @@ const surfaceCommands = [
 				description: "True when the file downloads as an attachment rather than opening inline",
 				schema: z.boolean()
 			}],
-			takesBody: false
+			bodyFlags: []
 		})]
 	},
 	{
@@ -2397,6 +3336,7 @@ const surfaceCommands = [
 			defineOperation({
 				name: "list",
 				summary: "Get items",
+				example: "hardfin item list --limit 10",
 				method: "GET",
 				path: "/item",
 				pathParameters: [],
@@ -2471,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: [{
@@ -2493,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: [{
@@ -2506,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",
@@ -2517,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: [{
@@ -2525,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()
+						}
+					]
 				})]
 			},
 			{
@@ -2538,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: [{
@@ -2546,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: [{
@@ -2563,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: [{
@@ -2580,7 +3837,7 @@ const surfaceCommands = [
 							required: true
 						}],
 						queryFlags: [],
-						takesBody: false
+						bodyFlags: []
 					})
 				]
 			}
@@ -2596,6 +3853,7 @@ const surfaceCommands = [
 			defineOperation({
 				name: "list",
 				summary: "Get location listing",
+				example: "hardfin location list --limit 10",
 				method: "GET",
 				path: "/location",
 				pathParameters: [],
@@ -2684,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: [{
@@ -2706,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: [{
@@ -2719,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",
@@ -2730,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: [{
@@ -2748,7 +4237,7 @@ const surfaceCommands = [
 							"true"
 						])
 					}],
-					takesBody: false
+					bodyFlags: []
 				})]
 			}
 		]
@@ -2763,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: [{
@@ -2771,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: [{
@@ -2784,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: [{
@@ -2797,7 +4301,7 @@ const surfaceCommands = [
 					required: true
 				}],
 				queryFlags: [],
-				takesBody: false
+				bodyFlags: []
 			})
 		]
 	}
@@ -3084,7 +4588,9 @@ const commands = [
 	apiCommand,
 	configCommand,
 	agentGuideCommand,
-	mcpCommand
+	completionCommand,
+	mcpCommand,
+	completeCommand
 ];
 //#endregion
 //#region src/command/validate.ts
@@ -3100,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) {
@@ -3118,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] ?? {};