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

package/README.md

@@ -7,7 +7,8 @@ It is built for people at a terminal and for agents that call Hardfin on their b
 
 ## Status
 
-This package is a placeholder that reserves the name. No commands work yet.
+The CLI is early. `hardfin api` and the generated commands work against an API key, and
+`hardfin login` is not built yet.
 
 ## Install
 
@@ -21,6 +22,69 @@ Previews of unreleased work are published from the `dev` branch.
 npm install -g @hardfin/cli@dev
 ```
 
+## The command surface
+
+Most commands are generated from the published API document rather than written by hand.
+
+| Piece | Holds |
+| --- | --- |
+| `hardfin api` | A call to any endpoint, written by hand, and the escape hatch when no generated command fits |
+| `src/command/surface.generated.ts` | Every endpoint as a command, rewritten by the generator |
+| `surface-overrides.json` | The operations whose generated name is wrong |
+| `scripts/generate-surface.mjs` | The generator |
+
+### How an endpoint becomes a command
+
+The first path segment is the noun. Every later literal segment nests under it. The method
+and the shape of the last segment decide the verb.
+
+| Endpoint | Command |
+| --- | --- |
+| `GET /asset` | `hardfin asset list` |
+| `POST /asset` | `hardfin asset create` |
+| `GET /asset/{assetKey}` | `hardfin asset get <assetKey>` |
+| `PATCH /asset/{assetKey}` | `hardfin asset update <assetKey>` |
+| `PATCH /asset/{assetKey}/accounting` | `hardfin asset accounting update <assetKey>` |
+
+A path parameter becomes a positional argument. A query parameter becomes a flag, named in
+kebab case, and an array parameter becomes a flag you repeat. An enum parameter carries its
+values, so a wrong value fails locally with exit code 2 rather than at the API.
+
+### Overrides
+
+Two endpoints sometimes want one name. `DELETE /asset/{assetKey}/ownership` and
+`DELETE /asset/{assetKey}/ownership/{segmentKey}` both generate `asset ownership delete`, so
+the generator stops and names the pair.
+
+Settle it in `surface-overrides.json`, keyed by `operationId`:
+
+```json
+{
+    "assetClearAssetActiveOwnership": {
+        "command": ["asset", "ownership", "clear"],
+        "summary": "Clear the ownership an asset holds today"
+    }
+}
+```
+
+An override for an `operationId` the document no longer publishes fails the generator. That
+is deliberate, because a silently dropped override renames a command nobody meant to rename.
+
+### Regenerating
+
+The Surface workflow runs each weekday, reads `reference/core.openapi.yaml` from the
+`hardfinhq/api-spec` repository through a read-only deploy key, and opens a pull request when
+the generated file changes. It needs the `API_SPEC_READ_DEPLOY_KEY` secret.
+
+Run it by hand against a local document:
+
+```sh
+npm run generate-surface -- ../api-spec/reference/core.openapi.yaml
+```
+
+The document is bundled, meaning its external files are inlined, but `$ref` pointers within
+it remain. The generator follows those pointers itself.
+
 ## Releasing
 
 This section is for anyone who merges a pull request in this repository. It tells you where

package/dist/cli.js

@@ -282,14 +282,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;
@@ -315,7 +315,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 +324,100 @@ 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/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 = toApiKey();
+	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: toApiUrl(),
+			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,7 +429,1068 @@ 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,
+	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();
@@ -358,6 +1513,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,13 +1524,18 @@ 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({
+		return await command.run?.({
 			args,
 			flags,
 			isJSON,
 			commands
-		});
+		}) ?? ExitCode.OK;
 	} catch (error) {
 		writeFailure(error instanceof Error ? error.message : String(error), isJSON);
 		return ExitCode.ERROR;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@hardfin/cli",
-    "version": "0.0.2-dev.5",
+    "version": "0.0.2-dev.6",
     "description": "Command line interface for the Hardfin API",
     "license": "Apache-2.0",
     "author": "Hardfin, Inc.",
@@ -33,6 +33,7 @@
     },
     "scripts": {
         "build": "tsdown",
+        "generate-surface": "node scripts/generate-surface.mjs",
         "check-types": "tsc --noEmit",
         "test": "vitest run",
         "test:watch": "vitest",
@@ -47,6 +48,7 @@
         "tsdown": "^0.23.0",
         "typescript": "^5.9.0",
         "unrun": "^0.3.1",
-        "vitest": "^5.0.1"
+        "vitest": "^5.0.1",
+        "yaml": "^2.9.1"
     }
 }