@hardfin/cli 0.1.0-dev.29 → 0.1.0-dev.30

package/README.md

@@ -87,6 +87,23 @@ Three things fail locally with exit code 2, before any request is made: a value
 enum, a required field that is missing, and `--unset` on a field the API will not take null
 for.
 
+### When a command fails
+
+A person at a terminal reads one plain line on stderr. Anything else reads JSON, also on
+stderr, so a pipe still carries only the result.
+
+| Field       | Holds                                                                    |
+| ----------- | ------------------------------------------------------------------------ |
+| `code`      | A fixed name for the failure, such as `not_found` or `missing_flag`      |
+| `message`   | The same plain sentence a person reads                                   |
+| `errors`    | Every error the API's envelope named, with its own numeric `statusCode`  |
+| `requestId` | The API's request ID, or null when the request never reached it          |
+| `status`    | The HTTP status, or null for a failure caught before any request is made |
+
+An agent branches on `code`. A code is never renamed and never changes meaning, while the
+message may be reworded at any time. `hardfin agent-guide` lists every code with what it
+means, and `src/output/failure.ts` defines them.
+
 ### Overrides
 
 Two endpoints sometimes want one name. `DELETE /asset/{assetKey}/ownership` and

package/dist/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="39e80611-82c5-527b-ac56-e34310ee122e")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="29560915-e7ae-5a74-b5f6-f4a6988e1b43")}catch(e){}}();
 import module from "node:module";
 //#region src/cli.ts
 module.enableCompileCache?.();
@@ -14,8 +14,14 @@ process.on("unhandledRejection", (error) => void toCrash(error));
 try {
 	const answer = await toQuickAnswer(process.argv.slice(2));
 	if (answer === void 0) {
-		const { toCli, wasReportAttempted } = await import("./program-CnXYN9xS.js");
-		await toCli().parseAsync(process.argv);
+		const { toCli, toParseExitCode, wasReportAttempted } = await import("./program-BZW_50HP.js");
+		try {
+			await toCli().parseAsync(process.argv);
+		} catch (error) {
+			const code = toParseExitCode(error, process.argv.slice(2));
+			if (code === void 0) throw error;
+			process.exitCode = code;
+		}
 		if (wasReportAttempted()) process.exit();
 	} else process.stdout.write(`${answer}\n`);
 } catch (error) {
@@ -27,7 +33,7 @@ async function toCrash(error) {
 	isCrashing = true;
 	process.stderr.write(`error: ${error instanceof Error ? error.message : String(error)}\n`);
 	try {
-		const { toReported } = await import("./program-CnXYN9xS.js");
+		const { toReported } = await import("./program-BZW_50HP.js");
 		await toReported(error, false, void 0, "fatal");
 	} finally {
 		process.exit(1);
@@ -45,4 +51,4 @@ async function toQuickAnswer(args) {
 export {};
 
 //# sourceMappingURL=cli.js.map
-//# debugId=39e80611-82c5-527b-ac56-e34310ee122e
+//# debugId=29560915-e7ae-5a74-b5f6-f4a6988e1b43

package/dist/{program-CnXYN9xS.js → program-BZW_50HP.js}

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="8979dc06-d236-502b-bea1-b13868301f52")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="5c189832-33ce-5032-b0e0-fc3a33cf5b1d")}catch(e){}}();
 import { a as defineCommand, i as GLOBAL_FLAGS, r as ExitCode, t as toInvocation } from "./scrub-VtQmxap1.js";
 import { n as toCompletion, t as toAnswer$1 } from "./completion-tree-rR_Rmeij.js";
 import { createRequire } from "node:module";
-import { Command, Option } from "commander";
+import { Command, CommanderError, Option } from "commander";
 import { z } from "zod";
 import { accessSync, chmodSync, closeSync, constants, existsSync, mkdirSync, openAsBlob, openSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, writeSync } from "node:fs";
 import { basename, delimiter, dirname, join, resolve } from "node:path";
