@hardfin/cli 0.0.2-dev.9 → 0.1.0-dev.20

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 { createHash, randomBytes, randomUUID } from "node:crypto";
 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 = {
@@ -119,18 +120,28 @@ function toOrigin(apiUrl) {
 }
 //#endregion
 //#region src/output/writer.ts
+/**
+* toText reads a value a caller supplied, which arrives typed as unknown. An object would
+* otherwise reach a request as the text "[object Object]".
+*/
+function toText(value) {
+	if (typeof value === "string") return value;
+	if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") return String(value);
+	if (value === void 0 || value === null) return "";
+	return JSON.stringify(value);
+}
 /** writeData prints a command's result on stdout. */
 function writeData(value) {
 	if (typeof value === "string") {
 		process.stdout.write(value.endsWith("\n") ? value : `${value}\n`);
 		return;
 	}
-	process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+	process.stdout.write(`${JSON.stringify(value ?? null, null, 2)}\n`);
 }
 /** writeFailure prints why a command failed on stderr, as text or as JSON. */
-function writeFailure(message, isJSON, errors, requestId) {
+function writeFailure(message, isJSON, errors, requestId, status) {
 	if (!isJSON) {
-		process.stderr.write(`error: ${message}\n`);
+		process.stderr.write(`error: ${message}${status === void 0 ? "" : ` (HTTP ${status})`}\n`);
 		for (const entry of errors?.slice(1) ?? []) process.stderr.write(`  ${entry.error} (${entry.statusCode})\n`);
 		if (requestId) process.stderr.write(`  request ${requestId}\n`);
 		return;
@@ -140,7 +151,8 @@ function writeFailure(message, isJSON, errors, requestId) {
 			error: message,
 			statusCode: 0
 		}],
-		requestId: requestId ?? null
+		requestId: requestId ?? null,
+		status: status ?? null
 	};
 	process.stderr.write(`${JSON.stringify(payload, null, 2)}\n`);
 }
@@ -197,24 +209,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) {
@@ -237,10 +259,168 @@ function toSummary(command) {
 			valueName: flag.valueName ?? null,
 			repeatable: flag.repeatable ?? false
 		})),
-		examples: command.examples
+		examples: command.examples,
+		subcommands: command.subcommands?.filter((entry) => !entry.hidden).map(toSummary)
 	};
 }
 //#endregion
