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

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
@@ -142,8 +159,18 @@ hardfin status           # what the CLI is configured with and signed in as
 hardfin logout           # forget this machine, and ask Hardfin to revoke it
 ```
 
-An API key is still the way to run unattended. `HARDFIN_API_KEY` wins over a stored sign in,
-so CI and an agent sandbox need no browser.
+An API key is still the way to run unattended. `--api-key`, or `HARDFIN_API_KEY`, wins over
+a stored sign in, so CI and an agent sandbox need no browser. The flag beats the variable.
+
+An API key is held to two rules before it is sent:
+
+| Rule                                                                                                                                    | Why                                                                     |
+| --------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| It goes only over https, or to this machine                                                                                             | Anything between here and the host could read it                        |
+| A key you set, by flag or exported variable, never goes to an API URL that `config.local.json` or `.env` in the working directory chose | A repository you cloned could otherwise send your key to its own server |
+
+A key and an API URL that come from the same folder's files still work together, which is
+how a local build is set up. Pass `--api-url` to send a key you set to that folder's address.
 
 ### What login does
 
@@ -356,7 +383,7 @@ settings, and the one nearest the top wins.
 
 | Layer       | Where                                                                 | Beats            |
 | ----------- | --------------------------------------------------------------------- | ---------------- |
-| Flag        | `--api-url`                                                           | everything below |
+| Flag        | `--api-url`, `--api-key`, `--issuer-url`                              | everything below |
 | Environment | an exported `HARDFIN_*` variable                                      | the files below  |
 | Env file    | `.env` in the working directory, or the file `HARDFIN_ENV_FILE` names | the config file  |
 | Config file | `config.local.json` in the working directory                          | the defaults     |

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]="bb3026cb-ab06-5af0-9743-290b61ec91a3")}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-B0vISolG.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-B0vISolG.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=bb3026cb-ab06-5af0-9743-290b61ec91a3

package/dist/completion-tree.json

@@ -5,6 +5,11 @@
       "description": "The API to call, whose host also holds the authorization server",
       "valueName": "url"
     },
+    {
+      "name": "api-key",
+      "description": "An API key to call with, in place of HARDFIN_API_KEY or a sign in",
+      "valueName": "key"
+    },
     {
       "name": "issuer-url",
       "description": "The authorization server, when it does not sit at the API's host",

package/dist/{program-CnXYN9xS.js → program-B0vISolG.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){}}();
-import { a as defineCommand, i as GLOBAL_FLAGS, r as ExitCode, t as toInvocation } from "./scrub-VtQmxap1.js";
+!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]="ab584cf3-443f-569e-8167-fa0cbab9ab68")}catch(e){}}();
+import { a as defineCommand, i as GLOBAL_FLAGS, r as ExitCode, t as toInvocation } from "./scrub-BN3gyBpR.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(),
@@ -795,12 +694,15 @@ const held = /* @__PURE__ */ new Map();
 * unattended caller sets it deliberately, and otherwise the stored refresh token buys an
 * access token that lives only in memory.
 */
-async function toRequestCredential(settings) {
-	if (settings.apiKey) return {
-		header: "X-API-Key",
-		value: settings.apiKey,
-		kind: "api key"
-	};
+async function toRequestCredential(settings, sources) {
+	if (settings.apiKey) {
+		refuseForeignKey(settings, sources);
+		return {
+			header: "X-API-Key",
+			value: settings.apiKey,
+			kind: "api key"
+		};
+	}
 	refuseForeignHost(settings);
 	const stored = toCredential(settings.issuerUrl);
 	if (!stored) throw new NoCredential("not authenticated. Run hardfin login, or set HARDFIN_API_KEY");
@@ -876,6 +778,20 @@ function refuseForeignHost(settings) {
 	if (api.host !== issuer.host) throw new NoCredential(`this sign in belongs to ${issuer.host}, so it is not sent to ${api.host}. Set HARDFIN_API_KEY to call another host, or point --issuer-url at the server that signs you in`);
 	if (api.protocol !== "https:" && !isLoopback(api.hostname)) throw new NoCredential(`${settings.apiUrl} is not https, so a sign in is not sent to it`);
 }
+/** The layers a file in the working directory sets, which a cloned repository can carry. */
+const DIRECTORY_SOURCES = /* @__PURE__ */ new Set(["config file", "env file"]);
+/** refuseForeignKey keeps an API key off plain connections and off hosts a stray file chose. */
+function refuseForeignKey(settings, sources) {
+	const api = toHost$1(settings.apiUrl);
+	if (api === void 0) throw new NoCredential(`${settings.apiUrl} is not a URL this CLI can call`);
+	if (api.protocol !== "https:" && !isLoopback(api.hostname)) throw new NoCredential(`Your API key was not sent, because ${api.host} does not use a secure connection.`);
+	const isKeyChosen = sources?.apiKey !== void 0 && !DIRECTORY_SOURCES.has(sources.apiKey);
+	const isUrlFromFolder = sources?.apiUrl !== void 0 && DIRECTORY_SOURCES.has(sources.apiUrl);
+	if (isKeyChosen && isUrlFromFolder) {
+		const file = sources.apiUrl === "config file" ? CONFIG_FILE : ".env";
+		throw new NoCredential(`Your API key was not sent to ${api.host}, because that address comes from a file in this folder, not from you.\nDetails: the API URL is set in ${file}. Pass --api-url to use it anyway`);
+	}
+}
 function toHost$1(url) {
 	try {
 		return new URL(url);
@@ -891,12 +807,15 @@ function isLoopback(hostname) {
 * an access token this process already holds. An error report uses it, because a refresh
 * cut short by the process ending would spend the refresh token and sign the person out.
 */
-function toHeldCredential(settings) {
-	if (settings.apiKey) return {
-		header: "X-API-Key",
-		value: settings.apiKey,
-		kind: "api key"
-	};
+function toHeldCredential(settings, sources) {
+	if (settings.apiKey) {
+		refuseForeignKey(settings, sources);
+		return {
+			header: "X-API-Key",
+			value: settings.apiKey,
+			kind: "api key"
+		};
+	}
 	const current = held.get(settings.issuerUrl);
 	if (!current || (current.expiresAt ?? 0) - EXPIRY_MARGIN_MS <= Date.now()) return;
 	return {
@@ -980,6 +899,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 with `--api-key`, 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,30 +1128,30 @@ 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;
 		}
 	}
 	try {
 		writeData((await request$1({
 			apiUrl: input.resolved.settings.apiUrl,
-			credential: await toRequestCredential(input.resolved.settings),
+			credential: await toRequestCredential(input.resolved.settings, input.resolved.sources),
 			method: toText(input.flags["method"] ?? "GET").toUpperCase(),
 			path,
 			query,
@@ -1075,11 +1160,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 +1570,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 +1743,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 +2149,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 +2177,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 +2211,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));
@@ -2478,7 +2563,7 @@ function toServerReport(metadata) {
 async function toApiReport(resolved, options) {
 	const settings = resolved.settings;
 	try {
-		const credential = options.isHeldOnly ? toHeldCredential(settings) : await toRequestCredential(settings);
+		const credential = options.isHeldOnly ? toHeldCredential(settings, resolved.sources) : await toRequestCredential(settings, resolved.sources);
 		if (!credential) return {
 			checked: false,
 			url: settings.apiUrl,
@@ -2610,7 +2695,7 @@ async function report(error, occasion, resolved) {
 		const settings = resolved ?? toResolved();
 		const status = settings ? await toStatus(settings) : void 0;
 		const secrets = [settings?.settings.apiKey, settings ? toCredential(settings.settings.issuerUrl)?.refreshToken : void 0];
-		return await (await import("./sentry-D5lKx0nm.js")).send({
+		return await (await import("./sentry-CLaeAWNa.js")).send({
 			error,
 			occasion,
 			telemetry,
@@ -2802,7 +2887,7 @@ const REFUSED_COMMANDS = /* @__PURE__ */ new Set([
 	"mcp"
 ]);
 /** The global options, which sit before a command and take a value of their own. */
-const GLOBAL_OPTIONS_WITH_VALUES = /* @__PURE__ */ new Set(["--api-url", "--issuer-url"]);
+const GLOBAL_OPTIONS_WITH_VALUES = new Set(GLOBAL_FLAGS.filter((flag) => flag.valueName).map((flag) => `--${flag.name}`));
 /**
 * toCommandName reads which command a call names. A global option sits before it, so
 * reading the first argument alone would let --issuer-url x logout through.
@@ -3059,28 +3144,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;
@@ -3088,7 +3173,7 @@ async function runOperation(operation, input) {
 	try {
 		const envelope = await request$1({
 			apiUrl: input.resolved.settings.apiUrl,
-			credential: await toRequestCredential(input.resolved.settings),
+			credential: await toRequestCredential(input.resolved.settings, input.resolved.sources),
 			method: operation.method,
 			path,
 			query: toQuery(operation, input.flags),
@@ -3101,11 +3186,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 +3205,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 +6006,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 +6015,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,17 +6039,48 @@ 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;
 	try {
 		resolved = toSettings({
 			apiUrl: root.opts()["apiUrl"],
+			apiKey: root.opts()["apiKey"],
 			issuerUrl: root.opts()["issuerUrl"]
 		});
 		return await command.run?.({
@@ -5977,7 +6095,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 +6120,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-B0vISolG.js.map
+//# debugId=ab584cf3-443f-569e-8167-fa0cbab9ab68

package/dist/{scrub-VtQmxap1.js → scrub-BN3gyBpR.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]="9fab3688-8d6c-599c-94b2-64daa75cd233")}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]="3af5060a-b6fe-5f2e-9661-01f4460a7b04")}catch(e){}}();
 import { z } from "zod";
 import { homedir } from "node:os";
 //#region src/command/registry.ts
@@ -17,17 +17,26 @@ function defineCommand(command) {
 	return command;
 }
 /** GLOBAL_FLAGS are the options the CLI takes before any command. */
-const GLOBAL_FLAGS = [{
-	name: "api-url",
-	description: "The API to call, whose host also holds the authorization server",
-	valueName: "url",
-	schema: z.string()
-}, {
-	name: "issuer-url",
-	description: "The authorization server, when it does not sit at the API's host",
-	valueName: "url",
-	schema: z.string()
-}];
+const GLOBAL_FLAGS = [
+	{
+		name: "api-url",
+		description: "The API to call, whose host also holds the authorization server",
+		valueName: "url",
+		schema: z.string()
+	},
+	{
+		name: "api-key",
+		description: "An API key to call with, in place of HARDFIN_API_KEY or a sign in",
+		valueName: "key",
+		schema: z.string()
+	},
+	{
+		name: "issuer-url",
+		description: "The authorization server, when it does not sit at the API's host",
+		valueName: "url",
+		schema: z.string()
+	}
+];
 //#endregion
 //#region src/report/scrub.ts
 const REDACTED = "[redacted]";
@@ -109,5 +118,5 @@ function toFlag(flags, word) {
 //#endregion
 export { defineCommand as a, GLOBAL_FLAGS as i, toScrubbed as n, ExitCode as r, toInvocation as t };
 
-//# sourceMappingURL=scrub-VtQmxap1.js.map
-//# debugId=9fab3688-8d6c-599c-94b2-64daa75cd233
+//# sourceMappingURL=scrub-BN3gyBpR.js.map
+//# debugId=3af5060a-b6fe-5f2e-9661-01f4460a7b04

package/dist/{sentry-D5lKx0nm.js → sentry-CLaeAWNa.js}

@@ -1,7 +1,7 @@
 #!/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]="a251c173-a448-5d16-93ea-bc9547e82365")}catch(e){}}();
-import { n as toScrubbed } from "./scrub-VtQmxap1.js";
+!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]="853940c3-9e72-566b-ad70-9f043e6aba8d")}catch(e){}}();
+import { n as toScrubbed } from "./scrub-BN3gyBpR.js";
 import { dirname } from "node:path";
 import { request } from "node:http";
 import { fileURLToPath } from "node:url";
@@ -4385,5 +4385,5 @@ function toTags(delivery) {
 //#endregion
 export { send };
 
-//# sourceMappingURL=sentry-D5lKx0nm.js.map
-//# debugId=a251c173-a448-5d16-93ea-bc9547e82365
+//# sourceMappingURL=sentry-CLaeAWNa.js.map
+//# debugId=853940c3-9e72-566b-ad70-9f043e6aba8d

package/package.json

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