@@ -144,152 +144,6 @@ 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, null, 2)}\n`);
-}
-/** writeFailure prints why a command failed on stderr, as text or as JSON. */
-function writeFailure(message, isJSON, errors, requestId, status) {
-	if (!isJSON) {
-		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;
-	}
-	const payload = {
-		errors: errors ?? [{
-			error: message,
-			statusCode: 0
-		}],
-		requestId: requestId ?? null,
-		status: status ?? null
-	};
-	process.stderr.write(`${JSON.stringify(payload, null, 2)}\n`);
-}
-/** isJSONOutput decides whether this invocation prints machine-readable output. */
-function isJSONOutput(flags) {
-	if (flags["json"] === true) return true;
-	return !process.stdout.isTTY;
-}
-/** version is what this build reports, read from the published package manifest. */
-const version$1 = createRequire(import.meta.url)("../package.json").version;
-//#endregion
-//#region src/command/agent-guide.ts
-const agentGuideCommand = defineCommand({
-	name: "agent-guide",
-	summary: "Print instructions an agent can follow to use this CLI",
-	description: "Writes Markdown describing every command, its flags, and its exit codes. Save it as a skill file, an AGENTS.md section, or paste it into a system prompt.",
-	arguments: [],
-	flags: [{
-		name: "json",
-		description: "Print the command registry as JSON instead of Markdown",
-		schema: z.boolean().optional()
-	}],
-	examples: [{
-		description: "Write a skill file",
-		command: "hardfin agent-guide > SKILL.md"
-	}, {
-		description: "Inspect the registry",
-		command: "hardfin agent-guide --json"
-	}],
-	run: runAgentGuide
-});
-/** toGuide renders the registry as the Markdown an agent reads. */
-function toGuide(commands, version) {
-	const lines = [
-		"# Hardfin CLI",
-		"",
-		`The \`hardfin\` command calls the Hardfin API. This guide describes version ${version} of the CLI, which speaks API version ${API_VERSION}.`,
-		"",
-		"## Before calling",
-		"",
-		"- Authenticate by setting `HARDFIN_API_KEY`, or by running `hardfin login`",
-		"- Every command prints JSON on stdout and diagnostics on stderr",
-		"- Output is JSON whenever stdout is not a terminal, so no flag is needed when calling from code",
-		"",
-		"## Exit codes",
-		"",
-		"| Code | Means |",
-		"| --- | --- |",
-		"| 0 | The command succeeded |",
-		"| 1 | The command failed |",
-		"| 2 | The command was called wrongly |",
-		"| 4 | No usable credential |",
-		"| 130 | The person pressed Ctrl-C |",
-		"",
-		"## Commands",
-		""
-	];
-	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} |`);
-		}
-		lines.push("");
-	}
-	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) {
-		writeData(input.commands.map(toSummary));
-		return ExitCode.OK;
-	}
-	writeData(toGuide(input.commands, version$1));
-	return ExitCode.OK;
-}
-function toSummary(command) {
-	return {
-		name: command.name,
-		summary: command.summary,
-		description: command.description ?? command.summary,
-		arguments: command.arguments,
-		flags: command.flags.map((flag) => ({
-			name: flag.name,
-			short: flag.short ?? null,
-			description: flag.description,
-			valueName: flag.valueName ?? null,
-			repeatable: flag.repeatable ?? false
-		})),
-		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
@@ -620,6 +474,51 @@ function keep(issuer, document) {
 	} catch {}
 }
 //#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, null, 2)}\n`);