+//#region src/auth/jwt.ts
+/**
+* toClaims reads an access token's payload for display. Nothing here verifies the
+* signature, because the API is what decides whether a token is good.
+*/
+function toClaims(token) {
+	const payload = token.split(".")[1];
+	if (!payload) return {};
+	try {
+		const decoded = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
+		return {
+			expiresAt: typeof decoded["exp"] === "number" ? decoded["exp"] * 1e3 : void 0,
+			issuedAt: typeof decoded["iat"] === "number" ? decoded["iat"] * 1e3 : void 0,
+			scopes: toScopes(decoded),
+			subject: typeof decoded["sub"] === "string" ? decoded["sub"] : void 0
+		};
+	} catch {
+		return {};
+	}
+}
+/** toScopes reads scp, which is where Hardfin puts an access token's scopes. */
+function toScopes(decoded) {
+	if (Array.isArray(decoded["scp"])) return decoded["scp"].map(String);
+	return typeof decoded["scope"] === "string" ? decoded["scope"].split(" ") : void 0;
+}
+//#endregion
+//#region src/credential/store.ts
+const load = createRequire(import.meta.url);
+/** The service a keyring entry is filed under, alongside the issuer it belongs to. */
+const SERVICE = "hardfin-cli";
+const FILE_MODE = 384;
+const DIRECTORY_MODE$1 = 448;
+/** toCredentialPath names the file the fallback keeps refresh tokens in. */
+function toCredentialPath() {
+	const base = process.env["XDG_STATE_HOME"] ?? join(homedir(), ".local", "state");
+	return join(base, "hardfin", "credentials.json");
+}
+/**
+* keep writes a refresh token for one issuer. Only the refresh token is stored, so a stolen
+* entry is revocable, and access tokens live in the process that fetched them.
+*
+* A rotation keeps the date of the original sign in, because that is what the server's
+* family lifetime runs from. Callers hold the credential lock, which is what makes a write
+* from another process merge rather than disappear.
+*/
+function keep$1(issuer, refreshToken, expiresAt) {
+	const now = (/* @__PURE__ */ new Date()).toISOString();
+	const record = {
+		refreshToken,
+		signedInAt: toCredential(issuer)?.signedInAt ?? now,
+		renewedAt: now,
+		expiresAt: expiresAt === void 0 ? void 0 : new Date(expiresAt).toISOString()
+	};
+	const keyring = toKeyring(issuer);
+	if (keyring) try {
+		keyring.setPassword(JSON.stringify(record));
+		forgetFile(issuer);
+		return "keyring";
+	} catch {}
+	writeFile({
+		...readFile(),
+		[issuer]: record
+	});
+	forgetKeyring(issuer);
+	return "file";
+}
+/**
+* toCredential reads what is held for an issuer, and where it was held. Both backends are
+* read, because a host that lost its keyring for a while wrote to the file instead, and the
+* newer of the two is the one the server has not spent.
+*/
+function toCredential(issuer) {
+	const fromKeyring = toKeyringCredential(issuer);
+	const held = readFile()[issuer];
+	const fromFile = held === void 0 ? void 0 : {
+		...held,
+		backend: "file",
+		path: toCredentialPath()
+	};
+	if (!fromKeyring || !fromFile) return fromKeyring ?? fromFile;
+	return (fromFile.renewedAt ?? "") > (fromKeyring.renewedAt ?? "") ? fromFile : fromKeyring;
+}
+function toKeyringCredential(issuer) {
+	const keyring = toKeyring(issuer);
+	if (!keyring) return;
+	try {
+		const held = keyring.getPassword();
+		return held ? {
+			...toRecord(held),
+			backend: "keyring"
+		} : void 0;
+	} catch {
+		return;
+	}
+}
+/** toRecord reads a stored entry, which older versions wrote as the bare token. */
+function toRecord(held) {
+	if (!held.startsWith("{")) return { refreshToken: held };
+	try {
+		return JSON.parse(held);
+	} catch {
+		return { refreshToken: held };
+	}
+}
+/** forget removes whatever is held for an issuer, in both places. */
+function forget(issuer) {
+	forgetKeyring(issuer);
+	forgetFile(issuer);
+}
+function forgetKeyring(issuer) {
+	const keyring = toKeyring(issuer);
+	if (!keyring) return;
+	try {
+		keyring.deletePassword();
+	} catch {}
+}
+function forgetFile(issuer) {
+	const held = readFile();
+	if (held[issuer] === void 0) return;
+	const remaining = Object.fromEntries(Object.entries(held).filter(([name]) => name !== issuer));
+	if (Object.keys(remaining).length === 0) {
+		rmSync(toCredentialPath(), { force: true });
+		return;
+	}
+	writeFile(remaining);
+}
+/** toKeyring opens the OS keyring, or answers undefined where the platform has none. */
+function toKeyring(issuer) {
+	if (process.env["HARDFIN_CREDENTIAL_STORE"] === "file") return;
+	try {
+		const { Entry } = load("@napi-rs/keyring");
+		return new Entry(SERVICE, issuer);
+	} catch {
+		return;
+	}
+}
+function readFile() {
+	try {
+		const parsed = JSON.parse(readFileSync(toCredentialPath(), "utf8"));
+		if (typeof parsed !== "object" || parsed === null) return {};
+		return Object.fromEntries(Object.entries(parsed).map(([issuer, held]) => [issuer, typeof held === "string" ? { refreshToken: held } : held]));
+	} catch {
+		return {};
+	}
+}
+function writeFile(held) {
+	const path = toCredentialPath();
+	mkdirSync(dirname(path), {
+		recursive: true,
+		mode: DIRECTORY_MODE$1
+	});
+	const pending = `${path}.${process.pid}.tmp`;
+	writeFileSync(pending, `${JSON.stringify(held, null, 2)}\n`, { mode: FILE_MODE });
+	chmodSync(pending, FILE_MODE);
+	renameSync(pending, path);
+}
+//#endregion
 //#region src/auth/metadata.ts
 const METADATA_PATH = "/.well-known/oauth-authorization-server";
 const AuthorizationServerMetadata = z.looseObject({
@@ -260,8 +440,12 @@ var DiscoveryFailure = class extends Error {
 		this.name = "DiscoveryFailure";
 	}
 };
+/** How long a discovery document is reused, which is the hour the server asks for. */
+const CACHE_MS = 36e5;
 /** toMetadata reads what an authorization server says about itself. */
 async function toMetadata(issuer) {
+	const cached = toCached(issuer);
+	if (cached) return cached;
 	const url = `${issuer.replace(/\/+$/, "")}${METADATA_PATH}`;
 	let response;
 	try {
@@ -273,8 +457,39 @@ async function toMetadata(issuer) {
 	const parsed = AuthorizationServerMetadata.safeParse(await response.json().catch(() => void 0));
 	if (!parsed.success) throw new DiscoveryFailure(`${url} does not describe an authorization server`);
 	if (parsed.data.issuer.replace(/\/+$/, "") !== issuer.replace(/\/+$/, "")) throw new DiscoveryFailure(`${url} names issuer ${parsed.data.issuer}, which is not the host it was read from`);
+	keep(issuer, parsed.data);
 	return parsed.data;
 }
+/** toCachePath names where one server's document is kept, beside the credentials. */
+function toCachePath(issuer) {
+	const name = createHash("sha256").update(issuer).digest("hex").slice(0, 16);
+	return join(dirname(toCredentialPath()), `metadata-${name}.json`);
+}
+function toCached(issuer) {
+	const path = toCachePath(issuer);
+	if (!existsSync(path)) return;
+	try {
+		const held = JSON.parse(readFileSync(path, "utf8"));
+		if ((held.readAt ?? 0) + CACHE_MS < Date.now()) return;
+		const parsed = AuthorizationServerMetadata.safeParse(held.document);
+		return parsed.success ? parsed.data : void 0;
+	} catch {
+		return;
+	}
+}
+function keep(issuer, document) {
+	const path = toCachePath(issuer);
+	try {
+		mkdirSync(dirname(path), {
+			recursive: true,
+			mode: 448
+		});
+		writeFileSync(path, JSON.stringify({
+			readAt: Date.now(),
+			document
+		}), { mode: 384 });
+	} catch {}
+}
 //#endregion
 //#region src/auth/grant.ts
 const TokenResponse = z.looseObject({
@@ -282,6 +497,7 @@ const TokenResponse = z.looseObject({
 	token_type: z.string(),
 	expires_in: z.number().optional(),
 	refresh_token: z.string().optional(),
+	refresh_token_expires_in: z.number().optional(),
 	scope: z.string().optional()
 });
 /** GrantFailure is a token request the authorization server refused. */
@@ -295,7 +511,7 @@ var GrantFailure = class extends Error {
 };
 /** toTokensFromCode trades an authorization code for tokens. */
 async function toTokensFromCode(tokenUrl, clientId, code, redirectUri, pkce) {
-	return await request$1(tokenUrl, {
+	return await toTokens(tokenUrl, {
 		grant_type: "authorization_code",
 		client_id: clientId,
 		code,
@@ -305,7 +521,7 @@ async function toTokensFromCode(tokenUrl, clientId, code, redirectUri, pkce) {
 }
 /** toTokensFromRefresh trades a refresh token for a fresh pair. */
 async function toTokensFromRefresh(tokenUrl, clientId, refreshToken) {
-	return await request$1(tokenUrl, {
+	return await toTokens(tokenUrl, {
 		grant_type: "refresh_token",
 		client_id: clientId,
 		refresh_token: refreshToken
@@ -323,8 +539,8 @@ async function revoke(revocationUrl, clientId, token) {
 		})
 	});
 }
-/** The token endpoint answers a flat RFC 6749 body, not the API's envelope. */
-async function request$1(url, form) {
+/** toTokens asks the token endpoint, which answers a flat RFC 6749 body, not the envelope. */
+async function toTokens(url, form) {
 	const response = await fetch(url, {
 		method: "POST",
 		headers: {
@@ -334,132 +550,26 @@ async function request$1(url, form) {
 		body: new URLSearchParams(form)
 	});
 	const body = await response.json().catch(() => void 0);
-	if (!response.ok) throw new GrantFailure(String(body?.["error"] ?? `http_${response.status}`), body?.["error_description"] === void 0 ? void 0 : String(body["error_description"]));
+	if (!response.ok) throw new GrantFailure(toText(body?.["error"] ?? `http_${response.status}`), body?.["error_description"] === void 0 ? void 0 : toText(body["error_description"]));
 	const parsed = TokenResponse.safeParse(body);
 	if (!parsed.success) throw new GrantFailure("invalid_response", "the token endpoint did not answer with a token");
 	return {
 		accessToken: parsed.data.access_token,
 		refreshToken: parsed.data.refresh_token,
+		refreshExpiresAt: parsed.data.refresh_token_expires_in === void 0 ? void 0 : Date.now() + parsed.data.refresh_token_expires_in * 1e3,
 		scope: parsed.data.scope,
 		expiresAt: parsed.data.expires_in === void 0 ? void 0 : Date.now() + parsed.data.expires_in * 1e3
 	};
 }
 //#endregion
-//#region src/credential/store.ts
-const load = createRequire(import.meta.url);
-/** The service a keyring entry is filed under, alongside the issuer it belongs to. */
-const SERVICE = "hardfin-cli";
-const FILE_MODE = 384;
-const DIRECTORY_MODE$1 = 448;
-/** toCredentialPath names the file the fallback keeps refresh tokens in. */
-function toCredentialPath() {
-	const base = process.env["XDG_STATE_HOME"] ?? join(homedir(), ".local", "state");
-	return join(base, "hardfin", "credentials.json");
-}
-/**
-* keep writes a refresh token for one issuer. Only the refresh token is stored, so a stolen
-* entry is revocable, and access tokens live in the process that fetched them.
-*
-* A rotation keeps the date of the original sign in, because that is what the server's
-* family lifetime runs from. Callers hold the credential lock, which is what makes a write
-* from another process merge rather than disappear.
-*/
-function keep(issuer, refreshToken) {
-	const now = (/* @__PURE__ */ new Date()).toISOString();
-	const record = {
-		refreshToken,
-		signedInAt: toCredential(issuer)?.signedInAt ?? now,
-		renewedAt: now
-	};
-	const keyring = toKeyring(issuer);
-	if (keyring) try {
-		keyring.setPassword(JSON.stringify(record));
-		return "keyring";
-	} catch {}
-	writeFile({
-		...readFile(),
-		[issuer]: record
-	});
-	return "file";
-}
-/** toCredential reads what is held for an issuer, and where it was held. */
-function toCredential(issuer) {
-	const keyring = toKeyring(issuer);
-	if (keyring) try {
-		const held = keyring.getPassword();
-		if (held) return {
-			...toRecord(held),
-			backend: "keyring"
-		};
-	} catch {}
-	const held = readFile()[issuer];
-	return held === void 0 ? void 0 : {
-		...held,
-		backend: "file",
-		path: toCredentialPath()
-	};
-}
-/** toRecord reads a stored entry, which older versions wrote as the bare token. */
-function toRecord(held) {
-	if (!held.startsWith("{")) return { refreshToken: held };
-	try {
-		return JSON.parse(held);
-	} catch {
-		return { refreshToken: held };
-	}
-}
-/** forget removes whatever is held for an issuer, in both places. */
-function forget(issuer) {
-	const keyring = toKeyring(issuer);
-	if (keyring) try {
-		keyring.deletePassword();
-	} catch {}
-	const held = readFile();
-	if (held[issuer] === void 0) return;
-	delete held[issuer];
-	if (Object.keys(held).length === 0) {
-		rmSync(toCredentialPath(), { force: true });
-		return;
-	}
-	writeFile(held);
-}
-/** toKeyring opens the OS keyring, or answers undefined where the platform has none. */
-function toKeyring(issuer) {
-	if (process.env["HARDFIN_CREDENTIAL_STORE"] === "file") return;
-	try {
-		const { Entry } = load("@napi-rs/keyring");
-		return new Entry(SERVICE, issuer);
-	} catch {
-		return;
-	}
-}
-function readFile() {
-	try {
-		const parsed = JSON.parse(readFileSync(toCredentialPath(), "utf8"));
-		if (typeof parsed !== "object" || parsed === null) return {};
-		return Object.fromEntries(Object.entries(parsed).map(([issuer, held]) => [issuer, typeof held === "string" ? { refreshToken: held } : held]));
-	} catch {
-		return {};
-	}
-}
-function writeFile(held) {
-	const path = toCredentialPath();
-	mkdirSync(dirname(path), {
-		recursive: true,
-		mode: DIRECTORY_MODE$1
-	});
-	const pending = `${path}.${process.pid}.tmp`;
-	writeFileSync(pending, `${JSON.stringify(held, null, 2)}\n`, { mode: FILE_MODE });
-	chmodSync(pending, FILE_MODE);
-	renameSync(pending, path);
-}
-//#endregion
 //#region src/credential/lock.ts
 /** A lock held longer than this belongs to a process that died, so it is taken. */
 const STALE_MS = 3e4;
 const WAIT_MS$1 = 1e4;
 const RETRY_MS = 25;
 const DIRECTORY_MODE = 448;
+/** What this process wrote into the lock, which is how it knows the lock is still its own. */
+let heldBy;
 /** toLockPath names the lock every process coordinates credential writes through. */
 function toLockPath() {
 	return join(dirname(toCredentialPath()), "credentials.lock");
@@ -471,17 +581,23 @@ function tryAcquire() {
 		recursive: true,
 		mode: DIRECTORY_MODE
 	});
+	const mark = `${process.pid}:${randomUUID()}`;
 	try {
 		const handle = openSync(path, "wx");
-		writeSync(handle, String(process.pid));
+		writeSync(handle, mark);
 		closeSync(handle);
+		heldBy = mark;
 		return true;
 	} catch {
-		return isStale(path) ? steal(path) : false;
+		return isStale(path) ? steal(path, mark) : false;
 	}
 }
-/** release lets the next process in. */
+/** release lets the next process in, and only ever removes this process's own lock. */
 function release$1() {
+	const mark = heldBy;
+	if (mark === void 0) return;
+	heldBy = void 0;
+	if (toMark(toLockPath()) !== mark) return;
 	rmSync(toLockPath(), { force: true });
 }
 /**
@@ -508,9 +624,29 @@ function isStale(path) {
 		return true;
 	}
 }
-function steal(path) {
+/**
+* steal takes over a lock whose holder is gone. Two processes can reach this at once, so
+* the winner is whichever mark survives in the file, not whichever removed it.
+*/
+function steal(path, mark) {
 	rmSync(path, { force: true });
-	return tryAcquire();
+	try {
+		const handle = openSync(path, "wx");
+		writeSync(handle, mark);
+		closeSync(handle);
+	} catch {
+		return false;
+	}
+	if (toMark(path) !== mark) return false;
+	heldBy = mark;
+	return true;
+}
+function toMark(path) {
+	try {
+		return readFileSync(path, "utf8");
+	} catch {
+		return;
+	}
 }
 //#endregion
 //#region src/auth/session.ts
@@ -536,6 +672,7 @@ async function toRequestCredential(settings) {
 		value: settings.apiKey,
 		kind: "api key"
 	};
+	refuseForeignHost(settings);
 	const stored = toCredential(settings.issuerUrl);
 	if (!stored) throw new NoCredential("not authenticated. Run hardfin login, or set HARDFIN_API_KEY");
 	return {
@@ -552,12 +689,74 @@ async function toAccessToken(settings, refreshToken) {
 	const metadata = await toMetadata(settings.issuerUrl);
 	return await withLock(async () => {
 		const latest = toCredential(settings.issuerUrl)?.refreshToken ?? refreshToken;
-		const tokens = await toTokensFromRefresh(metadata.token_endpoint, settings.clientId, latest);
-		held.set(settings.issuerUrl, tokens);
-		if (tokens.refreshToken && tokens.refreshToken !== latest) keep(settings.issuerUrl, tokens.refreshToken);
-		return tokens;
+		try {
+			const tokens = toDated(await toTokensFromRefresh(metadata.token_endpoint, settings.clientId, latest));
+			held.set(settings.issuerUrl, tokens);
+			store(settings.issuerUrl, tokens, latest);
+			return tokens;
+		} catch (error) {
+			if (error instanceof GrantFailure && isDead(error.code)) {
+				forget(settings.issuerUrl);
+				throw new NoCredential(`the sign in for ${settings.issuerUrl} is no longer valid, so it was removed. Run hardfin login`);
+			}
+			throw error;
+		}
 	});
 }
+/**
+* invalid_grant is the only refusal that says anything about the refresh token itself.
+* invalid_client and unauthorized_client describe the client registration, which is server
+* configuration and a setting a person can mistype, so a good credential survives them.
+*/
+function isDead(code) {
+	return code === "invalid_grant";
+}
+/**
+* toDated fills in when an access token expires. A token endpoint that states no expires_in
+* would otherwise have this process refresh on every command, and every refresh spends a
+* generation of the token family.
+*/
+function toDated(tokens) {
+	if (tokens.expiresAt !== void 0) return tokens;
+	return {
+		...tokens,
+		expiresAt: toClaims(tokens.accessToken).expiresAt
+	};
+}
+/**
+* store writes what a rotation issued. The old token is spent either way, so failing to
+* write the new one is worth saying out loud rather than failing a command that succeeded.
+*/
+function store(issuer, tokens, previous) {
+	if (!tokens.refreshToken || tokens.refreshToken === previous) return;
+	try {
+		keep$1(issuer, tokens.refreshToken, tokens.refreshExpiresAt);
+	} catch (error) {
+		process.stderr.write(`warning: this sign in was renewed but could not be stored, so the next command will ask you to sign in again: ${error instanceof Error ? error.message : String(error)}\n`);
+	}
+}
+/**
+* refuseForeignHost keeps an access token on the host that issued it. The API URL and the
+* authorization server are configured separately, and a directory's config file can set
+* either, so nothing else stops a token minted for Hardfin being sent somewhere else.
+*/
+function refuseForeignHost(settings) {
+	const api = toHost(settings.apiUrl);
+	const issuer = toHost(settings.issuerUrl);
+	if (api === void 0 || issuer === void 0) throw new NoCredential(`${settings.apiUrl} is not a URL this CLI can call`);
+	if (api.host !== issuer.host) throw new NoCredential(`this sign in belongs to ${issuer.host}, so it is not sent to ${api.host}. Set HARDFIN_API_KEY to call another host, or point --issuer-url at the server that signs you in`);
+	if (api.protocol !== "https:" && !isLoopback(api.hostname)) throw new NoCredential(`${settings.apiUrl} is not https, so a sign in is not sent to it`);
+}
+function toHost(url) {
+	try {
+		return new URL(url);
+	} catch {
+		return;
+	}
+}
+function isLoopback(hostname) {
+	return hostname === "127.0.0.1" || hostname === "::1" || hostname === "[::1]" || hostname === "localhost";
+}
 /** forgetHeldTokens drops the access tokens this process is holding. */
 function forgetHeldTokens() {
 	held.clear();
@@ -580,18 +779,23 @@ var RequestFailure = class extends Error {
 /** request calls one /v2 endpoint and returns the envelope it answered with. */
 async function request(options) {
 	const url = new URL(`${options.apiUrl}${toLeadingSlash(options.path)}`);
-	if (options.query) url.search = options.query.toString();
+	for (const [name, value] of options.query ?? []) url.searchParams.append(name, value);
 	const headers = {
 		[options.credential.header]: options.credential.value,
 		"X-API-Version": API_VERSION,
-		Accept: "application/json"
+		Accept: options.downloads ? "*/*" : "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))
 	});
+	if (options.downloads && response.ok) return { data: {
+		bytes: Buffer.from(await response.arrayBuffer()),
+		contentType: response.headers.get("content-type"),
+		fileName: toFileName(response.headers.get("content-disposition"))
+	} };
 	const envelope = toEnvelope(await response.text());
 	if (!response.ok && envelope === void 0) throw new RequestFailure(response.status, [{
 		error: toStatusMessage(response.status),
@@ -606,6 +810,11 @@ async function request(options) {
 	}
 	return envelope ?? { data: null };
 }
+/** toFileName reads the name a download was offered under, when the server names one. */
+function toFileName(disposition) {
+	const matched = /filename\*?=(?:UTF-8'')?"?([^";]+)"?/i.exec(disposition ?? "");
+	return matched?.[1] ? decodeURIComponent(matched[1]) : void 0;
+}
 function toLeadingSlash(path) {
 	return path.startsWith("/") ? path : `/${path}`;
 }
@@ -688,6 +897,10 @@ async function runApi(input) {
 		writeFailure("a path is required, such as /customer", input.isJSON);
 		return ExitCode.USAGE;
 	}
+	if (path.split("/").includes("..")) {
+		writeFailure("a path stays inside the API, so it cannot contain ..", input.isJSON);
+		return ExitCode.USAGE;
+	}
 	const query = toQuery$1(input.flags["field"]);
 	if (query === void 0) {
 		writeFailure("each --field is key=value, such as -f limit=50", input.isJSON);
@@ -705,7 +918,7 @@ async function runApi(input) {
 		writeData((await request({
 			apiUrl: input.resolved.settings.apiUrl,
 			credential: await toRequestCredential(input.resolved.settings),
-			method: String(input.flags["method"] ?? "GET").toUpperCase(),
+			method: toText(input.flags["method"] ?? "GET").toUpperCase(),
 			path,
 			query,
 			body
@@ -717,7 +930,7 @@ async function runApi(input) {
 			return ExitCode.NOT_AUTHENTICATED;
 		}
 		if (error instanceof RequestFailure) {
-			writeFailure(error.message, input.isJSON, error.errors, error.requestId);
+			writeFailure(error.message, input.isJSON, error.errors, error.requestId, error.status);
 			return error.status === 401 ? ExitCode.NOT_AUTHENTICATED : ExitCode.ERROR;
 		}
 		writeFailure(error instanceof Error ? error.message : String(error), input.isJSON);
@@ -743,6 +956,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 = 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",
@@ -825,8 +1164,8 @@ function toOpeners(url) {
 	return [["xdg-open", [url]]];
 }
 /** openBrowser asks the desktop to show a URL, and reports whether anything took it. */
-function openBrowser(url) {
-	for (const [command, args] of toOpeners(url)) if (spawnSync(command, args, {
+function openBrowser(url, launch = spawnSync) {
+	for (const [command, args] of toOpeners(url)) if (launch(command, args, {
 		stdio: "ignore",
 		cwd: command.endsWith(".exe") ? "/mnt/c" : void 0,
 		timeout: 1e4
@@ -834,6 +1173,74 @@ function openBrowser(url) {
 	return false;
 }
 //#endregion
+//#region src/auth/device.ts
+const DEVICE_GRANT = "urn:ietf:params:oauth:grant-type:device_code";
+/** The interval a server gives is in seconds, and five more are added on a slow_down. */
+const DEFAULT_INTERVAL_SECONDS = 5;
+const SLOW_DOWN_SECONDS = 5;
+const DeviceResponse = z.looseObject({
+	device_code: z.string(),
+	user_code: z.string(),
+	verification_uri: z.string(),
+	verification_uri_complete: z.string().optional(),
+	expires_in: z.number(),
+	interval: z.number().optional()
+});
+/** toDeviceAuthorization asks for a code a person can type on another machine. */
+async function toDeviceAuthorization(endpoint, clientId, scope) {
+	const response = await fetch(endpoint, {
+		method: "POST",
+		headers: {
+			"Content-Type": "application/x-www-form-urlencoded",
+			Accept: "application/json"
+		},
+		body: new URLSearchParams({
+			client_id: clientId,
+			scope
+		})
+	});
+	const body = await response.json().catch(() => void 0);
+	if (!response.ok) throw new GrantFailure(toText(body?.["error"] ?? `http_${response.status}`), body?.["error_description"] === void 0 ? void 0 : toText(body["error_description"]));
+	const parsed = DeviceResponse.safeParse(body);
+	if (!parsed.success) throw new GrantFailure("invalid_response", "the device endpoint did not answer with a code");
+	return {
+		deviceCode: parsed.data.device_code,
+		userCode: parsed.data.user_code,
+		verificationUri: parsed.data.verification_uri,
+		verificationUriComplete: parsed.data.verification_uri_complete,
+		expiresAt: Date.now() + parsed.data.expires_in * 1e3,
+		intervalMs: (parsed.data.interval ?? DEFAULT_INTERVAL_SECONDS) * 1e3
+	};
+}
+/**
+* toTokensFromDevice waits for the person to approve on another machine. The server answers
+* authorization_pending until they do, and slow_down when this asked too often.
+*/
+async function toTokensFromDevice(tokenUrl, clientId, device, sleep = toSleep) {
+	let intervalMs = device.intervalMs;
+	for (;;) {
+		if (Date.now() > device.expiresAt) throw new GrantFailure("expired_token", "the code expired before it was approved");
+		await sleep(intervalMs);
+		try {
+			return await toTokens(tokenUrl, {
+				grant_type: DEVICE_GRANT,
+				client_id: clientId,
+				device_code: device.deviceCode
+			});
+		} catch (error) {
+			if (!(error instanceof GrantFailure)) throw error;
+			if (error.code === "slow_down") {
+				intervalMs += SLOW_DOWN_SECONDS * 1e3;
+				continue;
+			}
+			if (error.code !== "authorization_pending") throw error;
+		}
+	}
+}
+function toSleep(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//#endregion
 //#region src/auth/loopback.ts
 /** The path the browser is sent back to, which the client metadata document registers. */
 const CALLBACK_PATH = "/callback";
@@ -869,8 +1276,12 @@ async function toListener(timeoutMs) {
 	}, timeoutMs);
 	return {
 		redirectUri: `http://${HOST}:${server.address().port}${CALLBACK_PATH}`,
-		callback: callback.finally(() => close(server, timer)),
-		close: () => close(server, timer)
+		callback: callback.finally(() => {
+			close(server, timer);
+		}),
+		close: () => {
+			close(server, timer);
+		}
 	};
 }
 function toCallback(request) {
@@ -924,11 +1335,11 @@ function toClipboardCommand() {
 	return ["xclip", ["-selection", "clipboard"]];
 }
 /** copyToClipboard puts text on the clipboard, and reports whether anything took it. */
-function copyToClipboard(text) {
+function copyToClipboard(text, copy = spawnSync) {
 	const command = toClipboardCommand();
 	if (!command) return false;
 	const [name, args] = command;
-	const result = spawnSync(name, args, { input: text });
+	const result = copy(name, args, { input: text });
 	return result.error === void 0 && result.status === 0;
 }
 //#endregion
@@ -964,20 +1375,21 @@ function toPastedCallback(pasted) {
 * toPrompt watches the keyboard while the browser is away. Pressing c copies the URL, and
 * pasting a code finishes the sign in on a machine whose browser cannot reach this listener.
 */
-function toPrompt(url) {
+function toPrompt(url, input = process.stdin, copy = copyToClipboard) {
 	let settle = () => {};
 	let fail = () => {};
 	const pasted = new Promise((resolve, reject) => {
 		settle = resolve;
 		fail = reject;
 	});
-	const input = process.stdin;
+	pasted.catch(() => {});
 	if (!input.isTTY) return {
 		pasted,
 		close: () => {}
 	};
 	let typed = "";
 	const onData = (chunk) => {
+		const isKeystroke = chunk.length === 1;
 		for (const character of chunk) {
 			if (character === CTRL_C) {
 				fail(/* @__PURE__ */ new Error("sign in was cancelled"));
@@ -994,8 +1406,8 @@ function toPrompt(url) {
 				process.stderr.write("\b \b");
 				continue;
 			}
-			if ((character === "c" || character === "C") && typed === "") {
-				process.stderr.write(copyToClipboard(url) ? "Copied the URL to your clipboard\n" : "Nothing on this host takes a clipboard\n");
+			if (isKeystroke && (character === "c" || character === "C") && typed === "") {
+				process.stderr.write(copy(url) ? "Copied the URL to your clipboard\n" : "Nothing on this host takes a clipboard\n");
 				continue;
 			}
 			typed += character;
@@ -1039,19 +1451,31 @@ const loginCommand = defineCommand({
 			description: "Print the URL instead of opening it",
 			schema: z.boolean()
 		},
+		{
+			name: "device",
+			description: "Approve on another machine, by typing a code, with no listener on this one",
+			schema: z.boolean()
+		},
 		{
 			name: "json",
 			description: "Print machine-readable output, which is the default when stdout is not a terminal",
 			schema: z.boolean()
 		}
 	],
-	examples: [{
-		description: "Sign in",
-		command: "hardfin login"
-	}, {
-		description: "Sign in over SSH, opening the URL yourself",
-		command: "hardfin login --no-browser"
-	}],
+	examples: [
+		{
+			description: "Sign in",
+			command: "hardfin login"
+		},
+		{
+			description: "Sign in over SSH, opening the URL yourself",
+			command: "hardfin login --no-browser"
+		},
+		{
+			description: "Approve from your phone or another machine",
+			command: "hardfin login --device"
+		}
+	],
 	run: runLogin
 });
 async function runLogin(input) {
@@ -1059,13 +1483,15 @@ async function runLogin(input) {
 	try {
 		const clientId = settings.clientId;
 		const metadata = await toMetadata(settings.issuerUrl);
+		const scope = toText(input.flags["scope"] ?? DEFAULT_SCOPES);
+		if (input.flags["device"] === true) return await runDeviceLogin(input, metadata, scope);
 		const listener = await toListener(WAIT_MS);
 		const pkce = toPkce();
 		const state = toState();
 		const url = toAuthorizationUrl(metadata.authorization_endpoint, {
 			clientId,
 			redirectUri: listener.redirectUri,
-			scope: String(input.flags["scope"] ?? DEFAULT_SCOPES),
+			scope,
 			state,
 			challenge: pkce.challenge
 		});
@@ -1073,9 +1499,13 @@ async function runLogin(input) {
 		process.stderr.write(opened ? `Opening your browser to sign in. If it did not open:\n\n${url}\n\n` : `Open this URL to sign in:\n\n${url}\n\n`);
 		const prompt = toPrompt(url);
 		if (process.stdin.isTTY) process.stderr.write("Press c to copy the URL, or paste the code or redirect URL here: ");
-		const callback = await Promise.race([listener.callback, prompt.pasted]);
-		listener.close();
-		prompt.close();
+		let callback;
+		try {
+			callback = await Promise.race([listener.callback, prompt.pasted]);
+		} finally {
+			listener.close();
+			prompt.close();
+		}
 		process.stderr.write(callback.error ? "\n" : "\nApproved, finishing the sign in\n");
 		if (callback.error) {
 			writeFailure(`sign in was refused: ${callback.error}${callback.errorDescription ? `, ${callback.errorDescription}` : ""}`, input.isJSON);
@@ -1093,31 +1523,7 @@ async function runLogin(input) {
 			writeFailure("the browser came back without an authorization code", input.isJSON);
 			return ExitCode.ERROR;
 		}
-		const tokens = await toTokensFromCode(metadata.token_endpoint, clientId, callback.code, listener.redirectUri, pkce);
-		const refreshToken = tokens.refreshToken;
-		if (!refreshToken) {
-			writeFailure("the authorization server issued no refresh token, so this sign in cannot be kept", input.isJSON);
-			return ExitCode.ERROR;
-		}
-		const backend = await withLock(() => keep(settings.issuerUrl, refreshToken));
-		if (input.isJSON) {
-			writeData({
-				signedIn: true,
-				issuer: metadata.issuer,
-				scope: tokens.scope ?? null,
-				storedIn: backend
-			});
-			return ExitCode.OK;
-		}
-		const stored = backend === "keyring" ? "your OS keyring" : toCredentialPath();
-		writeData([
-			`Signed in to ${metadata.issuer}`,
-			`Scope     ${tokens.scope ?? "as granted"}`,
-			`Stored in ${stored}`,
-			"",
-			"Run hardfin status to see what this CLI is using"
-		].join("\n"));
-		return ExitCode.OK;
+		return await toSignedIn(input, metadata, await toTokensFromCode(metadata.token_endpoint, clientId, callback.code, listener.redirectUri, pkce));
 	} catch (error) {
 		if (error instanceof DiscoveryFailure || error instanceof GrantFailure) {
 			writeFailure(error.message, input.isJSON);
@@ -1127,6 +1533,61 @@ async function runLogin(input) {
 		return ExitCode.ERROR;
 	}
 }
+/** runDeviceLogin waits while the person approves on a machine that has a browser. */
+async function runDeviceLogin(input, metadata, scope) {
+	const settings = input.resolved.settings;
+	if (!metadata.device_authorization_endpoint) {
+		writeFailure(`${metadata.issuer} does not offer the device grant, so sign in without --device`, input.isJSON);
+		return ExitCode.ERROR;
+	}
+	const device = await toDeviceAuthorization(metadata.device_authorization_endpoint, settings.clientId, scope);
+	const url = device.verificationUriComplete ?? device.verificationUri;
+	const opened = input.flags["noBrowser"] !== true && !process.env["HARDFIN_NO_BROWSER"] && openBrowser(url);
+	process.stderr.write([
+		"",
+		`  Code  ${device.userCode}`,
+		`  At    ${device.verificationUri}`,
+		"",
+		opened ? "Opened your browser there. Waiting for approval\n" : "Open that page on any machine, and enter the code. Waiting for approval\n"
+	].join("\n"));
+	const prompt = toPrompt(url);
+	try {
+		return await toSignedIn(input, metadata, await Promise.race([toTokensFromDevice(metadata.token_endpoint, settings.clientId, device), prompt.pasted.then(toCancelled)]));
+	} finally {
+		prompt.close();
+	}
+}
+/** toCancelled ends a device sign in that the keyboard interrupted. */
+function toCancelled() {
+	throw new Error("sign in was cancelled");
+}
+/** toSignedIn stores what a sign in issued, whichever flow issued it. */
+async function toSignedIn(input, metadata, tokens) {
+	const refreshToken = tokens.refreshToken;
+	if (!refreshToken) {
+		writeFailure("the authorization server issued no refresh token, so this sign in cannot be kept", input.isJSON);
+		return ExitCode.ERROR;
+	}
+	const backend = await withLock(() => keep$1(input.resolved.settings.issuerUrl, refreshToken, tokens.refreshExpiresAt));
+	if (input.isJSON) {
+		writeData({
+			signedIn: true,
+			issuer: metadata.issuer,
+			scope: tokens.scope ?? null,
+			storedIn: backend
+		});
+		return ExitCode.OK;
+	}
+	const stored = backend === "keyring" ? "your OS keyring" : toCredentialPath();
+	writeData([
+		`Signed in to ${metadata.issuer}`,
+		`Scope     ${tokens.scope ?? "as granted"}`,
+		`Stored in ${stored}`,
+		"",
+		"Run hardfin status to see what this CLI is using"
+	].join("\n"));
+	return ExitCode.OK;
+}
 /** toAuthorizationUrl builds the URL the person approves this CLI at. */
 function toAuthorizationUrl(endpoint, request) {
 	const url = new URL(endpoint);
@@ -1178,7 +1639,9 @@ async function runLogout(input) {
 	} catch {
 		revoked = false;
 	}
-	await withLock(() => forget(settings.issuerUrl));
+	await withLock(() => {
+		forget(settings.issuerUrl);
+	});
 	forgetHeldTokens();
 	writeData({
 		signedOut: true,
@@ -1188,11 +1651,344 @@ 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"]
+	}
+};
+/** ProtocolFailure is a line this server answers with a JSON-RPC error rather than a result. */
+var ProtocolFailure = class extends Error {
+	code;
+	id;
+	constructor(code, message, id) {
+		super(message);
+		this.name = "ProtocolFailure";
+		this.code = code;
+		this.id = id;
+	}
+};
+/** 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": {
+			const uri = toText(request.params?.["uri"] ?? "");
+			const resource = toResource(uri, commands);
+			if (!resource) return {
+				jsonrpc: "2.0",
+				id: request.id ?? null,
+				error: {
+					code: -32002,
+					message: `${uri} is not a resource this server offers`
+				}
+			};
+			return answer(resource);
+		}
+		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`
+				}
+			};
+	}
+}
+/** The revisions this server speaks, newest first, which is what it may answer with. */
+const PROTOCOL_VERSIONS = [
+	PROTOCOL_VERSION,
+	"2025-03-26",
+	"2024-11-05"
+];
+/** toProtocolVersion answers a version this server implements, never one it was told. */
+function toProtocolVersion(params) {
+	const asked = params?.["protocolVersion"];
+	return typeof asked === "string" && PROTOCOL_VERSIONS.includes(asked) ? 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)
+	}] };
+}
+/** 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
+	}));
+}
+/** Signing in needs a browser and a person, neither of which an agent's session has. */
+const REFUSED_COMMANDS = /* @__PURE__ */ new Set([
+	"login",
+	"logout",
+	"mcp"
+]);
+/** The global options, which sit before a command and take a value of their own. */
+const GLOBAL_OPTIONS_WITH_VALUES = /* @__PURE__ */ new Set(["--api-url", "--issuer-url"]);
+/**
+* toCommandName reads which command a call names. A global option sits before it, so
+* reading the first argument alone would let --issuer-url x logout through.
+*/
+function toCommandName(args) {
+	for (let index = 0; index < args.length; index += 1) {
+		const argument = args[index] ?? "";
+		if (GLOBAL_OPTIONS_WITH_VALUES.has(argument)) {
+			index += 1;
+			continue;
+		}
+		if (argument.startsWith("-")) continue;
+		return argument;
+	}
+}
+/** toIsAskingForHelp reports whether a call only wants to read about a command. */
+function toIsAskingForHelp(args) {
+	return args.includes("--help") || args.includes("-h") || args[0] === "help";
+}
+async function toToolResult(params, run) {
+	if (params?.["name"] !== TOOL.name) return {
+		content: [{
+			type: "text",
+			text: `a call names its tool, and this server offers one, ${TOOL.name}`
+		}],
+		isError: true
+	};
+	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 refused = toRefusedArgument(args);
+	if (refused) return {
+		content: [{
+			type: "text",
+			text: refused
+		}],
+		isError: true
+	};
+	const asked = args;
+	const command = toCommandName(asked) ?? "";
+	if (REFUSED_COMMANDS.has(command) && !toIsAskingForHelp(asked)) return {
+		content: [{
+			type: "text",
+			text: `${command} is run by a person at a terminal, not through this server. Run hardfin ${command} yourself, then call this tool again`
+		}],
+		isError: true
+	};
+	const outcome = await run(asked);
+	return {
+		content: [{
+			type: "text",
+			text: [outcome.stdout, outcome.stderr].filter((part) => part.trim() !== "").join("\n") || `hardfin exited ${outcome.code}`
+		}],
+		isError: outcome.code !== 0
+	};
+}
+/** The most a command line can carry, below what the operating system refuses outright. */
+const ARGUMENT_LIMIT = 1e5;
+/** toRefusedArgument names an argument a command line cannot carry, rather than failing later. */
+function toRefusedArgument(args) {
+	const withNul = args.findIndex((argument) => argument.includes("\0"));
+	if (withNul >= 0) return `args[${withNul}] holds a NUL byte, which a command line cannot carry`;
+	const total = args.reduce((carried, argument) => carried + argument.length, 0);
+	if (total > ARGUMENT_LIMIT) return `these arguments are ${total} characters, and a command line carries at most ${ARGUMENT_LIMIT}`;
+}
+/** 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 });
+	const answering = /* @__PURE__ */ new Set();
+	for await (const line of lines) {
+		if (line.trim() === "") continue;
+		const answered = toAnswer(line, commands, run).finally(() => answering.delete(answered));
+		answering.add(answered);
+	}
+	await Promise.all(answering);
+}
+/** toAnswer replies to one line, and never rejects, because a rejection ends the server. */
+async function toAnswer(line, commands, run) {
+	let response;
+	try {
+		response = await toResponse(toRequest(line), commands, run);
+	} catch (error) {
+		response = error instanceof ProtocolFailure ? toErrorResponse(error.id, error.code, error.message) : toErrorResponse(toRequestId(line), -32603, error instanceof Error ? error.message : String(error));
+	}
+	if (response) write(`${JSON.stringify(response)}\n`);
+}
+/** toRequest reads one line, refusing what the protocol does not allow to be a request. */
+function toRequest(line) {
+	let parsed;
+	try {
+		parsed = JSON.parse(line);
+	} catch {
+		throw new ProtocolFailure(-32700, "this line is not JSON", null);
+	}
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) throw new ProtocolFailure(-32600, "a request is a JSON object, and this server takes one per line", null);
+	const request = parsed;
+	if (typeof request.method !== "string") throw new ProtocolFailure(-32600, "a request names a method", toAllowedId(request.id));
+	if (request.id !== void 0 && request.id !== null && typeof request.id !== "string" && typeof request.id !== "number") throw new ProtocolFailure(-32600, "an id is a string, a number, or null", null);
+	return request;
+}
+function toAllowedId(id) {
+	return typeof id === "string" || typeof id === "number" ? id : null;
+}
+function toErrorResponse(id, code, message) {
+	return {
+		jsonrpc: "2.0",
+		id,
+		error: {
+			code,
+			message
+		}
+	};
+}
+/** toRequestId reads the id of a line that could not be answered, so a client is not left waiting. */
+function toRequestId(line) {
+	try {
+		return toAllowedId(JSON.parse(line).id);
+	} catch {
+		return null;
+	}
+}
+/** write puts a reply on stdout, and stops quietly when the client has gone. */
+function write(text) {
+	try {
+		process.stdout.write(text);
+	} catch {}
+}
+//#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",
+/**
+* toEnum takes a value in any case, as the API does, and answers the spelling the document
+* lists, which is what a response always uses.
+*/
+function toEnum(values) {
+	return z.string().transform((value) => values.find((allowed) => allowed.toLowerCase() === value.toLowerCase()) ?? value).pipe(z.enum(values));
+}
+const UNSET_FLAG = {
+	name: "unset",
+	description: "A field to clear, named as its flag is, repeatable",
+	valueName: "field",
+	repeatable: true,
+	schema: z.array(z.string())
+};
+const FILE_FLAG = {
+	name: "file",
+	description: "The file to upload",
+	valueName: "path",
+	schema: z.string()
+};
+const OUTPUT_FLAG = {
+	name: "output",
+	description: "Where to write the file, or - for standard output",
+	valueName: "path",
 	schema: z.string()
 };
 const JSON_FLAG = {
@@ -1202,15 +1998,28 @@ 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.bodyFlags.some((flag) => flag.nullable) ? [UNSET_FLAG] : [],
+		...operation.upload ? [...operation.upload.fields, FILE_FLAG] : [],
+		...operation.downloads ? [OUTPUT_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
+		}] : [],
+		endpoint: {
+			method: operation.method,
+			path: operation.path
+		},
 		run: (input) => runOperation(operation, input)
 	};
 }
@@ -1220,23 +2029,42 @@ 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;
+	}
+	if (operation.bodyFlags.length > 0 && body === void 0) {
+		writeFailure(`this command changes nothing unless a flag is given, such as ${operation.bodyFlags.slice(0, 3).map((flag) => `--${flag.name}`).join(", ")}. Run it with --help for the rest`, 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({
+		const envelope = await request({
 			apiUrl: input.resolved.settings.apiUrl,
 			credential: await toRequestCredential(input.resolved.settings),
 			method: operation.method,
 			path,
 			query: toQuery(operation, input.flags),
-			body
-		})).data);
+			body,
+			form,
+			downloads: operation.downloads
+		});
+		if (operation.downloads) return toWritten(envelope.data, input);
+		writeData(envelope.data);
 		return ExitCode.OK;
 	} catch (error) {
 		if (error instanceof NoCredential) {
@@ -1244,13 +2072,36 @@ async function runOperation(operation, input) {
 			return ExitCode.NOT_AUTHENTICATED;
 		}
 		if (error instanceof RequestFailure) {
-			writeFailure(error.message, input.isJSON, error.errors, error.requestId);
+			writeFailure(error.message, input.isJSON, error.errors, error.requestId, error.status);
 			return error.status === 401 ? ExitCode.NOT_AUTHENTICATED : ExitCode.ERROR;
 		}
 		writeFailure(error instanceof Error ? error.message : String(error), input.isJSON);
 		return ExitCode.ERROR;
 	}
 }
+/**
+* toWritten puts a downloaded file where it was asked for. A terminal is never written to,
+* because a person would otherwise have their session filled with a file's bytes.
+*/
+function toWritten(download, input) {
+	const asked = input.flags["output"];
+	const path = typeof asked === "string" ? asked : download.fileName ?? "-";
+	if (path === "-") {
+		if (process.stdout.isTTY) {
+			writeFailure("this answer is a file, so name where to write it with --output, or send it on with a pipe", input.isJSON);
+			return ExitCode.USAGE;
+		}
+		process.stdout.write(download.bytes);
+		return ExitCode.OK;
+	}
+	writeFileSync(path, download.bytes);
+	writeData({
+		written: path,
+		bytes: download.bytes.length,
+		contentType: download.contentType
+	});
+	return ExitCode.OK;
+}
 /** toPath fills the path template from the positional arguments, in order. */
 function toPath(operation, args) {
 	if (args.length !== operation.pathParameters.length) return;
@@ -1264,7 +2115,9 @@ function toQuery(operation, flags) {
 	for (const flag of operation.queryFlags) {
 		const value = flags[toOptionKey(flag.name)];
 		if (value === void 0) continue;
-		for (const entry of Array.isArray(value) ? value : [value]) query.append(flag.queryName, String(entry));
+		const parsed = flag.schema.safeParse(value);
+		const carried = parsed.success ? parsed.data : value;
+		for (const entry of Array.isArray(carried) ? carried : [carried]) query.append(flag.queryName, toText(entry));
 	}
 	return query;
 }
@@ -1272,13 +2125,84 @@ 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) {
+			const parsed = field.schema.safeParse(value);
+			form.append(field.jsonPath[0] ?? field.name, toText(parsed.success ? parsed.data : 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(toText) : [toText(value)]);
+			if (elements instanceof Error) return elements;
+			set(body, flag.jsonPath, elements);
+			hasField = true;
+			continue;
+		}
+		const parsed = flag.schema.safeParse(value);
+		set(body, flag.jsonPath, parsed.success ? parsed.data : value);
+		hasField = true;
+	}
+	const cleared = toCleared(operation, flags, body);
+	if (cleared instanceof Error) return cleared;
+	return hasField || cleared ? body : void 0;
+}
+/** toCleared sends null for each field named by --unset, which is how a field is cleared. */
+function toCleared(operation, flags, body) {
+	const named = flags["unset"];
+	const names = Array.isArray(named) ? named.map(toText) : named === void 0 ? [] : [toText(named)];
+	for (const name of names) {
+		const flag = operation.bodyFlags.find((entry) => entry.name === name.replace(/^--/, ""));
+		if (!flag) return /* @__PURE__ */ new Error(`--unset names no field called ${name}`);
+		if (!flag.nullable) return /* @__PURE__ */ new Error(`--${flag.name} cannot be cleared, because the API does not accept null for it`);
+		set(body, flag.jsonPath, null);
+	}
+	return names.length > 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] ?? "field"}=value. A value cannot contain a comma`);
+			const key = pair.slice(0, split).trim();
+			if (flag.element && !flag.element.includes(key)) return /* @__PURE__ */ new Error(`--${flag.name} has no field ${key}. It takes ${flag.element.join(", ")}`);
+			if (key in element) return /* @__PURE__ */ new Error(`--${flag.name} names ${key} twice in one element, so which one it takes is not clear`);
+			element[key] = pair.slice(split + 1).trim();
+		}
+		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
@@ -1293,6 +2217,7 @@ const surfaceCommands = [
 			defineOperation({
 				name: "list",
 				summary: "Get asset listing",
+				example: "hardfin asset list --limit 10",
 				method: "GET",
 				path: "/asset",
 				pathParameters: [],
@@ -1302,21 +2227,21 @@ const surfaceCommands = [
 						queryName: "page",
 						description: "The page to return, starting at 1",
 						valueName: "number",
-						schema: z.coerce.number()
+						schema: z.coerce.number().int()
 					},
 					{
 						name: "limit",
 						queryName: "limit",
 						description: "The number of records per page, from 1 to 100",
 						valueName: "number",
-						schema: z.coerce.number()
+						schema: z.coerce.number().int().min(1).max(100)
 					},
 					{
 						name: "sort-by",
 						queryName: "sortBy",
 						description: "The field to sort by",
 						valueName: "value",
-						schema: z.enum([
+						schema: toEnum([
 							"serial",
 							"project",
 							"item",
@@ -1330,14 +2255,14 @@ const surfaceCommands = [
 						queryName: "sortOrder",
 						description: "The sort direction",
 						valueName: "value",
-						schema: z.enum(["ASC", "DESC"])
+						schema: toEnum(["ASC", "DESC"])
 					},
 					{
 						name: "archived",
 						queryName: "archived",
 						description: "Whether to return unarchived records, archived records, or all of them",
 						valueName: "value",
-						schema: z.enum([
+						schema: toEnum([
 							"all",
 							"false",
 							"true"
@@ -1354,9 +2279,9 @@ const surfaceCommands = [
 						name: "for-asset-id",
 						queryName: "forAssetId",
 						description: "The IDs of the assets to list",
-						valueName: "value",
+						valueName: "uuid",
 						repeatable: true,
-						schema: z.array(z.string())
+						schema: z.array(z.uuid())
 					},
 					{
 						name: "for-asset-key",
@@ -1370,33 +2295,33 @@ const surfaceCommands = [
 						name: "for-customer",
 						queryName: "forCustomer",
 						description: "The IDs of the customers whose assets to list",
-						valueName: "value",
+						valueName: "uuid",
 						repeatable: true,
-						schema: z.array(z.string())
+						schema: z.array(z.uuid())
 					},
 					{
 						name: "for-item",
 						queryName: "forItem",
 						description: "The IDs of the items whose assets to list",
-						valueName: "value",
+						valueName: "uuid",
 						repeatable: true,
-						schema: z.array(z.string())
+						schema: z.array(z.uuid())
 					},
 					{
 						name: "at-site",
 						queryName: "atSite",
 						description: "The IDs of the locations whose assets to list",
-						valueName: "value",
+						valueName: "uuid",
 						repeatable: true,
-						schema: z.array(z.string())
+						schema: z.array(z.uuid())
 					},
 					{
 						name: "at-customer-sites",
 						queryName: "atCustomerSites",
 						description: "The IDs of the customers whose sites to list assets at",
-						valueName: "value",
+						valueName: "uuid",
 						repeatable: true,
-						schema: z.array(z.string())
+						schema: z.array(z.uuid())
 					},
 					{
 						name: "with-functional-statuses",
@@ -1404,7 +2329,7 @@ const surfaceCommands = [
 						description: "The functional statuses to list, where SCRAPPED lists scrapped assets",
 						valueName: "value",
 						repeatable: true,
-						schema: z.array(z.enum([
+						schema: z.array(toEnum([
 							"FUNCTIONAL",
 							"NEEDS_REVIEW",
 							"NON-FUNCTIONAL",
@@ -1417,7 +2342,7 @@ const surfaceCommands = [
 						description: "The transit statuses to list",
 						valueName: "value",
 						repeatable: true,
-						schema: z.array(z.enum([
+						schema: z.array(toEnum([
 							"IN_TRANSIT",
 							"IN_TRANSIT_TO_FIELD",
 							"IN_TRANSIT_TO_INVENTORY",
@@ -1460,32 +2385,201 @@ const surfaceCommands = [
 						name: "for-project",
 						queryName: "forProject",
 						description: "The IDs of the projects whose assets to list",
-						valueName: "value",
+						valueName: "uuid",
 						repeatable: true,
-						schema: z.array(z.string())
+						schema: z.array(z.uuid())
 					},
 					{
 						name: "scrapped",
 						queryName: "scrapped",
 						description: "Whether to list unscrapped assets, scrapped assets, or all of them",
 						valueName: "value",
-						schema: z.enum([
+						schema: toEnum([
 							"all",
 							"false",
 							"true"
 						])
 					}
 				],
-				takesBody: false
+				bodyFlags: []
 			}),
 			defineOperation({
 				name: "create",
 				summary: "Create asset",
+				example: "hardfin asset create --item-id <uuid> --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",
+						nullable: true,
+						schema: z.string()
+					},
+					{
+						name: "bill-of-materials",
+						jsonPath: ["billOfMaterials"],
+						description: "The parts cost of one unit, a cost component",
+						valueName: "value",
+						nullable: true,
+						schema: z.string()
+					},
+					{
+						name: "depreciation-model",
+						jsonPath: ["depreciationModel"],
+						description: "The method one unit is depreciated by, or null to clear it",
+						valueName: "value",
+						schema: toEnum([
+							"DOUBLE_DECLINING",
+							"STRAIGHT_LINE",
+							"SUM_YEAR",
+							"UNIT_OF_PRODUCTION"
+						])
+					},
+					{
+						name: "description",
+						jsonPath: ["description"],
+						description: "A free-form description of the asset",
+						valueName: "value",
+						nullable: true,
+						schema: z.string()
+					},
+					{
+						name: "direct-labor",
+						jsonPath: ["directLabor"],
+						description: "The labor cost to build one unit, a cost component",
+						valueName: "value",
+						nullable: true,
+						schema: z.string()
+					},
+					{
+						name: "freight-inbound",
+						jsonPath: ["freightInbound"],
+						description: "The shipping cost to receive one unit, a cost component",
+						valueName: "value",
+						nullable: true,
+						schema: z.string()
+					},
+					{
+						name: "freight-outbound",
+						jsonPath: ["freightOutbound"],
+						description: "The shipping cost to deploy one unit, a deployment cost component",
+						valueName: "value",
+						nullable: true,
+						schema: z.string()
+					},
+					{
+						name: "functional-status",
+						jsonPath: ["functionalStatus"],
+						description: "The asset's starting functional status, FUNCTIONAL when absent, which cannot be SCRAPPED",
+						valueName: "value",
+						nullable: true,
+						schema: toEnum([
+							"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",
+						nullable: true,
+						schema: z.string()
+					},
+					{
+						name: "installation",
+						jsonPath: ["installation"],
+						description: "The cost to install one unit, a deployment cost component",
+						valueName: "value",
+						nullable: true,
+						schema: z.string()
+					},
+					{
+						name: "interest",
+						jsonPath: ["interest"],
+						description: "The financing cost of one unit, a cost component",
+						valueName: "value",
+						nullable: true,
+						schema: z.string()
+					},
+					{
+						name: "item-id",
+						jsonPath: ["itemId"],
+						description: "The ID of the catalog item the asset is a unit of",
+						valueName: "uuid",
+						required: true,
+						schema: z.uuid()
+					},
+					{
+						name: "location-id",
+						jsonPath: ["locationId"],
+						description: "The ID of the location the asset enters inventory at",
+						valueName: "uuid",
+						schema: z.uuid()
+					},
+					{
+						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",
+						nullable: true,
+						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",
+						nullable: true,
+						schema: z.string()
+					},
+					{
+						name: "tariffs",
+						jsonPath: ["tariffs"],
+						description: "The import duty paid on one unit, a cost component",
+						valueName: "value",
+						nullable: true,
+						schema: z.string()
+					},
+					{
+						name: "tax",
+						jsonPath: ["tax"],
+						description: "The tax paid on one unit, a cost component",
+						valueName: "value",
+						nullable: true,
+						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",
+						nullable: true,
+						schema: z.coerce.number().int()
+					}
+				]
 			}),
 			{
 				name: "move",
@@ -1502,11 +2596,28 @@ const surfaceCommands = [
 					subcommands: [defineOperation({
 						name: "create",
 						summary: "Execute asset move",
+						example: "hardfin asset move execute create --move assetId=<value>,deliverAt=<value>,deliverAtTimezone=<value>,destinationId=<value>,originId=<value>,shipAt=<value>,shipAtTimezone=<value>",
 						method: "POST",
 						path: "/asset/move/execute",
 						pathParameters: [],
 						queryFlags: [],
-						takesBody: true
+						bodyFlags: [{
+							name: "move",
+							jsonPath: ["moves"],
+							description: "The moves to carry out",
+							valueName: "assetId=,deliverAt=,deliverAtTimezone=,destinationId=,originId=,shipAt=,shipAtTimezone=",
+							repeatable: true,
+							element: [
+								"assetId",
+								"deliverAt",
+								"deliverAtTimezone",
+								"destinationId",
+								"originId",
+								"shipAt",
+								"shipAtTimezone"
+							],
+							schema: z.array(z.string())
+						}]
 					})]
 				}, {
 					name: "plan",
@@ -1517,17 +2628,32 @@ const surfaceCommands = [
 					subcommands: [defineOperation({
 						name: "create",
 						summary: "Plan asset move",
+						example: "hardfin asset move plan create --move assetId=<value>,deliverAt=<value>,id=<value>,shipAt=<value>",
 						method: "POST",
 						path: "/asset/move/plan",
 						pathParameters: [],
 						queryFlags: [],
-						takesBody: true
+						bodyFlags: [{
+							name: "move",
+							jsonPath: ["moves"],
+							description: "The moves to plan",
+							valueName: "assetId=,deliverAt=,id=,shipAt=",
+							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: [{
@@ -1536,11 +2662,12 @@ const surfaceCommands = [
 					required: true
 				}],
 				queryFlags: [],
-				takesBody: false
+				bodyFlags: []
 			}),
 			defineOperation({
 				name: "update",
 				summary: "Patch asset",
+				example: "hardfin asset update ast_4f9xk2mq7plr8stz --metadata fieldId=<value>,value=<value>",
 				method: "PATCH",
 				path: "/asset/{assetKey}",
 				pathParameters: [{
@@ -1549,7 +2676,62 @@ 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",
+						nullable: true,
+						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",
+						nullable: true,
+						schema: toEnum([
+							"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",
+						nullable: true,
+						schema: z.string()
+					},
+					{
+						name: "initial-location-id",
+						jsonPath: ["initialLocationId"],
+						description: "The ID of the location the asset entered inventory at",
+						valueName: "uuid",
+						nullable: true,
+						schema: z.uuid()
+					},
+					{
+						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",
+						nullable: true,
+						schema: z.string()
+					}
+				]
 			}),
 			{
 				name: "accounting",
@@ -1560,6 +2742,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: [{
@@ -1568,7 +2751,132 @@ 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",
+							nullable: true,
+							schema: z.string()
+						},
+						{
+							name: "bill-of-materials",
+							jsonPath: ["billOfMaterials"],
+							description: "The parts cost of one unit, a cost component",
+							valueName: "value",
+							nullable: true,
+							schema: z.string()
+						},
+						{
+							name: "depreciation-model",
+							jsonPath: ["depreciationModel"],
+							description: "The method one unit is depreciated by, or null to clear it",
+							valueName: "value",
+							schema: toEnum([
+								"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",
+							nullable: true,
+							schema: z.string()
+						},
+						{
+							name: "freight-inbound",
+							jsonPath: ["freightInbound"],
+							description: "The shipping cost to receive one unit, a cost component",
+							valueName: "value",
+							nullable: true,
+							schema: z.string()
+						},
+						{
+							name: "freight-outbound",
+							jsonPath: ["freightOutbound"],
+							description: "The shipping cost to deploy one unit, a deployment cost component",
+							valueName: "value",
+							nullable: true,
+							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",
+							nullable: true,
+							schema: z.string()
+						},
+						{
+							name: "installation",
+							jsonPath: ["installation"],
+							description: "The cost to install one unit, a deployment cost component",
+							valueName: "value",
+							nullable: true,
+							schema: z.string()
+						},
+						{
+							name: "interest",
+							jsonPath: ["interest"],
+							description: "The financing cost of one unit, a cost component",
+							valueName: "value",
+							nullable: true,
+							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",
+							negatable: true,
+							nullable: true,
+							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",
+							nullable: 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",
+							nullable: true,
+							schema: z.string()
+						},
+						{
+							name: "tariffs",
+							jsonPath: ["tariffs"],
+							description: "The import duty paid on one unit, a cost component",
+							valueName: "value",
+							nullable: true,
+							schema: z.string()
+						},
+						{
+							name: "tax",
+							jsonPath: ["tax"],
+							description: "The tax paid on one unit, a cost component",
+							valueName: "value",
+							nullable: true,
+							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",
+							nullable: true,
+							schema: z.coerce.number().int()
+						}
+					]
 				}), {
 					name: "in-service-management",
 					summary: "In service management commands",
@@ -1578,6 +2886,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: [{
@@ -1586,7 +2895,14 @@ const surfaceCommands = [
 							required: true
 						}],
 						queryFlags: [],
-						takesBody: true
+						bodyFlags: [{
+							name: "automatic",
+							jsonPath: ["automatic"],
+							description: "Whether Hardfin sets the asset's in-service date itself",
+							negatable: true,
+							required: true,
+							schema: z.boolean()
+						}]
 					})]
 				}]
 			},
@@ -1599,6 +2915,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: [{
@@ -1607,7 +2924,58 @@ 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: toEnum(["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",
+							nullable: true,
+							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: toEnum([
+								"ADDITION",
+								"BETTERMENT",
+								"DAMAGE",
+								"INSTALLATION",
+								"LIFE_EXTENSION",
+								"MARKET_DECLINE",
+								"OBSOLESCENCE",
+								"OTHER",
+								"REGULATORY"
+							])
+						}
+					]
 				})]
 			},
 			{
@@ -1619,6 +2987,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: [{
@@ -1627,7 +2996,7 @@ const surfaceCommands = [
 						required: true
 					}],
 					queryFlags: [],
-					takesBody: false
+					bodyFlags: []
 				})]
 			},
 			{
@@ -1639,6 +3008,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: [{
@@ -1659,10 +3029,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: [{
@@ -1675,7 +3046,7 @@ const surfaceCommands = [
 						required: true
 					}],
 					queryFlags: [],
-					takesBody: false
+					bodyFlags: []
 				})]
 			},
 			{
@@ -1687,6 +3058,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: [{
@@ -1695,10 +3067,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: [{
@@ -1711,7 +3084,7 @@ const surfaceCommands = [
 						required: true
 					}],
 					queryFlags: [],
-					takesBody: false
+					bodyFlags: []
 				})]
 			},
 			{
@@ -1723,6 +3096,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: [{
@@ -1731,7 +3105,7 @@ const surfaceCommands = [
 						required: true
 					}],
 					queryFlags: [],
-					takesBody: false
+					bodyFlags: []
 				})]
 			},
 			{
@@ -1744,6 +3118,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: [{
@@ -1752,11 +3127,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 <uuid> --date <value>",
 						method: "POST",
 						path: "/asset/{assetKey}/ownership",
 						pathParameters: [{
@@ -1765,11 +3141,37 @@ 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: "uuid",
+								required: true,
+								schema: z.uuid()
+							},
+							{
+								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",
+								nullable: true,
+								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: [{
@@ -1778,11 +3180,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: [{
@@ -1795,11 +3205,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: [{
@@ -1812,11 +3223,37 @@ 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: "uuid",
+								nullable: true,
+								schema: z.uuid()
+							},
+							{
+								name: "date",
+								jsonPath: ["date"],
+								description: "The day the segment's owner took ownership, which cannot be in the future",
+								valueName: "value",
+								nullable: true,
+								schema: z.string()
+							},
+							{
+								name: "sale-price",
+								jsonPath: ["salePrice"],
+								description: "What the owner paid for the asset, which cannot be negative",
+								valueName: "value",
+								nullable: true,
+								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: [{
@@ -1829,7 +3266,7 @@ const surfaceCommands = [
 							required: true
 						}],
 						queryFlags: [],
-						takesBody: false
+						bodyFlags: []
 					})
 				]
 			},
@@ -1842,6 +3279,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: [{
@@ -1850,7 +3288,32 @@ 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",
+							nullable: true,
+							schema: z.string()
+						},
+						{
+							name: "disposal-reason",
+							jsonPath: ["disposalReason"],
+							description: "Why the asset was scrapped",
+							valueName: "value",
+							nullable: true,
+							schema: z.string()
+						}
+					]
 				})]
 			},
 			{
@@ -1862,6 +3325,7 @@ const surfaceCommands = [
 				subcommands: [defineOperation({
 					name: "create",
 					summary: "Unscrap asset",
+					example: "hardfin asset unscrap create ast_4f9xk2mq7plr8stz",
 					method: "POST",
 					path: "/asset/{assetKey}/unscrap",
 					pathParameters: [{
@@ -1870,7 +3334,7 @@ const surfaceCommands = [
 						required: true
 					}],
 					queryFlags: [],
-					takesBody: false
+					bodyFlags: []
 				})]
 			},
 			{
@@ -1882,6 +3346,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: [{
@@ -1890,10 +3355,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: [{
@@ -1902,7 +3368,21 @@ 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",
+						nullable: true,
+						schema: z.string()
+					}, {
+						name: "url",
+						jsonPath: ["url"],
+						description: "The address the link points to",
+						valueName: "value",
+						required: true,
+						schema: z.string()
+					}]
 				})]
 			},
 			{
@@ -1914,6 +3394,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: [{
@@ -1922,7 +3403,48 @@ 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",
+							nullable: true,
+							schema: z.string()
+						},
+						{
+							name: "reason",
+							jsonPath: ["reason"],
+							description: "Why the useful life was revised",
+							valueName: "value",
+							required: true,
+							schema: toEnum([
+								"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().int()
+						}
+					]
 				})]
 			}
 		]
@@ -1937,6 +3459,7 @@ const surfaceCommands = [
 			defineOperation({
 				name: "list",
 				summary: "Get customers",
+				example: "hardfin customer list --limit 10",
 				method: "GET",
 				path: "/customer",
 				pathParameters: [],
@@ -1946,14 +3469,14 @@ const surfaceCommands = [
 						queryName: "page",
 						description: "The page to return, starting at 1",
 						valueName: "number",
-						schema: z.coerce.number()
+						schema: z.coerce.number().int()
 					},
 					{
 						name: "limit",
 						queryName: "limit",
 						description: "The number of records per page, from 1 to 100",
 						valueName: "number",
-						schema: z.coerce.number()
+						schema: z.coerce.number().int().min(1).max(100)
 					},
 					{
 						name: "sort-by",
@@ -1967,14 +3490,14 @@ const surfaceCommands = [
 						queryName: "sortOrder",
 						description: "The sort direction",
 						valueName: "value",
-						schema: z.enum(["ASC", "DESC"])
+						schema: toEnum(["ASC", "DESC"])
 					},
 					{
 						name: "archived",
 						queryName: "archived",
 						description: "Whether to return unarchived records, archived records, or all of them",
 						valueName: "value",
-						schema: z.enum([
+						schema: toEnum([
 							"all",
 							"false",
 							"true"
@@ -2008,20 +3531,101 @@ 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",
+						nullable: true,
+						schema: z.string()
+					},
+					{
+						name: "billing-contact-email",
+						jsonPath: ["billingContact", "email"],
+						description: "The billing contact's email address",
+						valueName: "value",
+						nullable: true,
+						schema: z.string()
+					},
+					{
+						name: "billing-contact-name",
+						jsonPath: ["billingContact", "name"],
+						description: "The billing contact's name",
+						valueName: "value",
+						nullable: true,
+						schema: z.string()
+					},
+					{
+						name: "billing-contact-phone",
+						jsonPath: ["billingContact", "phone"],
+						description: "The billing contact's phone number",
+						valueName: "value",
+						nullable: true,
+						schema: z.string()
+					},
+					{
+						name: "comment",
+						jsonPath: ["comment"],
+						description: "A free-form note about the customer",
+						valueName: "value",
+						nullable: true,
+						schema: z.string()
+					},
+					{
+						name: "domain",
+						jsonPath: ["domain"],
+						description: "The customer's web domain, used to look up its logo",
+						valueName: "value",
+						nullable: true,
+						schema: z.string()
+					},
+					{
+						name: "external-id",
+						jsonPath: ["externalId"],
+						description: "The customer's identifier in another system",
+						valueName: "value",
+						nullable: true,
+						schema: z.string()
+					},
+					{
+						name: "is-customer",
+						jsonPath: ["isCustomer"],
+						description: "Whether the company is a customer",
+						negatable: true,
+						schema: z.boolean()
+					},
+					{
+						name: "is-supplier",
+						jsonPath: ["isSupplier"],
+						description: "Whether the company is a supplier",
+						negatable: true,
+						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: [{
@@ -2030,11 +3634,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: [{
@@ -2043,7 +3648,96 @@ const surfaceCommands = [
 					required: true
 				}],
 				queryFlags: [],
-				takesBody: true
+				bodyFlags: [
+					{
+						name: "billing-address",
+						jsonPath: ["billingAddress"],
+						description: "The address invoices are sent to",
+						valueName: "value",
+						nullable: true,
+						schema: z.string()
+					},
+					{
+						name: "billing-contact-email",
+						jsonPath: ["billingContact", "email"],
+						description: "The billing contact's email address",
+						valueName: "value",
+						nullable: true,
+						schema: z.string()
+					},
+					{
+						name: "billing-contact-name",
+						jsonPath: ["billingContact", "name"],
+						description: "The billing contact's name",
+						valueName: "value",
+						nullable: true,
+						schema: z.string()
+					},
+					{
+						name: "billing-contact-phone",
+						jsonPath: ["billingContact", "phone"],
+						description: "The billing contact's phone number",
+						valueName: "value",
+						nullable: true,
+						schema: z.string()
+					},
+					{
+						name: "comment",
+						jsonPath: ["comment"],
+						description: "A free-form note about the customer",
+						valueName: "value",
+						nullable: true,
+						schema: z.string()
+					},
+					{
+						name: "domain",
+						jsonPath: ["domain"],
+						description: "The customer's web domain, used to look up its logo",
+						valueName: "value",
+						nullable: true,
+						schema: z.string()
+					},
+					{
+						name: "external-id",
+						jsonPath: ["externalId"],
+						description: "The customer's identifier in another system",
+						valueName: "value",
+						nullable: true,
+						schema: z.string()
+					},
+					{
+						name: "is-archived",
+						jsonPath: ["isArchived"],
+						description: "Whether the customer is archived",
+						negatable: true,
+						nullable: true,
+						schema: z.boolean()
+					},
+					{
+						name: "is-customer",
+						jsonPath: ["isCustomer"],
+						description: "Whether the company is a customer",
+						negatable: true,
+						nullable: true,
+						schema: z.boolean()
+					},
+					{
+						name: "is-supplier",
+						jsonPath: ["isSupplier"],
+						description: "Whether the company is a supplier",
+						negatable: true,
+						nullable: true,
+						schema: z.boolean()
+					},
+					{
+						name: "name",
+						jsonPath: ["name"],
+						description: "The customer's display name",
+						valueName: "value",
+						nullable: true,
+						schema: z.string()
+					}
+				]
 			})
 		]
 	},
@@ -2056,14 +3750,43 @@ const surfaceCommands = [
 		subcommands: [defineOperation({
 			name: "create",
 			summary: "Upload file",
+			example: "hardfin file create --file-type <value> --for-entity <uuid> --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: "uuid",
+						required: true,
+						schema: z.uuid()
+					},
+					{
+						name: "is-public",
+						jsonPath: ["isPublic"],
+						description: "Whether any organization's API key may download the file, which is false unless sent as true",
+						schema: z.boolean()
+					}
+				]
+			}
 		}), defineOperation({
 			name: "get",
 			summary: "Get file",
+			example: "hardfin file get file_7hq2mx9pkr4stz8w",
 			method: "GET",
 			path: "/file/{fileKey}",
 			pathParameters: [{
@@ -2077,7 +3800,8 @@ const surfaceCommands = [
 				description: "True when the file downloads as an attachment rather than opening inline",
 				schema: z.boolean()
 			}],
-			takesBody: false
+			bodyFlags: [],
+			downloads: true
 		})]
 	},
 	{
@@ -2090,6 +3814,7 @@ const surfaceCommands = [
 			defineOperation({
 				name: "list",
 				summary: "Get items",
+				example: "hardfin item list --limit 10",
 				method: "GET",
 				path: "/item",
 				pathParameters: [],
@@ -2099,7 +3824,7 @@ const surfaceCommands = [
 						queryName: "type",
 						description: "The item type to list, SERVICE, DEVICE, or BULK, or absent for every type",
 						valueName: "value",
-						schema: z.enum([
+						schema: toEnum([
 							"BULK",
 							"DEVICE",
 							"SERVICE"
@@ -2117,21 +3842,21 @@ const surfaceCommands = [
 						queryName: "page",
 						description: "The page to return, starting at 1",
 						valueName: "number",
-						schema: z.coerce.number()
+						schema: z.coerce.number().int()
 					},
 					{
 						name: "limit",
 						queryName: "limit",
 						description: "The number of records per page, from 1 to 100",
 						valueName: "number",
-						schema: z.coerce.number()
+						schema: z.coerce.number().int().min(1).max(100)
 					},
 					{
 						name: "sort-by",
 						queryName: "sortBy",
 						description: "The field to sort by",
 						valueName: "value",
-						schema: z.enum([
+						schema: toEnum([
 							"name",
 							"sku",
 							"type",
@@ -2143,14 +3868,14 @@ const surfaceCommands = [
 						queryName: "sortOrder",
 						description: "The sort direction",
 						valueName: "value",
-						schema: z.enum(["ASC", "DESC"])
+						schema: toEnum(["ASC", "DESC"])
 					},
 					{
 						name: "archived",
 						queryName: "archived",
 						description: "Whether to return unarchived records, archived records, or all of them",
 						valueName: "value",
-						schema: z.enum([
+						schema: toEnum([
 							"all",
 							"false",
 							"true"
@@ -2164,20 +3889,131 @@ 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",
+						negatable: true,
+						schema: z.boolean()
+					},
+					{
+						name: "description",
+						jsonPath: ["description"],
+						description: "A free-form description of the item",
+						valueName: "value",
+						nullable: true,
+						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: toEnum([
+							"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: toEnum([
+							"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: [{
@@ -2186,11 +4022,12 @@ const surfaceCommands = [
 					required: true
 				}],
 				queryFlags: [],
-				takesBody: false
+				bodyFlags: []
 			}),
 			defineOperation({
 				name: "update",
 				summary: "Update item",
+				example: "hardfin item update item_7Hq2Lm9XcR4tWz8K --field fieldId=<value>,order=<value>,section=<value>",
 				method: "PATCH",
 				path: "/item/{itemKey}",
 				pathParameters: [{
@@ -2199,7 +4036,73 @@ 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",
+						negatable: true,
+						nullable: true,
+						schema: z.boolean()
+					},
+					{
+						name: "description",
+						jsonPath: ["description"],
+						description: "The item's new description, or null to clear it",
+						valueName: "value",
+						nullable: true,
+						schema: z.string()
+					},
+					{
+						name: "field",
+						jsonPath: ["fields"],
+						description: "New positions for a DEVICE item's fields",
+						valueName: "fieldId=,order=,section=",
+						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",
+						negatable: true,
+						nullable: true,
+						schema: z.boolean()
+					},
+					{
+						name: "name",
+						jsonPath: ["name"],
+						description: "The item's new display name, which cannot be empty",
+						valueName: "value",
+						nullable: true,
+						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",
+						nullable: true,
+						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",
+						nullable: true,
+						schema: toEnum([
+							"BULK",
+							"DEVICE",
+							"SERVICE"
+						])
+					}
+				]
 			}),
 			{
 				name: "accounting",
@@ -2210,6 +4113,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: [{
@@ -2218,7 +4122,116 @@ 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",
+							nullable: true,
+							schema: z.string()
+						},
+						{
+							name: "bill-of-materials",
+							jsonPath: ["billOfMaterials"],
+							description: "The parts cost of one unit, a cost component",
+							valueName: "value",
+							nullable: true,
+							schema: z.string()
+						},
+						{
+							name: "depreciation-model",
+							jsonPath: ["depreciationModel"],
+							description: "The method one unit is depreciated by, or null to clear it",
+							valueName: "value",
+							schema: toEnum([
+								"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",
+							nullable: true,
+							schema: z.string()
+						},
+						{
+							name: "freight-inbound",
+							jsonPath: ["freightInbound"],
+							description: "The shipping cost to receive one unit, a cost component",
+							valueName: "value",
+							nullable: true,
+							schema: z.string()
+						},
+						{
+							name: "freight-outbound",
+							jsonPath: ["freightOutbound"],
+							description: "The shipping cost to deploy one unit, a deployment cost component",
+							valueName: "value",
+							nullable: true,
+							schema: z.string()
+						},
+						{
+							name: "installation",
+							jsonPath: ["installation"],
+							description: "The cost to install one unit, a deployment cost component",
+							valueName: "value",
+							nullable: true,
+							schema: z.string()
+						},
+						{
+							name: "interest",
+							jsonPath: ["interest"],
+							description: "The financing cost of one unit, a cost component",
+							valueName: "value",
+							nullable: true,
+							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",
+							nullable: 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",
+							nullable: true,
+							schema: z.string()
+						},
+						{
+							name: "tariffs",
+							jsonPath: ["tariffs"],
+							description: "The import duty paid on one unit, a cost component",
+							valueName: "value",
+							nullable: true,
+							schema: z.string()
+						},
+						{
+							name: "tax",
+							jsonPath: ["tax"],
+							description: "The tax paid on one unit, a cost component",
+							valueName: "value",
+							nullable: true,
+							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",
+							nullable: true,
+							schema: z.coerce.number().int()
+						}
+					]
 				})]
 			},
 			{
@@ -2231,6 +4244,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: [{
@@ -2239,11 +4253,56 @@ 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: toEnum([
+									"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,
+								nullable: true,
+								schema: z.coerce.number().int()
+							},
+							{
+								name: "section",
+								jsonPath: ["section"],
+								description: "The group the field is shown in, starting at 0",
+								valueName: "number",
+								required: true,
+								nullable: true,
+								schema: z.coerce.number().int()
+							}
+						]
 					}),
 					defineOperation({
 						name: "update",
 						summary: "Update item field",
+						example: "hardfin item field update item_7Hq2Lm9XcR4tWz8K pfield_2wn8kq4lxp7rtz3m",
 						method: "PATCH",
 						path: "/item/{itemKey}/field/{fieldKey}",
 						pathParameters: [{
@@ -2256,11 +4315,19 @@ 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",
+							nullable: true,
+							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: [{
@@ -2273,7 +4340,7 @@ const surfaceCommands = [
 							required: true
 						}],
 						queryFlags: [],
-						takesBody: false
+						bodyFlags: []
 					})
 				]
 			}
@@ -2289,6 +4356,7 @@ const surfaceCommands = [
 			defineOperation({
 				name: "list",
 				summary: "Get location listing",
+				example: "hardfin location list --limit 10",
 				method: "GET",
 				path: "/location",
 				pathParameters: [],
@@ -2298,21 +4366,21 @@ const surfaceCommands = [
 						queryName: "page",
 						description: "The page to return, starting at 1",
 						valueName: "number",
-						schema: z.coerce.number()
+						schema: z.coerce.number().int()
 					},
 					{
 						name: "limit",
 						queryName: "limit",
 						description: "The number of records per page, from 1 to 100",
 						valueName: "number",
-						schema: z.coerce.number()
+						schema: z.coerce.number().int().min(1).max(100)
 					},
 					{
 						name: "sort-by",
 						queryName: "sortBy",
 						description: "The field to sort by",
 						valueName: "value",
-						schema: z.enum([
+						schema: toEnum([
 							"name",
 							"company",
 							"assetCount"
@@ -2323,14 +4391,14 @@ const surfaceCommands = [
 						queryName: "sortOrder",
 						description: "The sort direction",
 						valueName: "value",
-						schema: z.enum(["ASC", "DESC"])
+						schema: toEnum(["ASC", "DESC"])
 					},
 					{
 						name: "archived",
 						queryName: "archived",
 						description: "Whether to return unarchived records, archived records, or all of them",
 						valueName: "value",
-						schema: z.enum([
+						schema: toEnum([
 							"all",
 							"false",
 							"true"
@@ -2341,7 +4409,7 @@ const surfaceCommands = [
 						queryName: "isTransient",
 						description: "Whether to return permanent locations (false), transient locations (true), or both (all)",
 						valueName: "value",
-						schema: z.enum([
+						schema: toEnum([
 							"all",
 							"false",
 							"true"
@@ -2377,20 +4445,150 @@ 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",
+						nullable: true,
+						schema: z.string()
+					},
+					{
+						name: "address-line2",
+						jsonPath: ["address", "addressLine2"],
+						description: "The second line of the street address, such as a suite",
+						valueName: "value",
+						nullable: true,
+						schema: z.string()
+					},
+					{
+						name: "address-city",
+						jsonPath: ["address", "city"],
+						description: "The city",
+						valueName: "value",
+						nullable: true,
+						schema: z.string()
+					},
+					{
+						name: "address-country",
+						jsonPath: ["address", "country"],
+						description: "The country",
+						valueName: "value",
+						nullable: true,
+						schema: z.string()
+					},
+					{
+						name: "address-formatted-address",
+						jsonPath: ["address", "formattedAddress"],
+						description: "The whole address on one line",
+						valueName: "value",
+						nullable: true,
+						schema: z.string()
+					},
+					{
+						name: "address-postal-code",
+						jsonPath: ["address", "postalCode"],
+						description: "The postal or ZIP code",
+						valueName: "value",
+						nullable: true,
+						schema: z.string()
+					},
+					{
+						name: "address-state",
+						jsonPath: ["address", "state"],
+						description: "The state or region",
+						valueName: "value",
+						nullable: true,
+						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: "uuid",
+						nullable: true,
+						schema: z.uuid()
+					},
+					{
+						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: "uuid",
+						nullable: true,
+						schema: z.uuid()
+					},
+					{
+						name: "description",
+						jsonPath: ["description"],
+						description: "A free-form description of a zone",
+						valueName: "value",
+						nullable: true,
+						schema: z.string()
+					},
+					{
+						name: "is-inventory",
+						jsonPath: ["isInventory"],
+						description: "Whether assets at the location count as inventory for reporting",
+						negatable: true,
+						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",
+						negatable: true,
+						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",
+						negatable: true,
+						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: "uuid",
+						nullable: true,
+						schema: z.uuid()
+					},
+					{
+						name: "type",
+						jsonPath: ["type"],
+						description: "SITE for a site, or ZONE for a zone within a site",
+						valueName: "value",
+						schema: toEnum([
+							"SITE",
+							"UNKNOWN",
+							"ZONE"
+						])
+					}
+				]
 			}),
 			defineOperation({
 				name: "get",
 				summary: "Get location",
+				example: "hardfin location get loc_4f9Xk2mQ7pLr8sTz",
 				method: "GET",
 				path: "/location/{locationKey}",
 				pathParameters: [{
@@ -2399,11 +4597,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: [{
@@ -2412,7 +4611,139 @@ const surfaceCommands = [
 					required: true
 				}],
 				queryFlags: [],
-				takesBody: true
+				bodyFlags: [
+					{
+						name: "address-line1",
+						jsonPath: ["address", "addressLine1"],
+						description: "The first line of the street address",
+						valueName: "value",
+						nullable: true,
+						schema: z.string()
+					},
+					{
+						name: "address-line2",
+						jsonPath: ["address", "addressLine2"],
+						description: "The second line of the street address, such as a suite",
+						valueName: "value",
+						nullable: true,
+						schema: z.string()
+					},
+					{
+						name: "address-city",
+						jsonPath: ["address", "city"],
+						description: "The city",
+						valueName: "value",
+						nullable: true,
+						schema: z.string()
+					},
+					{
+						name: "address-country",
+						jsonPath: ["address", "country"],
+						description: "The country",
+						valueName: "value",
+						nullable: true,
+						schema: z.string()
+					},
+					{
+						name: "address-formatted-address",
+						jsonPath: ["address", "formattedAddress"],
+						description: "The whole address on one line",
+						valueName: "value",
+						nullable: true,
+						schema: z.string()
+					},
+					{
+						name: "address-postal-code",
+						jsonPath: ["address", "postalCode"],
+						description: "The postal or ZIP code",
+						valueName: "value",
+						nullable: true,
+						schema: z.string()
+					},
+					{
+						name: "address-state",
+						jsonPath: ["address", "state"],
+						description: "The state or region",
+						valueName: "value",
+						nullable: true,
+						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: "uuid",
+						nullable: true,
+						schema: z.uuid()
+					},
+					{
+						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: "uuid",
+						nullable: true,
+						schema: z.uuid()
+					},
+					{
+						name: "description",
+						jsonPath: ["description"],
+						description: "A free-form description of a zone",
+						valueName: "value",
+						nullable: true,
+						schema: z.string()
+					},
+					{
+						name: "is-archived",
+						jsonPath: ["isArchived"],
+						description: "Whether the location is archived, and archiving a site archives its zones",
+						negatable: true,
+						nullable: true,
+						schema: z.boolean()
+					},
+					{
+						name: "is-inventory",
+						jsonPath: ["isInventory"],
+						description: "Whether assets at the location count as inventory for reporting",
+						negatable: true,
+						nullable: true,
+						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",
+						negatable: true,
+						nullable: true,
+						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",
+						negatable: true,
+						nullable: true,
+						schema: z.boolean()
+					},
+					{
+						name: "name",
+						jsonPath: ["name"],
+						description: "The location's display name",
+						valueName: "value",
+						nullable: true,
+						schema: z.string()
+					},
+					{
+						name: "type",
+						jsonPath: ["type"],
+						description: "SITE for a site, or ZONE for a zone within a site",
+						valueName: "value",
+						schema: toEnum([
+							"SITE",
+							"UNKNOWN",
+							"ZONE"
+						])
+					}
+				]
 			}),
 			{
 				name: "zones",
@@ -2423,6 +4754,7 @@ const surfaceCommands = [
 				subcommands: [defineOperation({
 					name: "list",
 					summary: "Get zones",
+					example: "hardfin location zones list loc_4f9Xk2mQ7pLr8sTz",
 					method: "GET",
 					path: "/location/{locationKey}/zones",
 					pathParameters: [{
@@ -2435,17 +4767,34 @@ const surfaceCommands = [
 						queryName: "archived",
 						description: "Whether to return unarchived zones, archived zones, or all of them",
 						valueName: "value",
-						schema: z.enum([
+						schema: toEnum([
 							"all",
 							"false",
 							"true"
 						])
 					}],
-					takesBody: false
+					bodyFlags: []
 				})]
 			}
 		]
 	},
+	{
+		name: "token",
+		summary: "Token commands",
+		arguments: [],
+		flags: [],
+		examples: [],
+		subcommands: [defineOperation({
+			name: "get",
+			summary: "Report the credential this CLI is calling with",
+			example: "hardfin token get",
+			method: "GET",
+			path: "/token",
+			pathParameters: [],
+			queryFlags: [],
+			bodyFlags: []
+		})]
+	},
 	{
 		name: "url-link",
 		summary: "URL link commands",
@@ -2456,6 +4805,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: [{
@@ -2464,11 +4814,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: [{
@@ -2477,11 +4828,26 @@ 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",
+					nullable: true,
+					schema: z.string()
+				}, {
+					name: "url",
+					jsonPath: ["url"],
+					description: "The address the link points to, which cannot be empty or null",
+					valueName: "value",
+					nullable: true,
+					schema: z.string()
+				}]
 			}),
 			defineOperation({
 				name: "delete",
 				summary: "Delete URL link",
+				example: "hardfin url-link delete link_7hq2mx9pcr4stz8w",
 				method: "DELETE",
 				path: "/url-link/{linkKey}",
 				pathParameters: [{
@@ -2490,38 +4856,12 @@ const surfaceCommands = [
 					required: true
 				}],
 				queryFlags: [],
-				takesBody: false
+				bodyFlags: []
 			})
 		]
 	}
 ];
 //#endregion
-//#region src/auth/jwt.ts
-/**
-* toClaims reads an access token's payload for display. Nothing here verifies the
-* signature, because the API is what decides whether a token is good.
-*/
-function toClaims(token) {
-	const payload = token.split(".")[1];
-	if (!payload) return {};
-	try {
-		const decoded = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
-		return {
-			expiresAt: typeof decoded["exp"] === "number" ? decoded["exp"] * 1e3 : void 0,
-			issuedAt: typeof decoded["iat"] === "number" ? decoded["iat"] * 1e3 : void 0,
-			scopes: toScopes(decoded),
-			subject: typeof decoded["sub"] === "string" ? decoded["sub"] : void 0
-		};
-	} catch {
-		return {};
-	}
-}
-/** toScopes reads scp, which is where Hardfin puts an access token's scopes. */
-function toScopes(decoded) {
-	if (Array.isArray(decoded["scp"])) return decoded["scp"].map(String);
-	return typeof decoded["scope"] === "string" ? decoded["scope"].split(" ") : void 0;
-}
-//#endregion
 //#region src/system/host.ts
 const BYTES_PER_GB = 1024 ** 3;
 /** toDistribution reads the name a Linux distribution gives itself. */
@@ -2565,8 +4905,8 @@ function toFile(path) {
 //#endregion
 //#region src/command/status.ts
 /**
-* Hardfin expires an unused refresh token after this long. It is the server's rule, not the
-* CLI's, and the token endpoint reports no expiry, so what this produces is an estimate.
+* What the CLI falls back to for an older sign in, stored before the server began reporting
+* when a refresh token expires. Hardfin's own rule, and an estimate rather than a fact.
 */
 const REFRESH_SLIDING_DAYS = 90;
 const statusCommand = defineCommand({
@@ -2629,27 +4969,24 @@ function toEnvironmentReport() {
 		apiVersion: API_VERSION,
 		node: process.version,
 		platform: process.platform,
-		interactive: Boolean(process.stdin.isTTY)
+		interactive: process.stdin.isTTY
 	};
 }
 /** toConfigurationReport names every setting, its source, and never a secret's value. */
 function toConfigurationReport(resolved) {
-	const entries = Object.entries(resolved.settings).map(([key, value]) => {
+	const report = { configFile: CONFIG_FILE };
+	for (const [key, value] of Object.entries(resolved.settings)) {
 		const from = resolved.sources[key];
-		if (key === "apiKey") return [key, {
+		report[key] = key === "apiKey" ? {
 			set: value !== void 0,
 			fingerprint: toFingerprint(value),
 			from
-		}];
-		return [key, {
+		} : {
 			value: value ?? null,
 			from
-		}];
-	});
-	return {
-		...Object.fromEntries(entries),
-		configFile: CONFIG_FILE
-	};
+		};
+	}
+	return report;
 }
 function toCredentialReport(apiKey, stored) {
 	if (apiKey) return {
@@ -2670,8 +5007,8 @@ function toCredentialReport(apiKey, stored) {
 		fingerprint: toFingerprint(stored.refreshToken),
 		signedInAt: stored.signedInAt ?? null,
 		renewedAt: stored.renewedAt ?? null,
-		refreshExpiresAt: toRefreshExpiry(stored.renewedAt),
-		refreshExpiryIsEstimated: true
+		refreshExpiresAt: stored.expiresAt ?? toRefreshExpiry(stored.renewedAt),
+		refreshExpiryIsEstimated: stored.expiresAt === void 0
 	};
 }
 function toServerReport(metadata) {
@@ -2745,8 +5082,7 @@ function toFlattened(value) {
 	if (value === null || typeof value !== "object" || Array.isArray(value)) return;
 	const holder = value;
 	if (holder.from === void 0) return;
-	const shown = holder.value ?? (holder.set ? holder.fingerprint ?? "set" : "not set");
-	return `${String(shown)}  (${holder.from})`;
+	return `${toText(holder.value ?? (holder.set ? holder.fingerprint ?? "set" : "not set"))}  (${holder.from})`;
 }
 /** toLines lays the report out for a person, one indented line per value. */
 function toLines(report, depth = 0) {
@@ -2776,7 +5112,10 @@ const commands = [
 	...surfaceCommands,
 	apiCommand,
 	configCommand,
-	agentGuideCommand
+	agentGuideCommand,
+	completionCommand,
+	mcpCommand,
+	completeCommand
 ];
 //#endregion
 //#region src/command/validate.ts
@@ -2789,13 +5128,16 @@ function toRejectedFlag(command, flags) {
 	}
 }
 //#endregion
-//#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));
-await program.parseAsync(process.argv);
+//#region src/cli/program.ts
+/** toCli builds the parser from the registry, which is what every surface reads. */
+function toCli(entries = commands) {
+	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 entries) program.addCommand(toProgram(program, command), { hidden: command.hidden });
+	return program;
+}
 /** toProgram wires one registry command into the parser. */
-function toProgram(command) {
+function toProgram(root, command) {
 	const program = new Command(command.name).summary(command.summary).description(command.description ?? command.summary);
 	for (const argument of command.arguments) {
 		const name = argument.variadic ? `${argument.name}...` : argument.name;
@@ -2805,21 +5147,22 @@ function toProgram(command) {
 		const short = flag.short ? `-${flag.short}, ` : "";
 		const value = flag.valueName ? ` <${flag.valueName}>` : "";
 		const option = new Option(`${short}--${flag.name}${value}`, flag.description);
+		if (flag.negatable) program.addOption(new Option(`--no-${flag.name}`, `${flag.description}, turned off`));
 		if (flag.repeatable) option.argParser(collect);
 		if (flag.defaultValue !== void 0) option.default(flag.defaultValue);
 		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(root, subcommand), { hidden: subcommand.hidden });
 	if (!command.run) return program;
 	program.action(async (...parsed) => {
 		const flags = parsed[parsed.length - 2] ?? {};
 		const args = parsed.slice(0, parsed.length - 2).flatMap(toArgumentList);
-		process.exitCode = await toExitCode(command, args, flags);
+		process.exitCode = await toExitCode(root, command, args, flags);
 	});
 	return program;
 }
-async function toExitCode(command, args, flags) {
+async function toExitCode(root, command, args, flags) {
 	const isJSON = isJSONOutput(flags);
 	const rejected = toRejectedFlag(command, flags);
 	if (rejected) {
@@ -2828,8 +5171,8 @@ async function toExitCode(command, args, flags) {
 	}
 	try {
 		const resolved = toSettings({
-			apiUrl: program.opts()["apiUrl"],
-			issuerUrl: program.opts()["issuerUrl"]
+			apiUrl: root.opts()["apiUrl"],
+			issuerUrl: root.opts()["issuerUrl"]
 		});
 		return await command.run?.({
 			args,
@@ -2845,10 +5188,17 @@ async function toExitCode(command, args, flags) {
 }
 function toArgumentList(value) {
 	if (Array.isArray(value)) return value.map(String);
-	return value === void 0 ? [] : [String(value)];
+	return value === void 0 ? [] : [toText(value)];
 }
 function collect(value, previous) {
 	return [...previous ?? [], value];
 }
 //#endregion
+//#region src/cli.ts
+process.stdout.on("error", (error) => {
+	if (error.code === "EPIPE") process.exit(0);
+	throw error;
+});
+await toCli().parseAsync(process.argv);
+//#endregion
 export {};