@hardfin/cli 0.0.2-dev.5 → 0.0.2-dev.7

package/dist/cli.js

@@ -2,7 +2,8 @@
 import { createRequire } from "node:module";
 import { Command, Option } from "commander";
 import { z } from "zod";
-import { readFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
 //#region src/command/registry.ts
 /** ExitCode is what the process returns, and what an agent branches on. */
 const ExitCode = {
@@ -19,14 +20,93 @@ function defineCommand(command) {
 //#region src/config/settings.ts
 /** The API version this build was written against, sent on every request. */
 const API_VERSION = "2026-09-17";
+/** The file a local build reads its overrides from, in the working directory. */
+const CONFIG_FILE = "config.local.json";
 const DEFAULT_API_URL = "https://api.hardfin.com/v2";
-/** toApiUrl picks the API this invocation talks to. */
-function toApiUrl(override) {
-	return (override ?? process.env["HARDFIN_API_URL"] ?? DEFAULT_API_URL).replace(/\/+$/, "");
+const DEFAULT_ENV_FILE = ".env";
+const FileSettings = z.strictObject({
+	apiUrl: z.string().optional(),
+	apiKey: z.string().optional(),
+	clientId: z.string().optional(),
+	auth: z.strictObject({
+		authorizeUrl: z.string().optional(),
+		tokenUrl: z.string().optional(),
+		deviceUrl: z.string().optional(),
+		revokeUrl: z.string().optional()
+	}).optional()
+});
+/** ConfigFailure is a config file that cannot be read or does not match the schema. */
+var ConfigFailure = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "ConfigFailure";
+	}
+};
+/** toSettings resolves what this invocation talks to, and where each value came from. */
+function toSettings(flags = {}, directory = process.cwd()) {
+	const fromEnvFile = loadEnvFile(directory);
+	const file = toFileSettings(directory);
+	const sources = {};
+	const pick = (key, flag, variable, fromFile, fallback) => {
+		const [value, source] = toLayer(flag, process.env[variable], fromEnvFile.has(variable), fromFile, fallback);
+		sources[key] = source;
+		return value;
+	};
+	const apiUrl = toTrimmedUrl(pick("apiUrl", flags.apiUrl, "HARDFIN_API_URL", file.apiUrl, DEFAULT_API_URL) ?? DEFAULT_API_URL);
+	return {
+		settings: {
+			apiUrl,
+			apiKey: pick("apiKey", flags.apiKey, "HARDFIN_API_KEY", file.apiKey),
+			clientId: pick("clientId", flags.clientId, "HARDFIN_CLIENT_ID", file.clientId),
+			authorizeUrl: pick("authorizeUrl", flags.authorizeUrl, "HARDFIN_AUTHORIZE_URL", file.auth?.authorizeUrl, `${apiUrl}/auth/authorize`) ?? "",
+			tokenUrl: pick("tokenUrl", flags.tokenUrl, "HARDFIN_TOKEN_URL", file.auth?.tokenUrl, `${apiUrl}/auth/token`) ?? "",
+			deviceUrl: pick("deviceUrl", flags.deviceUrl, "HARDFIN_DEVICE_URL", file.auth?.deviceUrl, `${apiUrl}/auth/device`) ?? "",
+			revokeUrl: pick("revokeUrl", flags.revokeUrl, "HARDFIN_REVOKE_URL", file.auth?.revokeUrl, `${apiUrl}/auth/revoke`) ?? ""
+		},
+		sources
+	};
+}
+function toLayer(flag, environment, isFromEnvFile, file, fallback) {
+	if (flag) return [flag, "flag"];
+	if (environment) return [environment, isFromEnvFile ? "env file" : "environment"];
+	if (file) return [file, "config file"];
+	return [fallback, "default"];
+}
+/** toFileSettings reads the local override file, which a local build is expected to have. */
+function toFileSettings(directory) {
+	const path = resolve(directory, CONFIG_FILE);
+	if (!existsSync(path)) return {};
+	let parsed;
+	try {
+		parsed = JSON.parse(readFileSync(path, "utf8"));
+	} catch {
+		throw new ConfigFailure(`${CONFIG_FILE} does not hold JSON`);
+	}
+	const result = FileSettings.safeParse(parsed);
+	if (!result.success) {
+		const issue = result.error.issues[0];
+		throw new ConfigFailure(`${CONFIG_FILE} is not valid: ${issue?.path.join(".") || "root"} ${issue?.message ?? ""}`.trim());
+	}
+	return result.data;
 }
-/** toApiKey reads the API key an unattended caller set. */
-function toApiKey() {
-	return process.env["HARDFIN_API_KEY"] || void 0;
+/**
+* loadEnvFile reads a .env beside the command, so a local build needs no exports, and
+* answers which variables it supplied. Node leaves an exported variable alone, so a
+* shell export still wins over the file.
+*/
+function loadEnvFile(directory) {
+	const path = process.env["HARDFIN_ENV_FILE"] ?? resolve(directory, DEFAULT_ENV_FILE);
+	if (!existsSync(path)) return /* @__PURE__ */ new Set();
+	const before = new Set(Object.keys(process.env));
+	try {
+		process.loadEnvFile(path);
+	} catch {
+		throw new ConfigFailure(`${path} cannot be read as an env file`);
+	}
+	return new Set(Object.keys(process.env).filter((name) => !before.has(name)));
+}
+function toTrimmedUrl(url) {
+	return url.replace(/\/+$/, "");
 }
 //#endregion
 //#region src/output/writer.ts
@@ -272,7 +352,7 @@ const apiCommand = defineCommand({
 	run: runApi
 });
 async function runApi(input) {
-	const apiKey = toApiKey();
+	const apiKey = input.resolved.settings.apiKey;
 	if (!apiKey) {
 		writeFailure("not authenticated. Set HARDFIN_API_KEY to an API key for your organization", input.isJSON);
 		return ExitCode.NOT_AUTHENTICATED;
@@ -282,14 +362,14 @@ async function runApi(input) {
 		writeFailure("a path is required, such as /customer", input.isJSON);
 		return ExitCode.USAGE;
 	}
-	const query = toQuery(input.flags["field"]);
+	const query = toQuery$1(input.flags["field"]);
 	if (query === void 0) {
 		writeFailure("each --field is key=value, such as -f limit=50", input.isJSON);
 		return ExitCode.USAGE;
 	}
 	let body;
 	if (typeof input.flags["input"] === "string") {
-		body = toBody(input.flags["input"]);
+		body = toBody$1(input.flags["input"]);
 		if (body === void 0) {
 			writeFailure(`${input.flags["input"]} does not hold JSON`, input.isJSON);
 			return ExitCode.USAGE;
@@ -297,7 +377,7 @@ async function runApi(input) {
 	}
 	try {
 		writeData((await request({
-			apiUrl: toApiUrl(),
+			apiUrl: input.resolved.settings.apiUrl,
 			apiKey,
 			method: String(input.flags["method"] ?? "GET").toUpperCase(),
 			path,
@@ -315,7 +395,7 @@ async function runApi(input) {
 	}
 }
 /** toQuery folds the repeated --field flags into query parameters. */
-function toQuery(fields) {
+function toQuery$1(fields) {
 	const query = new URLSearchParams();
 	for (const field of Array.isArray(fields) ? fields : []) {
 		const split = field.indexOf("=");
@@ -324,6 +404,150 @@ function toQuery(fields) {
 	}
 	return query;
 }
+function toBody$1(source) {
+	const text = source === "-" ? readFileSync(0, "utf8") : readFileSync(source, "utf8");
+	try {
+		return JSON.parse(text);
+	} catch {
+		return;
+	}
+}
+//#endregion
+//#region src/command/config.ts
+const configCommand = defineCommand({
+	name: "config",
+	summary: "Print what this invocation talks to, and where each value came from",
+	description: `Resolves the API and authentication endpoints from the flags, the environment, a .env file, and ${CONFIG_FILE} in the working directory. Use it when a local build reaches the wrong server.`,
+	arguments: [],
+	flags: [{
+		name: "json",
+		description: "Print machine-readable output, which is the default when stdout is not a terminal",
+		schema: z.boolean()
+	}],
+	examples: [{
+		description: "See what a local build is pointed at",
+		command: "hardfin config"
+	}, {
+		description: "Read one value from a script",
+		command: "hardfin config --json | jq -r .apiUrl"
+	}],
+	run: runConfig
+});
+/** toReport pairs each setting with the layer that supplied it. */
+function toReport(resolved) {
+	const report = { apiVersion: API_VERSION };
+	for (const [key, value] of Object.entries(resolved.settings)) {
+		const source = resolved.sources[key];
+		report[key] = key === "apiKey" ? {
+			set: value !== void 0,
+			from: source
+		} : {
+			value: value ?? null,
+			from: source
+		};
+	}
+	return report;
+}
+async function runConfig(input) {
+	const report = toReport(input.resolved);
+	if (input.isJSON) {
+		writeData(report);
+		return ExitCode.OK;
+	}
+	writeData(Object.entries(report).map(([key, entry]) => {
+		if (typeof entry !== "object" || entry === null) return `${key.padEnd(14)} ${String(entry)}`;
+		const holder = entry;
+		const shown = holder.value ?? (holder.set ? "set" : "not set");
+		return `${key.padEnd(14)} ${shown}  (${holder.from})`;
+	}).join("\n"));
+	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",
+	schema: z.string()
+};
+const JSON_FLAG = {
+	name: "json",
+	description: "Print machine-readable output, which is the default when stdout is not a terminal",
+	schema: z.boolean()
+};
+/** 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);
+	return {
+		name: operation.name,
+		summary: operation.summary,
+		description: operation.description ?? operation.summary,
+		arguments: operation.pathParameters,
+		flags,
+		examples: [],
+		run: (input) => runOperation(operation, input)
+	};
+}
+async function runOperation(operation, input) {
+	const apiKey = input.resolved.settings.apiKey;
+	if (!apiKey) {
+		writeFailure("not authenticated. Set HARDFIN_API_KEY to an API key for your organization", input.isJSON);
+		return ExitCode.NOT_AUTHENTICATED;
+	}
+	const path = toPath(operation, input.args);
+	if (path === void 0) {
+		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);
+			return ExitCode.USAGE;
+		}
+	}
+	try {
+		writeData((await request({
+			apiUrl: input.resolved.settings.apiUrl,
+			apiKey,
+			method: operation.method,
+			path,
+			query: toQuery(operation, input.flags),
+			body
+		})).data);
+		return ExitCode.OK;
+	} catch (error) {
+		if (error instanceof RequestFailure) {
+			writeFailure(error.message, input.isJSON, error.errors, error.requestId);
+			return error.status === 401 ? ExitCode.NOT_AUTHENTICATED : ExitCode.ERROR;
+		}
+		writeFailure(error instanceof Error ? error.message : String(error), input.isJSON);
+		return ExitCode.ERROR;
+	}
+}
+/** toPath fills the path template from the positional arguments, in order. */
+function toPath(operation, args) {
+	if (args.length !== operation.pathParameters.length) return;
+	let path = operation.path;
+	for (const [index, parameter] of operation.pathParameters.entries()) path = path.replace(`{${parameter.name}}`, encodeURIComponent(args[index] ?? ""));
+	return path;
+}
+/** toQuery carries only the flags this invocation actually set. */
+function toQuery(operation, flags) {
+	const query = new URLSearchParams();
+	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));
+	}
+	return query;
+}
+/** toOptionKey names the parsed flag, which the parser reports in camel case. */
+function toOptionKey(name) {
+	return name.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+}
 function toBody(source) {
 	const text = source === "-" ? readFileSync(0, "utf8") : readFileSync(source, "utf8");
 	try {
@@ -335,11 +559,1073 @@ function toBody(source) {
 //#endregion
 //#region src/command/commands.ts
 /** commands is every command the CLI offers, and drives help and the agent guide. */
-const commands = [apiCommand, agentGuideCommand];
+const commands = [
+	...[
+		{
+			name: "asset",
+			summary: "Asset commands",
+			arguments: [],
+			flags: [],
+			examples: [],
+			subcommands: [
+				defineOperation({
+					name: "list",
+					summary: "Get asset listing",
+					method: "GET",
+					path: "/asset",
+					pathParameters: [],
+					queryFlags: [
+						{
+							name: "page",
+							queryName: "page",
+							description: "The page to return, starting at 1",
+							valueName: "number",
+							schema: z.coerce.number()
+						},
+						{
+							name: "limit",
+							queryName: "limit",
+							description: "The number of records per page, from 1 to 100",
+							valueName: "number",
+							schema: z.coerce.number()
+						},
+						{
+							name: "sort-by",
+							queryName: "sortBy",
+							description: "The field to sort by",
+							valueName: "value",
+							schema: z.enum([
+								"serial",
+								"project",
+								"item",
+								"location",
+								"owner",
+								"activity"
+							])
+						},
+						{
+							name: "sort-order",
+							queryName: "sortOrder",
+							description: "The sort direction",
+							valueName: "value",
+							schema: z.enum(["ASC", "DESC"])
+						},
+						{
+							name: "archived",
+							queryName: "archived",
+							description: "Whether to return unarchived records, archived records, or all of them",
+							valueName: "value",
+							schema: z.enum([
+								"all",
+								"false",
+								"true"
+							])
+						},
+						{
+							name: "search-query",
+							queryName: "searchQuery",
+							description: "Text to match against the serial, description, item, project, owner, and location, ignored when shorter than three characters",
+							valueName: "value",
+							schema: z.string()
+						},
+						{
+							name: "for-asset-id",
+							queryName: "forAssetId",
+							description: "The IDs of the assets to list",
+							valueName: "value",
+							repeatable: true,
+							schema: z.array(z.string())
+						},
+						{
+							name: "for-asset-key",
+							queryName: "forAssetKey",
+							description: "The keys of the assets to list",
+							valueName: "value",
+							repeatable: true,
+							schema: z.array(z.string())
+						},
+						{
+							name: "for-customer",
+							queryName: "forCustomer",
+							description: "The IDs of the customers whose assets to list",
+							valueName: "value",
+							repeatable: true,
+							schema: z.array(z.string())
+						},
+						{
+							name: "for-item",
+							queryName: "forItem",
+							description: "The IDs of the items whose assets to list",
+							valueName: "value",
+							repeatable: true,
+							schema: z.array(z.string())
+						},
+						{
+							name: "at-site",
+							queryName: "atSite",
+							description: "The IDs of the locations whose assets to list",
+							valueName: "value",
+							repeatable: true,
+							schema: z.array(z.string())
+						},
+						{
+							name: "at-customer-sites",
+							queryName: "atCustomerSites",
+							description: "The IDs of the customers whose sites to list assets at",
+							valueName: "value",
+							repeatable: true,
+							schema: z.array(z.string())
+						},
+						{
+							name: "with-functional-statuses",
+							queryName: "withFunctionalStatuses",
+							description: "The functional statuses to list, where SCRAPPED lists scrapped assets",
+							valueName: "value",
+							repeatable: true,
+							schema: z.array(z.enum([
+								"FUNCTIONAL",
+								"NEEDS_REVIEW",
+								"NON-FUNCTIONAL",
+								"SCRAPPED"
+							]))
+						},
+						{
+							name: "with-transit-statuses",
+							queryName: "withTransitStatuses",
+							description: "The transit statuses to list",
+							valueName: "value",
+							repeatable: true,
+							schema: z.array(z.enum([
+								"IN_TRANSIT",
+								"IN_TRANSIT_TO_FIELD",
+								"IN_TRANSIT_TO_INVENTORY",
+								"NOT_IN_TRANSIT"
+							]))
+						},
+						{
+							name: "with-inventory-statuses",
+							queryName: "withInventoryStatuses",
+							description: "In_inventory, not_in_inventory, or both, which filters only when one is sent",
+							valueName: "value",
+							repeatable: true,
+							schema: z.array(z.string())
+						},
+						{
+							name: "with-location-company-type",
+							queryName: "withLocationCompanyType",
+							description: "Customer, manufacturer, or both, for assets at customer sites or your own, which filters only when one is sent",
+							valueName: "value",
+							repeatable: true,
+							schema: z.array(z.string())
+						},
+						{
+							name: "with-project-status",
+							queryName: "withProjectStatus",
+							description: "The project assignments to list: upcoming, active, past, or none",
+							valueName: "value",
+							repeatable: true,
+							schema: z.array(z.string())
+						},
+						{
+							name: "with-owner",
+							queryName: "withOwner",
+							description: "Manufacturer for assets your organization owns, customer for assets customers own, or both",
+							valueName: "value",
+							repeatable: true,
+							schema: z.array(z.string())
+						},
+						{
+							name: "for-project",
+							queryName: "forProject",
+							description: "The IDs of the projects whose assets to list",
+							valueName: "value",
+							repeatable: true,
+							schema: z.array(z.string())
+						},
+						{
+							name: "scrapped",
+							queryName: "scrapped",
+							description: "Whether to list unscrapped assets, scrapped assets, or all of them",
+							valueName: "value",
+							schema: z.enum([
+								"all",
+								"false",
+								"true"
+							])
+						}
+					],
+					takesBody: false
+				}),
+				defineOperation({
+					name: "create",
+					summary: "Create asset",
+					method: "POST",
+					path: "/asset",
+					pathParameters: [],
+					queryFlags: [],
+					takesBody: true
+				}),
+				defineOperation({
+					name: "get",
+					summary: "Get asset",
+					method: "GET",
+					path: "/asset/{assetKey}",
+					pathParameters: [{
+						name: "assetKey",
+						description: "The asset's key",
+						required: true
+					}],
+					queryFlags: [],
+					takesBody: false
+				}),
+				defineOperation({
+					name: "update",
+					summary: "Patch asset",
+					method: "PATCH",
+					path: "/asset/{assetKey}",
+					pathParameters: [{
+						name: "assetKey",
+						description: "The asset's key",
+						required: true
+					}],
+					queryFlags: [],
+					takesBody: true
+				}),
+				{
+					name: "accounting",
+					summary: "Accounting commands",
+					arguments: [],
+					flags: [],
+					examples: [],
+					subcommands: [defineOperation({
+						name: "update",
+						summary: "Update asset accounting",
+						method: "PATCH",
+						path: "/asset/{assetKey}/accounting",
+						pathParameters: [{
+							name: "assetKey",
+							description: "The asset's key",
+							required: true
+						}],
+						queryFlags: [],
+						takesBody: true
+					}), {
+						name: "in-service-management",
+						summary: "In service management commands",
+						arguments: [],
+						flags: [],
+						examples: [],
+						subcommands: [defineOperation({
+							name: "update",
+							summary: "Toggle in service date management",
+							method: "PATCH",
+							path: "/asset/{assetKey}/accounting/in-service-management",
+							pathParameters: [{
+								name: "assetKey",
+								description: "The asset's key",
+								required: true
+							}],
+							queryFlags: [],
+							takesBody: true
+						})]
+					}]
+				},
+				{
+					name: "cost-adjustment",
+					summary: "Cost adjustment commands",
+					arguments: [],
+					flags: [],
+					examples: [],
+					subcommands: [defineOperation({
+						name: "create",
+						summary: "Create asset cost adjustment",
+						method: "POST",
+						path: "/asset/{assetKey}/cost-adjustment",
+						pathParameters: [{
+							name: "assetKey",
+							description: "The asset's key",
+							required: true
+						}],
+						queryFlags: [],
+						takesBody: true
+					})]
+				},
+				{
+					name: "file",
+					summary: "File commands",
+					arguments: [],
+					flags: [],
+					examples: [],
+					subcommands: [defineOperation({
+						name: "list",
+						summary: "Get asset files",
+						method: "GET",
+						path: "/asset/{assetKey}/file",
+						pathParameters: [{
+							name: "assetKey",
+							description: "The asset's key",
+							required: true
+						}],
+						queryFlags: [],
+						takesBody: false
+					}), defineOperation({
+						name: "delete",
+						summary: "Delete asset file",
+						method: "DELETE",
+						path: "/asset/{assetKey}/file/{fileKey}",
+						pathParameters: [{
+							name: "assetKey",
+							description: "The asset's key",
+							required: true
+						}, {
+							name: "fileKey",
+							description: "The file's key",
+							required: true
+						}],
+						queryFlags: [],
+						takesBody: false
+					})]
+				},
+				{
+					name: "ownership",
+					summary: "Ownership commands",
+					arguments: [],
+					flags: [],
+					examples: [],
+					subcommands: [
+						defineOperation({
+							name: "list",
+							summary: "Get asset ownership history",
+							method: "GET",
+							path: "/asset/{assetKey}/ownership",
+							pathParameters: [{
+								name: "assetKey",
+								description: "The asset's key",
+								required: true
+							}],
+							queryFlags: [],
+							takesBody: false
+						}),
+						defineOperation({
+							name: "create",
+							summary: "Create asset ownership",
+							method: "POST",
+							path: "/asset/{assetKey}/ownership",
+							pathParameters: [{
+								name: "assetKey",
+								description: "The asset's key",
+								required: true
+							}],
+							queryFlags: [],
+							takesBody: true
+						}),
+						defineOperation({
+							name: "clear",
+							summary: "Clear the ownership an asset holds today",
+							method: "DELETE",
+							path: "/asset/{assetKey}/ownership",
+							pathParameters: [{
+								name: "assetKey",
+								description: "The asset's key",
+								required: true
+							}],
+							queryFlags: [],
+							takesBody: true
+						}),
+						defineOperation({
+							name: "get",
+							summary: "Get asset ownership segment",
+							method: "GET",
+							path: "/asset/{assetKey}/ownership/{segmentKey}",
+							pathParameters: [{
+								name: "assetKey",
+								description: "The asset's key",
+								required: true
+							}, {
+								name: "segmentKey",
+								description: "The ownership segment's key",
+								required: true
+							}],
+							queryFlags: [],
+							takesBody: false
+						}),
+						defineOperation({
+							name: "update",
+							summary: "Patch asset ownership segment",
+							method: "PATCH",
+							path: "/asset/{assetKey}/ownership/{segmentKey}",
+							pathParameters: [{
+								name: "assetKey",
+								description: "The asset's key",
+								required: true
+							}, {
+								name: "segmentKey",
+								description: "The ownership segment's key",
+								required: true
+							}],
+							queryFlags: [],
+							takesBody: true
+						}),
+						defineOperation({
+							name: "delete",
+							summary: "Delete asset ownership segment",
+							method: "DELETE",
+							path: "/asset/{assetKey}/ownership/{segmentKey}",
+							pathParameters: [{
+								name: "assetKey",
+								description: "The asset's key",
+								required: true
+							}, {
+								name: "segmentKey",
+								description: "The ownership segment's key",
+								required: true
+							}],
+							queryFlags: [],
+							takesBody: false
+						})
+					]
+				},
+				{
+					name: "url-link",
+					summary: "URL link commands",
+					arguments: [],
+					flags: [],
+					examples: [],
+					subcommands: [defineOperation({
+						name: "list",
+						summary: "Get asset URL links",
+						method: "GET",
+						path: "/asset/{assetKey}/url-link",
+						pathParameters: [{
+							name: "assetKey",
+							description: "The asset's key",
+							required: true
+						}],
+						queryFlags: [],
+						takesBody: false
+					}), defineOperation({
+						name: "create",
+						summary: "Create asset URL link",
+						method: "POST",
+						path: "/asset/{assetKey}/url-link",
+						pathParameters: [{
+							name: "assetKey",
+							description: "The asset's key",
+							required: true
+						}],
+						queryFlags: [],
+						takesBody: true
+					})]
+				},
+				{
+					name: "useful-life-revision",
+					summary: "Useful life revision commands",
+					arguments: [],
+					flags: [],
+					examples: [],
+					subcommands: [defineOperation({
+						name: "create",
+						summary: "Create asset useful life revision",
+						method: "POST",
+						path: "/asset/{assetKey}/useful-life-revision",
+						pathParameters: [{
+							name: "assetKey",
+							description: "The asset's key",
+							required: true
+						}],
+						queryFlags: [],
+						takesBody: true
+					})]
+				}
+			]
+		},
+		{
+			name: "customer",
+			summary: "Customer commands",
+			arguments: [],
+			flags: [],
+			examples: [],
+			subcommands: [
+				defineOperation({
+					name: "list",
+					summary: "Get customers",
+					method: "GET",
+					path: "/customer",
+					pathParameters: [],
+					queryFlags: [
+						{
+							name: "page",
+							queryName: "page",
+							description: "The page to return, starting at 1",
+							valueName: "number",
+							schema: z.coerce.number()
+						},
+						{
+							name: "limit",
+							queryName: "limit",
+							description: "The number of records per page, from 1 to 100",
+							valueName: "number",
+							schema: z.coerce.number()
+						},
+						{
+							name: "sort-by",
+							queryName: "sortBy",
+							description: "The field to sort by",
+							valueName: "value",
+							schema: z.string()
+						},
+						{
+							name: "sort-order",
+							queryName: "sortOrder",
+							description: "The sort direction",
+							valueName: "value",
+							schema: z.enum(["ASC", "DESC"])
+						},
+						{
+							name: "archived",
+							queryName: "archived",
+							description: "Whether to return unarchived records, archived records, or all of them",
+							valueName: "value",
+							schema: z.enum([
+								"all",
+								"false",
+								"true"
+							])
+						},
+						{
+							name: "is-customer",
+							queryName: "isCustomer",
+							description: "True to return only customers, or false to return only non-customers",
+							schema: z.boolean()
+						},
+						{
+							name: "is-supplier",
+							queryName: "isSupplier",
+							description: "True to return only suppliers, or false to return only non-suppliers",
+							schema: z.boolean()
+						},
+						{
+							name: "sync-statuses",
+							queryName: "syncStatuses",
+							description: "The CRM sync statuses to return: in-sync, out-of-sync, or not-linked",
+							valueName: "value",
+							repeatable: true,
+							schema: z.array(z.string())
+						},
+						{
+							name: "search",
+							queryName: "search",
+							description: "Text to match against customer names",
+							valueName: "value",
+							schema: z.string()
+						}
+					],
+					takesBody: false
+				}),
+				defineOperation({
+					name: "create",
+					summary: "Create customer",
+					method: "POST",
+					path: "/customer",
+					pathParameters: [],
+					queryFlags: [],
+					takesBody: true
+				}),
+				defineOperation({
+					name: "get",
+					summary: "Get customer",
+					method: "GET",
+					path: "/customer/{customerKey}",
+					pathParameters: [{
+						name: "customerKey",
+						description: "The customer's key",
+						required: true
+					}],
+					queryFlags: [],
+					takesBody: false
+				}),
+				defineOperation({
+					name: "update",
+					summary: "Patch customer",
+					method: "PATCH",
+					path: "/customer/{customerKey}",
+					pathParameters: [{
+						name: "customerKey",
+						description: "The customer's key",
+						required: true
+					}],
+					queryFlags: [],
+					takesBody: true
+				})
+			]
+		},
+		{
+			name: "file",
+			summary: "File commands",
+			arguments: [],
+			flags: [],
+			examples: [],
+			subcommands: [defineOperation({
+				name: "create",
+				summary: "Upload file",
+				method: "POST",
+				path: "/file",
+				pathParameters: [],
+				queryFlags: [],
+				takesBody: true
+			}), defineOperation({
+				name: "get",
+				summary: "Get file",
+				method: "GET",
+				path: "/file/{fileKey}",
+				pathParameters: [{
+					name: "fileKey",
+					description: "The file's key, and a public file is readable with any organization's API key while any other file is readable only with its own organization's",
+					required: true
+				}],
+				queryFlags: [{
+					name: "attachment",
+					queryName: "attachment",
+					description: "Present, with any value or none, when the file should download as an attachment rather than open inline",
+					valueName: "value",
+					schema: z.string()
+				}],
+				takesBody: false
+			})]
+		},
+		{
+			name: "item",
+			summary: "Item commands",
+			arguments: [],
+			flags: [],
+			examples: [],
+			subcommands: [
+				defineOperation({
+					name: "list",
+					summary: "Get items",
+					method: "GET",
+					path: "/item",
+					pathParameters: [],
+					queryFlags: [
+						{
+							name: "type",
+							queryName: "type",
+							description: "The item type to list, SERVICE, DEVICE, or BULK, or absent for every type",
+							valueName: "value",
+							schema: z.enum([
+								"BULK",
+								"DEVICE",
+								"SERVICE"
+							])
+						},
+						{
+							name: "search",
+							queryName: "search",
+							description: "Text to match against item names, SKUs, and descriptions, in any case",
+							valueName: "value",
+							schema: z.string()
+						},
+						{
+							name: "page",
+							queryName: "page",
+							description: "The page to return, starting at 1",
+							valueName: "number",
+							schema: z.coerce.number()
+						},
+						{
+							name: "limit",
+							queryName: "limit",
+							description: "The number of records per page, from 1 to 100",
+							valueName: "number",
+							schema: z.coerce.number()
+						},
+						{
+							name: "sort-by",
+							queryName: "sortBy",
+							description: "The field to sort by",
+							valueName: "value",
+							schema: z.enum([
+								"name",
+								"sku",
+								"type",
+								"lastUpdatedAt"
+							])
+						},
+						{
+							name: "sort-order",
+							queryName: "sortOrder",
+							description: "The sort direction",
+							valueName: "value",
+							schema: z.enum(["ASC", "DESC"])
+						},
+						{
+							name: "archived",
+							queryName: "archived",
+							description: "Whether to return unarchived records, archived records, or all of them",
+							valueName: "value",
+							schema: z.enum([
+								"all",
+								"false",
+								"true"
+							])
+						},
+						{
+							name: "exclude-linked-integration",
+							queryName: "excludeLinkedIntegration",
+							description: "An integration whose already-linked items to leave out",
+							valueName: "value",
+							schema: z.string()
+						}
+					],
+					takesBody: false
+				}),
+				defineOperation({
+					name: "create",
+					summary: "Create item",
+					method: "POST",
+					path: "/item",
+					pathParameters: [],
+					queryFlags: [],
+					takesBody: true
+				}),
+				defineOperation({
+					name: "get",
+					summary: "Get item",
+					method: "GET",
+					path: "/item/{itemKey}",
+					pathParameters: [{
+						name: "itemKey",
+						description: "The item's key",
+						required: true
+					}],
+					queryFlags: [],
+					takesBody: false
+				}),
+				defineOperation({
+					name: "update",
+					summary: "Update item",
+					method: "PATCH",
+					path: "/item/{itemKey}",
+					pathParameters: [{
+						name: "itemKey",
+						description: "The item's key",
+						required: true
+					}],
+					queryFlags: [],
+					takesBody: true
+				}),
+				{
+					name: "accounting",
+					summary: "Accounting commands",
+					arguments: [],
+					flags: [],
+					examples: [],
+					subcommands: [defineOperation({
+						name: "update",
+						summary: "Update item accounting",
+						method: "PATCH",
+						path: "/item/{itemKey}/accounting",
+						pathParameters: [{
+							name: "itemKey",
+							description: "The item's key",
+							required: true
+						}],
+						queryFlags: [],
+						takesBody: true
+					})]
+				},
+				{
+					name: "field",
+					summary: "Field commands",
+					arguments: [],
+					flags: [],
+					examples: [],
+					subcommands: [
+						defineOperation({
+							name: "create",
+							summary: "Create item field",
+							method: "POST",
+							path: "/item/{itemKey}/field",
+							pathParameters: [{
+								name: "itemKey",
+								description: "The item's key",
+								required: true
+							}],
+							queryFlags: [],
+							takesBody: true
+						}),
+						defineOperation({
+							name: "update",
+							summary: "Update item field",
+							method: "PATCH",
+							path: "/item/{itemKey}/field/{fieldKey}",
+							pathParameters: [{
+								name: "itemKey",
+								description: "The item's key",
+								required: true
+							}, {
+								name: "fieldKey",
+								description: "The field's key",
+								required: true
+							}],
+							queryFlags: [],
+							takesBody: true
+						}),
+						defineOperation({
+							name: "delete",
+							summary: "Delete item field",
+							method: "DELETE",
+							path: "/item/{itemKey}/field/{fieldKey}",
+							pathParameters: [{
+								name: "itemKey",
+								description: "The item's key",
+								required: true
+							}, {
+								name: "fieldKey",
+								description: "The field's key",
+								required: true
+							}],
+							queryFlags: [],
+							takesBody: false
+						})
+					]
+				}
+			]
+		},
+		{
+			name: "location",
+			summary: "Location commands",
+			arguments: [],
+			flags: [],
+			examples: [],
+			subcommands: [
+				defineOperation({
+					name: "list",
+					summary: "Get location listing",
+					method: "GET",
+					path: "/location",
+					pathParameters: [],
+					queryFlags: [
+						{
+							name: "page",
+							queryName: "page",
+							description: "The page to return, starting at 1",
+							valueName: "number",
+							schema: z.coerce.number()
+						},
+						{
+							name: "limit",
+							queryName: "limit",
+							description: "The number of records per page, from 1 to 100",
+							valueName: "number",
+							schema: z.coerce.number()
+						},
+						{
+							name: "sort-by",
+							queryName: "sortBy",
+							description: "The field to sort by",
+							valueName: "value",
+							schema: z.enum([
+								"name",
+								"company",
+								"assetCount"
+							])
+						},
+						{
+							name: "sort-order",
+							queryName: "sortOrder",
+							description: "The sort direction",
+							valueName: "value",
+							schema: z.enum(["ASC", "DESC"])
+						},
+						{
+							name: "archived",
+							queryName: "archived",
+							description: "Whether to return unarchived records, archived records, or all of them",
+							valueName: "value",
+							schema: z.enum([
+								"all",
+								"false",
+								"true"
+							])
+						},
+						{
+							name: "is-transient",
+							queryName: "isTransient",
+							description: "Whether to return permanent locations (false), transient locations (true), or both (all)",
+							valueName: "value",
+							schema: z.enum([
+								"all",
+								"false",
+								"true"
+							])
+						},
+						{
+							name: "search",
+							queryName: "search",
+							description: "Text to match against location and customer names",
+							valueName: "value",
+							schema: z.string()
+						},
+						{
+							name: "for-customer-ids",
+							queryName: "forCustomerIds",
+							description: "The IDs of the customers whose locations to return",
+							valueName: "value",
+							repeatable: true,
+							schema: z.array(z.string())
+						},
+						{
+							name: "include-organization",
+							queryName: "includeOrganization",
+							description: "Whether the customer filter also matches your organization's own locations, which on its own returns only those",
+							schema: z.boolean()
+						},
+						{
+							name: "sync-statuses",
+							queryName: "syncStatuses",
+							description: "The CRM sync statuses to return: in-sync, out-of-sync, or not-linked",
+							valueName: "value",
+							repeatable: true,
+							schema: z.array(z.string())
+						}
+					],
+					takesBody: false
+				}),
+				defineOperation({
+					name: "create",
+					summary: "Create location",
+					method: "POST",
+					path: "/location",
+					pathParameters: [],
+					queryFlags: [],
+					takesBody: true
+				}),
+				defineOperation({
+					name: "get",
+					summary: "Get location",
+					method: "GET",
+					path: "/location/{locationKey}",
+					pathParameters: [{
+						name: "locationKey",
+						description: "The location's key",
+						required: true
+					}],
+					queryFlags: [],
+					takesBody: false
+				}),
+				defineOperation({
+					name: "update",
+					summary: "Patch location",
+					method: "PATCH",
+					path: "/location/{locationKey}",
+					pathParameters: [{
+						name: "locationKey",
+						description: "The location's key",
+						required: true
+					}],
+					queryFlags: [],
+					takesBody: true
+				}),
+				{
+					name: "zones",
+					summary: "Zones commands",
+					arguments: [],
+					flags: [],
+					examples: [],
+					subcommands: [defineOperation({
+						name: "list",
+						summary: "Get zones",
+						method: "GET",
+						path: "/location/{locationKey}/zones",
+						pathParameters: [{
+							name: "locationKey",
+							description: "The key of the site whose zones to list",
+							required: true
+						}],
+						queryFlags: [{
+							name: "archived",
+							queryName: "archived",
+							description: "Whether to return unarchived zones, archived zones, or all of them",
+							valueName: "value",
+							schema: z.enum([
+								"all",
+								"false",
+								"true"
+							])
+						}],
+						takesBody: false
+					})]
+				}
+			]
+		},
+		{
+			name: "url-link",
+			summary: "URL link commands",
+			arguments: [],
+			flags: [],
+			examples: [],
+			subcommands: [
+				defineOperation({
+					name: "get",
+					summary: "Get URL link by key",
+					method: "GET",
+					path: "/url-link/{linkKey}",
+					pathParameters: [{
+						name: "linkKey",
+						description: "The URL link's key",
+						required: true
+					}],
+					queryFlags: [],
+					takesBody: false
+				}),
+				defineOperation({
+					name: "update",
+					summary: "Update URL link",
+					method: "PATCH",
+					path: "/url-link/{linkKey}",
+					pathParameters: [{
+						name: "linkKey",
+						description: "The URL link's key",
+						required: true
+					}],
+					queryFlags: [],
+					takesBody: true
+				}),
+				defineOperation({
+					name: "delete",
+					summary: "Delete URL link",
+					method: "DELETE",
+					path: "/url-link/{linkKey}",
+					pathParameters: [{
+						name: "linkKey",
+						description: "The URL link's key",
+						required: true
+					}],
+					queryFlags: [],
+					takesBody: false
+				})
+			]
+		}
+	],
+	apiCommand,
+	configCommand,
+	agentGuideCommand
+];
+//#endregion
+//#region src/command/validate.ts
+/** toRejectedFlag names the first flag whose value its schema refuses. */
+function toRejectedFlag(command, flags) {
+	for (const flag of command.flags) {
+		const value = flags[toOptionKey(flag.name)];
+		if (value === void 0) continue;
+		if (!flag.schema.safeParse(value).success) return `--${flag.name} does not accept ${JSON.stringify(value)}`;
+	}
+}
 //#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, "-v, --version").showHelpAfterError().enablePositionalOptions();
+program.name("hardfin").description("Call the Hardfin API from a terminal or an agent").version(version, "-v, --version").option("--api-url <url>", "The API to call, which also moves the authentication endpoints").showHelpAfterError().enablePositionalOptions();
 for (const command of commands) program.addCommand(toProgram(command));
 await program.parseAsync(process.argv);
 /** toProgram wires one registry command into the parser. */
@@ -358,6 +1644,8 @@ function toProgram(command) {
 		program.addOption(option);
 	}
 	for (const example of command.examples) program.addHelpText("after", `\n${example.description}:\n  $ ${example.command}`);
+	for (const subcommand of command.subcommands ?? []) program.addCommand(toProgram(subcommand));
+	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);
@@ -367,16 +1655,23 @@ function toProgram(command) {
 }
 async function toExitCode(command, args, flags) {
 	const isJSON = isJSONOutput(flags);
+	const rejected = toRejectedFlag(command, flags);
+	if (rejected) {
+		writeFailure(rejected, isJSON);
+		return ExitCode.USAGE;
+	}
 	try {
-		return await command.run({
+		const resolved = toSettings({ apiUrl: program.opts()["apiUrl"] });
+		return await command.run?.({
 			args,
 			flags,
 			isJSON,
-			commands
-		});
+			commands,
+			resolved
+		}) ?? ExitCode.OK;
 	} catch (error) {
 		writeFailure(error instanceof Error ? error.message : String(error), isJSON);
-		return ExitCode.ERROR;
+		return error instanceof ConfigFailure ? ExitCode.USAGE : ExitCode.ERROR;
 	}
 }
 function toArgumentList(value) {