+}
+/** writeFailure prints why a command failed on stderr, with a code only a machine reading JSON sees. */
+function writeFailure(code, message, isJSON, errors, requestId, status) {
+	if (!isJSON) {
+		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;
+	}
+	const payload = {
+		code,
+		message,
+		errors: errors ?? [{
+			error: message,
+			statusCode: 0
+		}],
+		requestId: requestId ?? null,
+		status: status ?? null
+	};
+	process.stderr.write(`${JSON.stringify(payload, null, 2)}\n`);
+}
+/** isJSONOutput decides whether this invocation prints machine-readable output. */
+function isJSONOutput(flags) {
+	if (flags["json"] === true) return true;
+	return !process.stdout.isTTY;
+}
+//#endregion
 //#region src/auth/grant.ts
 const TokenResponse = z.looseObject({
 	access_token: z.string(),
@@ -980,6 +879,172 @@ function toStatusMessage(status) {
 	if (status === 403) return "the organization is deactivated, or its access has ended";
 	return `the request failed with status ${status}`;
 }
+//#endregion
+//#region src/output/failure.ts
+/** FAILURE_CODES is every code a failure can carry, and none is ever renamed or given a new meaning. */
+const FAILURE_CODES = {
+	unknown_command: "No command has that name. Run hardfin --help for the list",
+	invalid_arguments: "The command was given the wrong positional arguments",
+	missing_flag: "A flag the command needs was not given",
+	invalid_flag: "A flag was given a value it does not take",
+	invalid_input: "A file the command was given cannot be read, or does not hold JSON",
+	empty_request: "The command would change nothing, because no field was given",
+	output_required: "The answer is a file, and needs --output or a pipe",
+	not_confirmed: "The change was not confirmed. Pass --yes to confirm it without a terminal",
+	shell_unavailable: "The shell did not say where its startup file is",
+	invalid_config: "A config file or setting cannot be read",
+	not_signed_in: "No usable credential. Run hardfin login, or set HARDFIN_API_KEY",
+	sign_in_failed: "Signing in did not finish",
+	unreachable: "The CLI could not connect to the server",
+	timed_out: "Something the CLI waited on took too long",
+	busy: "Another hardfin command is holding the credential lock",
+	bad_request: "The API refused the request as written (HTTP 400)",
+	unauthorized: "The API did not accept the credential (HTTP 401)",
+	forbidden: "The credential may not do this (HTTP 403)",
+	not_found: "The record or path does not exist (HTTP 404)",
+	conflict: "The request conflicts with the record's current state (HTTP 409)",
+	too_large: "The request is larger than the API accepts (HTTP 413)",
+	invalid_request: "The API could not process the request (HTTP 422)",
+	rate_limited: "Too many requests. Wait, then try again (HTTP 429)",
+	server_error: "The API failed to answer (HTTP 5xx)",
+	api_error: "The API refused the request with another status",
+	internal_error: "A problem in hardfin itself, which has been reported"
+};
+/** toStatusCode names a refusal by the HTTP status the API answered with. */
+function toStatusCode(status) {
+	switch (status) {
+		case 400: return "bad_request";
+		case 401: return "unauthorized";
+		case 403: return "forbidden";
+		case 404: return "not_found";
+		case 409: return "conflict";
+		case 413: return "too_large";
+		case 422: return "invalid_request";
+		case 429: return "rate_limited";
+		default: return status >= 500 ? "server_error" : "api_error";
+	}
+}
+/** toErrorCode names a failure nothing handled closer to where it happened. */
+function toErrorCode(error) {
+	if (error instanceof RequestFailure) return toStatusCode(error.status);
+	if (error instanceof NoCredential) return "not_signed_in";
+	if (error instanceof ConfigFailure) return "invalid_config";
+	if (error instanceof Unreachable) return "unreachable";
+	if (error instanceof TimedOut) return "timed_out";
+	if (error instanceof LockHeld) return "busy";
+	return "internal_error";
+}
+/** version is what this build reports, read from the published package manifest. */
+const version$1 = createRequire(import.meta.url)("../package.json").version;
+//#endregion
+//#region src/command/agent-guide.ts
+const agentGuideCommand = defineCommand({
+	name: "agent-guide",
+	summary: "Print instructions an agent can follow to use this CLI",
+	description: "Writes Markdown describing every command, its flags, and its exit codes. Save it as a skill file, an AGENTS.md section, or paste it into a system prompt.",
+	arguments: [],
+	flags: [{
+		name: "json",
+		description: "Print the command registry as JSON instead of Markdown",
+		schema: z.boolean().optional()
+	}],
+	examples: [{
+		description: "Write a skill file",
+		command: "hardfin agent-guide > SKILL.md"
+	}, {
+		description: "Inspect the registry",
+		command: "hardfin agent-guide --json"
+	}],
+	run: runAgentGuide
+});
+/** toGuide renders the registry as the Markdown an agent reads. */
+function toGuide(commands, version) {
+	const lines = [
+		"# Hardfin CLI",
+		"",
+		`The \`hardfin\` command calls the Hardfin API. This guide describes version ${version} of the CLI, which speaks API version ${API_VERSION}.`,
+		"",
+		"## Before calling",
+		"",
+		"- Authenticate by setting `HARDFIN_API_KEY`, or by running `hardfin login`",
+		"- Every command prints JSON on stdout and diagnostics on stderr",
+		"- Output is JSON whenever stdout is not a terminal, so no flag is needed when calling from code",
+		"",
+		"## Exit codes",
+		"",
+		"| Code | Means |",
+		"| --- | --- |",
+		"| 0 | The command succeeded |",
+		"| 1 | The command failed |",
+		"| 2 | The command was called wrongly |",
+		"| 4 | No usable credential |",
+		"| 130 | The person pressed Ctrl-C |",
+		"",
+		"## Error codes",
+		"",
+		"A failed command prints JSON on stderr with a `code`, a `message`, the API's `errors`, its `requestId` and the HTTP `status`. Branch on `code`, which never changes meaning. The message is for a person.",
+		"",
+		"| Code | Means |",
+		"| --- | --- |",
+		...Object.entries(FAILURE_CODES).map(([code, meaning]) => `| \`${code}\` | ${meaning} |`),
+		"",
+		"## Commands",
+		""
+	];
+	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} |`);
+		}
+		lines.push("");
+	}
+	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) {
+		writeData(input.commands.map(toSummary));
+		return ExitCode.OK;
+	}
+	writeData(toGuide(input.commands, version$1));
+	return ExitCode.OK;
+}
+function toSummary(command) {
+	return {
+		name: command.name,
+		summary: command.summary,
+		description: command.description ?? command.summary,
+		arguments: command.arguments,
+		flags: command.flags.map((flag) => ({
+			name: flag.name,
+			short: flag.short ?? null,
+			description: flag.description,
+			valueName: flag.valueName ?? null,
+			repeatable: flag.repeatable ?? false
+		})),
+		examples: command.examples,
+		subcommands: command.subcommands?.filter((entry) => !entry.hidden).map(toSummary)
+	};
+}
 const apiCommand = defineCommand({
 	name: "api",
 	summary: "Call a Hardfin API endpoint and print what it answers",
@@ -1043,23 +1108,23 @@ const apiCommand = defineCommand({
 async function runApi(input) {
 	const path = input.args[0];
 	if (!path) {
-		writeFailure("a path is required, such as /customer", input.isJSON);
+		writeFailure("invalid_arguments", "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);
+		writeFailure("invalid_arguments", "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);
+		writeFailure("invalid_flag", "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$1(input.flags["input"]);
 		if (body === void 0) {
-			writeFailure(`${input.flags["input"]} does not hold JSON`, input.isJSON);
+			writeFailure("invalid_input", `${input.flags["input"]} does not hold JSON`, input.isJSON);
 			return ExitCode.USAGE;
 		}
 	}
@@ -1075,11 +1140,11 @@ async function runApi(input) {
 		return ExitCode.OK;
 	} catch (error) {
 		if (error instanceof NoCredential) {
-			writeFailure(error.message, input.isJSON);
+			writeFailure("not_signed_in", error.message, input.isJSON);
 			return ExitCode.NOT_AUTHENTICATED;
 		}
 		if (error instanceof RequestFailure) {
-			writeFailure(error.message, input.isJSON, error.errors, error.requestId, error.status);
+			writeFailure(toStatusCode(error.status), error.message, input.isJSON, error.errors, error.requestId, error.status);
 			return error.status === 401 ? ExitCode.NOT_AUTHENTICATED : ExitCode.ERROR;
 		}
 		throw error;
@@ -1485,17 +1550,17 @@ async function runChange(input, change) {
 	const place = toPlace();
 	const shell = input.args[0] ?? toShell(place);
 	if (!shell || !SHELLS.includes(shell)) {
-		writeFailure(`name the shell to ${change} for: ${SHELLS.join(", ")}`, input.isJSON);
+		writeFailure("invalid_arguments", `name the shell to ${change} for: ${SHELLS.join(", ")}`, input.isJSON);
 		return ExitCode.USAGE;
 	}
 	const plan = toPlan(shell, place);
 	if (change === "install" && shell === "powershell" && !plan.startup) {
-		writeFailure("PowerShell did not report its profile, so there is nowhere to load the script from", input.isJSON);
+		writeFailure("shell_unavailable", "PowerShell did not report its profile, so there is nowhere to load the script from", input.isJSON);
 		return ExitCode.ERROR;
 	}
 	process.stderr.write(toDescription(plan, change));
 	if (!await isConfirmed(input.flags["yes"] === true)) {
-		writeFailure(process.stdin.isTTY ? "nothing was changed" : "nothing was changed. Pass --yes to change it without a terminal", input.isJSON);
+		writeFailure("not_confirmed", process.stdin.isTTY ? "nothing was changed" : "nothing was changed. Pass --yes to change it without a terminal", input.isJSON);
 		return ExitCode.USAGE;
 	}
 	if (change === "install") {
@@ -1658,7 +1723,7 @@ function toSchemaValues(schema) {
 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);
+		writeFailure("invalid_arguments", `${shell || "no shell"} is not one this CLI writes for. Choose ${SHELLS.join(", ")}`, input.isJSON);
 		return ExitCode.USAGE;
 	}
 	writeData(toScript(shell));
@@ -2064,25 +2129,25 @@ async function runLogin(input) {
 		}
 		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);
+			writeFailure("sign_in_failed", `sign in was refused: ${callback.error}${callback.errorDescription ? `, ${callback.errorDescription}` : ""}`, input.isJSON);
 			return ExitCode.ERROR;
 		}
 		if (callback.source === "listener" ? callback.state !== state : callback.state !== void 0 && callback.state !== state) {
-			writeFailure("the browser came back with a state this sign in did not send", input.isJSON);
+			writeFailure("sign_in_failed", "the browser came back with a state this sign in did not send", input.isJSON);
 			return ExitCode.ERROR;
 		}
 		if (callback.issuer !== void 0 && callback.issuer.replace(/\/+$/, "") !== metadata.issuer.replace(/\/+$/, "")) {
-			writeFailure(`the browser came back from ${callback.issuer}, which is not ${metadata.issuer}`, input.isJSON);
+			writeFailure("sign_in_failed", `the browser came back from ${callback.issuer}, which is not ${metadata.issuer}`, input.isJSON);
 			return ExitCode.ERROR;
 		}
 		if (!callback.code) {
-			writeFailure("the browser came back without an authorization code", input.isJSON);
+			writeFailure("sign_in_failed", "the browser came back without an authorization code", input.isJSON);
 			return ExitCode.ERROR;
 		}
 		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);
+			writeFailure("sign_in_failed", error.message, input.isJSON);
 			return ExitCode.ERROR;
 		}
 		throw error;
@@ -2092,7 +2157,7 @@ async function runLogin(input) {
 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);
+		writeFailure("sign_in_failed", `${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);
@@ -2126,7 +2191,7 @@ async function toDeviceTokens(approved, typed) {
 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);
+		writeFailure("sign_in_failed", "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));
@@ -3059,28 +3124,28 @@ function defineOperation(operation) {
 async function runOperation(operation, input) {
 	const path = toPath(operation, input.args);
 	if (path === void 0) {
-		writeFailure(`this command takes ${operation.pathParameters.length} argument(s)`, input.isJSON);
+		writeFailure("invalid_arguments", `this command takes ${operation.pathParameters.length} argument(s)`, input.isJSON);
 		return ExitCode.USAGE;
 	}
 	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);
+		writeFailure("missing_flag", `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);
+		writeFailure("invalid_flag", 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);
+		writeFailure("empty_request", `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);
+			writeFailure("invalid_input", built.message, input.isJSON);
 			return ExitCode.USAGE;
 		}
 		form = built;
@@ -3101,11 +3166,11 @@ async function runOperation(operation, input) {
 		return ExitCode.OK;
 	} catch (error) {
 		if (error instanceof NoCredential) {
-			writeFailure(error.message, input.isJSON);
+			writeFailure("not_signed_in", error.message, input.isJSON);
 			return ExitCode.NOT_AUTHENTICATED;
 		}
 		if (error instanceof RequestFailure) {
-			writeFailure(error.message, input.isJSON, error.errors, error.requestId, error.status);
+			writeFailure(toStatusCode(error.status), error.message, input.isJSON, error.errors, error.requestId, error.status);
 			return error.status === 401 ? ExitCode.NOT_AUTHENTICATED : ExitCode.ERROR;
 		}
 		throw error;
@@ -3120,7 +3185,7 @@ function toWritten(download, input) {
 	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);
+			writeFailure("output_required", "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);
@@ -5921,7 +5986,8 @@ function toRejectedFlag(command, flags) {
 /** 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").showHelpAfterError().enablePositionalOptions();
+	program.name("hardfin").description("Call the Hardfin API from a terminal or an agent").version(version$1, "-v, --version").enablePositionalOptions();
+	toQuietParser(program);
 	for (const flag of GLOBAL_FLAGS) program.option(`--${flag.name} <${flag.valueName}>`, flag.description);
 	for (const command of entries) program.addCommand(toProgram(program, command), { hidden: command.hidden });
 	return program;
@@ -5929,6 +5995,7 @@ function toCli(entries = commands) {
 /** toProgram wires one registry command into the parser. */
 function toProgram(root, command) {
 	const program = new Command(command.name).summary(command.summary).description(command.description ?? command.summary);
+	toQuietParser(program);
 	for (const argument of command.arguments) {
 		const name = argument.variadic ? `${argument.name}...` : argument.name;
 		program.argument(argument.required ? `<${name}>` : `[${name}]`, argument.description);
@@ -5952,11 +6019,41 @@ function toProgram(root, command) {
 	});
 	return program;
 }
+/** toQuietParser has the parser hand back its mistakes, so they are answered like any other failure. */
+function toQuietParser(program) {
+	program.exitOverride().configureOutput({ outputError: () => void 0 });
+}
+/** The parser's codes for a run that only showed help or the version, which is not a failure. */
+const SHOWN = /* @__PURE__ */ new Set([
+	"commander.helpDisplayed",
+	"commander.help",
+	"commander.version"
+]);
+/** toParseExitCode answers a mistake the parser caught before any command ran. */
+function toParseExitCode(error, args) {
+	if (!(error instanceof CommanderError)) return;
+	if (SHOWN.has(error.code)) return error.exitCode;
+	const isJSON = args.includes("--json") || !process.stdout.isTTY;
+	writeFailure(toParseCode(error.code), error.message.replace(/^error: /, ""), isJSON);
+	if (!isJSON) process.stderr.write("  Run the command with --help to see what it takes\n");
+	return ExitCode.USAGE;
+}
+function toParseCode(code) {
+	switch (code) {
+		case "commander.unknownCommand": return "unknown_command";
+		case "commander.unknownOption":
+		case "commander.optionMissingArgument":
+		case "commander.missingMandatoryOptionValue":
+		case "commander.conflictingOption":
+		case "commander.invalidArgument": return "invalid_flag";
+		default: return "invalid_arguments";
+	}
+}
 async function toExitCode(root, command, args, flags) {
 	const isJSON = isJSONOutput(flags);
 	const rejected = toRejectedFlag(command, flags);
 	if (rejected) {
-		writeFailure(rejected, isJSON);
+		writeFailure("invalid_flag", rejected, isJSON);
 		return ExitCode.USAGE;
 	}
 	let resolved;
@@ -5977,7 +6074,7 @@ async function toExitCode(root, command, args, flags) {
 			process.stderr.write("\n");
 			return ExitCode.INTERRUPTED;
 		}
-		writeFailure(error instanceof Error ? error.message : String(error), isJSON);
+		writeFailure(toErrorCode(error), error instanceof Error ? error.message : String(error), isJSON);
 		await toReported(error, isJSON, resolved);
 		return error instanceof ConfigFailure ? ExitCode.USAGE : ExitCode.ERROR;
 	}
@@ -6002,7 +6099,7 @@ async function toReported(error, isJSON, resolved, level = "error") {
 	if (id && !isJSON) process.stderr.write(`This looks like a problem in hardfin itself, and it has been reported to the Hardfin team. Reference: ${id}\n`);
 }
 //#endregion
-export { toCli, toReported, wasReportAttempted };
+export { toCli, toParseExitCode, toReported, wasReportAttempted };
 
-//# sourceMappingURL=program-CnXYN9xS.js.map
-//# debugId=8979dc06-d236-502b-bea1-b13868301f52
+//# sourceMappingURL=program-BZW_50HP.js.map
+//# debugId=5c189832-33ce-5032-b0e0-fc3a33cf5b1d

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@hardfin/cli",
-    "version": "0.1.0-dev.29",
+    "version": "0.1.0-dev.30",
     "description": "Command line interface for the Hardfin API",
     "license": "Apache-2.0",
     "author": "Hardfin, Inc.",