@hardfin/cli 0.0.2-dev.15 → 0.0.2-dev.17

package/README.md

@@ -26,37 +26,37 @@ npm install -g @hardfin/cli@dev
 
 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 |
-| `spec/core.openapi.yaml` | The API document the generator reads, vendored here |
-| `scripts/generate-surface.mjs` | The generator |
+| 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                                                 |
+| `spec/core.openapi.yaml`           | The API document the generator reads, vendored here                                          |
+| `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>` |
+| 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>` |
 
 Everything an endpoint takes becomes a flag or an argument. No command asks for JSON.
 
-| The document says | You type |
-| --- | --- |
-| A path parameter | a positional argument |
-| A query or body field | `--field-name`, in kebab case |
-| A field inside a nested object | `--address-city`, the path joined |
-| An array of values | the flag, repeated |
-| An array of objects | the flag, repeated, each carrying that element's fields as `key=value` |
-| A file upload | `--file <path>`, sent as multipart |
+| The document says              | You type                                                               |
+| ------------------------------ | ---------------------------------------------------------------------- |
+| A path parameter               | a positional argument                                                  |
+| A query or body field          | `--field-name`, in kebab case                                          |
+| A field inside a nested object | `--address-city`, the path joined                                      |
+| An array of values             | the flag, repeated                                                     |
+| An array of objects            | the flag, repeated, each carrying that element's fields as `key=value` |
+| A file upload                  | `--file <path>`, sent as multipart                                     |
 
 ```sh
 hardfin asset ownership create ast_4f9xk2mq7plr8stz \
@@ -71,6 +71,13 @@ A value is sent as the type the document names. `--useful-life 36` sends the num
 decimal such as `--salvage-value 1500.00` stays a string, which is how the API takes money
 without losing precision.
 
+A download is written where you name it, and a terminal is never filled with a file's bytes.
+
+```sh
+hardfin file get file_7hq2mx9pkr4stz8w --output photo.jpg
+hardfin file get file_7hq2mx9pkr4stz8w --output - | wc -c
+```
+
 Clear a field with `--unset`, naming the flag:
 
 ```sh
@@ -118,10 +125,10 @@ what the api-spec bridge publishes. Commit the document and the generated comman
 
 Two checks keep the pair honest.
 
-| Check | Refuses |
-| --- | --- |
+| Check         | Refuses                                                                       |
+| ------------- | ----------------------------------------------------------------------------- |
 | The generator | a document whose `info.version` is not a date, which means an earlier release |
-| CI | a vendored document that was updated without regenerating the commands |
+| CI            | a vendored document that was updated without regenerating the commands        |
 
 The first one matters because `hardfinhq/api-spec` can sit a release behind the monorepo
 while its bridge pull request is open. Generating from that document would replace the
@@ -151,9 +158,9 @@ so CI and an agent sandbox need no browser.
 
 While it waits, the terminal takes two things.
 
-| Key | Does |
-| --- | --- |
-| `c` | Copies the URL to the clipboard |
+| Key                        | Does                                      |
+| -------------------------- | ----------------------------------------- |
+| `c`                        | Copies the URL to the clipboard           |
 | A pasted value, then enter | Finishes the sign in without the listener |
 
 Paste whichever of these you have: the whole redirect URL from the browser's address bar,
@@ -190,9 +197,9 @@ nothing about whether the credential is good.
 
 ### Where the refresh token is kept
 
-| Host | Kept in |
-| --- | --- |
-| macOS, Windows, and Linux with a secret service | the OS keyring |
+| Host                                                            | Kept in                                               |
+| --------------------------------------------------------------- | ----------------------------------------------------- |
+| macOS, Windows, and Linux with a secret service                 | the OS keyring                                        |
 | Everything else, including WSL, containers, and agent sandboxes | `$XDG_STATE_HOME/hardfin/credentials.json`, mode 0600 |
 
 `HARDFIN_NO_BROWSER=1` keeps `hardfin login` from opening a tab, which is what a script or a
@@ -210,10 +217,10 @@ production never share a sign in.
 Nothing. Hardfin registers this CLI as a first-party client, and its key is the same in every
 environment, so `hardfin login` works out of the box.
 
-| Setting | Holds | Default |
-| --- | --- | --- |
-| `clientId`, or `HARDFIN_CLIENT_ID` | the client this CLI names itself as | the seeded Hardfin CLI client |
-| `issuerUrl`, or `HARDFIN_ISSUER_URL` | the authorization server | the API's host root |
+| Setting                              | Holds                               | Default                       |
+| ------------------------------------ | ----------------------------------- | ----------------------------- |
+| `clientId`, or `HARDFIN_CLIENT_ID`   | the client this CLI names itself as | the seeded Hardfin CLI client |
+| `issuerUrl`, or `HARDFIN_ISSUER_URL` | the authorization server            | the API's host root           |
 
 ## Completing commands in your shell
 
@@ -244,11 +251,11 @@ claude mcp add hardfin -- hardfin mcp
 Every tool a server lists sits in the agent's context for the entire session, so this server
 offers one.
 
-| Offered as | Holds | Costs context |
-| --- | --- | --- |
-| The `hardfin` tool | A list of arguments, such as `["asset", "list", "--limit", "5"]` | Always, and it is about 400 bytes |
-| `hardfin://guide` | Every command, its flags, and the exit codes | Only when the agent reads it |
-| `hardfin://commands` | The command tree as JSON | Only when the agent reads it |
+| Offered as           | Holds                                                            | Costs context                     |
+| -------------------- | ---------------------------------------------------------------- | --------------------------------- |
+| The `hardfin` tool   | A list of arguments, such as `["asset", "list", "--limit", "5"]` | Always, and it is about 400 bytes |
+| `hardfin://guide`    | Every command, its flags, and the exit codes                     | Only when the agent reads it      |
+| `hardfin://commands` | The command tree as JSON                                         | Only when the agent reads it      |
 
 Fifty tools would describe the same surface and crowd out the work. An agent that needs the
 list reads a resource, or runs `["--help"]`.
@@ -272,14 +279,14 @@ hardfin status --json        # for a support request
 hardfin status --offline     # no network calls at all
 ```
 
-| Section | Holds |
-| --- | --- |
-| `cli` | The version, the API version it speaks, Node, and whether a terminal is attached |
-| `host` | The operating system, kernel, build, processor, memory, timezone, shell, and the distribution and WSL details on Linux |
-| `configuration` | Every setting, its value, and the layer it came from |
-| `credential` | Whether you are signed in, where the refresh token is kept, and when it was issued and last renewed |
-| `authorizationServer` | Whether discovery worked, and every endpoint it named |
-| `api` | Whether the API accepted the credential, when the access token expires, and its scopes |
+| Section               | Holds                                                                                                                  |
+| --------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `cli`                 | The version, the API version it speaks, Node, and whether a terminal is attached                                       |
+| `host`                | The operating system, kernel, build, processor, memory, timezone, shell, and the distribution and WSL details on Linux |
+| `configuration`       | Every setting, its value, and the layer it came from                                                                   |
+| `credential`          | Whether you are signed in, where the refresh token is kept, and when it was issued and last renewed                    |
+| `authorizationServer` | Whether discovery worked, and every endpoint it named                                                                  |
+| `api`                 | Whether the API accepted the credential, when the access token expires, and its scopes                                 |
 
 Nothing secret is printed. An API key and a refresh token are each reported as a
 `sha256:` fingerprint, which identifies a credential across two machines without disclosing
@@ -294,13 +301,13 @@ says which of the two you are looking at.
 A local build reaches a local server without editing code. Four layers supply the same
 settings, and the one nearest the top wins.
 
-| Layer | Where | Beats |
-| --- | --- | --- |
-| Flag | `--api-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 |
-| Default | the published API | nothing |
+| Layer       | Where                                                                 | Beats            |
+| ----------- | --------------------------------------------------------------------- | ---------------- |
+| Flag        | `--api-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     |
+| Default     | the published API                                                     | nothing          |
 
 An exported variable beats `.env` because Node leaves a variable that is already set alone.
 
@@ -336,6 +343,24 @@ The CLI reads whatever `config.local.json` and `.env` sit in the directory you r
 A directory you do not control can therefore point the CLI at a server you do not expect, so
 run `hardfin config` when a command reaches somewhere surprising.
 
+## Working on the CLI
+
+```sh
+npm run check-types      # tsc
+npm run lint             # eslint, with type-aware rules
+npm run prettier:write   # formatting
+npm test                 # vitest
+npm run build            # tsdown, into dist/cli.js
+```
+
+CI runs all five on every pull request, plus a check that the generated commands still match
+the vendored API document. A pull request that fails any of them cannot merge.
+
+Two lint rules exist because of defects that reached the repository. `no-floating-promises`
+covers a promise nobody waits for, which once killed the process when a sign in was
+cancelled. `no-base-to-string` covers a value stringified as `[object Object]`, which a
+request would have carried to the API.
+
 ## Releasing
 
 This section is for anyone who merges a pull request in this repository. It tells you where
@@ -358,11 +383,11 @@ package published from a public repository, and this repository is private.
 
 ### What each merge publishes
 
-| Merge | Publishes | Version | Dist-tag |
-| --- | --- | --- | --- |
-| Pull request into `dev` | always | the next version, suffixed `-dev.<run number>` | `dev` |
-| Promotion into `main` | when `package.json` names a version that is not yet on npm | that version | `latest` |
-| Hotfix into `main` | same rule as a promotion | that version | `latest` |
+| Merge                   | Publishes                                                  | Version                                        | Dist-tag |
+| ----------------------- | ---------------------------------------------------------- | ---------------------------------------------- | -------- |
+| Pull request into `dev` | always                                                     | the next version, suffixed `-dev.<run number>` | `dev`    |
+| Promotion into `main`   | when `package.json` names a version that is not yet on npm | that version                                   | `latest` |
+| Hotfix into `main`      | same rule as a promotion                                   | that version                                   | `latest` |
 
 A preview never moves `latest`, so `npm install @hardfin/cli` keeps returning the released
 version.
@@ -395,13 +420,13 @@ on `main` until someone brings it back.
 A required check reads `version` from `package.json` on every pull request and judges it
 against the branch the pull request targets.
 
-| Version | Into `dev` | Into `main` |
-| --- | --- | --- |
-| Plain, above what `main` holds | passes | passes |
-| Plain, equal to what `main` holds | passes | refused, because npm already serves it |
-| Plain, below what `main` holds | refused | refused |
-| Carrying a `-dev` or any other prerelease suffix | refused | refused |
-| Not a semver version | refused | refused |
+| Version                                          | Into `dev` | Into `main`                            |
+| ------------------------------------------------ | ---------- | -------------------------------------- |
+| Plain, above what `main` holds                   | passes     | passes                                 |
+| Plain, equal to what `main` holds                | passes     | refused, because npm already serves it |
+| Plain, below what `main` holds                   | refused    | refused                                |
+| Carrying a `-dev` or any other prerelease suffix | refused    | refused                                |
+| Not a semver version                             | refused    | refused                                |
 
 A prerelease suffix is refused everywhere because the release workflow appends it at publish
 time. A version equal to `main`'s is fine on `dev`, since the workflow increments the patch

package/dist/cli.js

@@ -120,6 +120,16 @@ 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") {
@@ -248,7 +258,8 @@ function toSummary(command) {
 			valueName: flag.valueName ?? null,
 			repeatable: flag.repeatable ?? false
 		})),
-		examples: command.examples
+		examples: command.examples,
+		subcommands: command.subcommands?.filter((entry) => !entry.hidden).map(toSummary)
 	};
 }
 //#endregion
@@ -372,7 +383,7 @@ async function toTokens(url, form) {
 		body: new URLSearchParams(form)
 	});
 	const body = await response.json().catch(() => void 0);
-	if (!response.ok) throw new GrantFailure(String(body?.["error"] ?? `http_${response.status}`), body?.["error_description"] === void 0 ? void 0 : String(body["error_description"]));
+	if (!response.ok) throw new GrantFailure(toText(body?.["error"] ?? `http_${response.status}`), body?.["error_description"] === void 0 ? void 0 : toText(body["error_description"]));
 	const parsed = TokenResponse.safeParse(body);
 	if (!parsed.success) throw new GrantFailure("invalid_response", "the token endpoint did not answer with a token");
 	return {
@@ -477,12 +488,12 @@ function forgetKeyring(issuer) {
 function forgetFile(issuer) {
 	const held = readFile();
 	if (held[issuer] === void 0) return;
-	delete held[issuer];
-	if (Object.keys(held).length === 0) {
+	const remaining = Object.fromEntries(Object.entries(held).filter(([name]) => name !== issuer));
+	if (Object.keys(remaining).length === 0) {
 		rmSync(toCredentialPath(), { force: true });
 		return;
 	}
-	writeFile(held);
+	writeFile(remaining);
 }
 /** toKeyring opens the OS keyring, or answers undefined where the platform has none. */
 function toKeyring(issuer) {
@@ -709,11 +720,11 @@ var RequestFailure = class extends Error {
 /** request calls one /v2 endpoint and returns the envelope it answered with. */
 async function request(options) {
 	const url = new URL(`${options.apiUrl}${toLeadingSlash(options.path)}`);
-	if (options.query) url.search = options.query.toString();
+	for (const [name, value] of options.query ?? []) url.searchParams.append(name, value);
 	const headers = {
 		[options.credential.header]: options.credential.value,
 		"X-API-Version": API_VERSION,
-		Accept: "application/json"
+		Accept: options.downloads ? "*/*" : "application/json"
 	};
 	if (options.body !== void 0 && options.form === void 0) headers["Content-Type"] = "application/json";
 	const response = await fetch(url, {
@@ -721,6 +732,11 @@ async function request(options) {
 		headers,
 		body: options.form ?? (options.body === void 0 ? void 0 : JSON.stringify(options.body))
 	});
+	if (options.downloads && response.ok) return { data: {
+		bytes: Buffer.from(await response.arrayBuffer()),
+		contentType: response.headers.get("content-type"),
+		fileName: toFileName(response.headers.get("content-disposition"))
+	} };
 	const envelope = toEnvelope(await response.text());
 	if (!response.ok && envelope === void 0) throw new RequestFailure(response.status, [{
 		error: toStatusMessage(response.status),
@@ -735,6 +751,11 @@ async function request(options) {
 	}
 	return envelope ?? { data: null };
 }
+/** toFileName reads the name a download was offered under, when the server names one. */
+function toFileName(disposition) {
+	const matched = /filename\*?=(?:UTF-8'')?"?([^";]+)"?/i.exec(disposition ?? "");
+	return matched?.[1] ? decodeURIComponent(matched[1]) : void 0;
+}
 function toLeadingSlash(path) {
 	return path.startsWith("/") ? path : `/${path}`;
 }
@@ -834,7 +855,7 @@ async function runApi(input) {
 		writeData((await request({
 			apiUrl: input.resolved.settings.apiUrl,
 			credential: await toRequestCredential(input.resolved.settings),
-			method: String(input.flags["method"] ?? "GET").toUpperCase(),
+			method: toText(input.flags["method"] ?? "GET").toUpperCase(),
 			path,
 			query,
 			body
@@ -962,7 +983,7 @@ function toFlagNames(command) {
 	return [...(command?.flags ?? []).map((flag) => `--${flag.name}`), "--help"];
 }
 async function runCompletion(input) {
-	const shell = String(input.args[0] ?? "");
+	const shell = input.args[0] ?? "";
 	if (!SHELLS.includes(shell)) {
 		writeFailure(`${shell || "no shell"} is not one this CLI writes for. Choose ${SHELLS.join(", ")}`, input.isJSON);
 		return ExitCode.USAGE;
@@ -1116,7 +1137,7 @@ async function toDeviceAuthorization(endpoint, clientId, scope) {
 		})
 	});
 	const body = await response.json().catch(() => void 0);
-	if (!response.ok) throw new GrantFailure(String(body?.["error"] ?? `http_${response.status}`), body?.["error_description"] === void 0 ? void 0 : String(body["error_description"]));
+	if (!response.ok) throw new GrantFailure(toText(body?.["error"] ?? `http_${response.status}`), body?.["error_description"] === void 0 ? void 0 : toText(body["error_description"]));
 	const parsed = DeviceResponse.safeParse(body);
 	if (!parsed.success) throw new GrantFailure("invalid_response", "the device endpoint did not answer with a code");
 	return {
@@ -1192,8 +1213,12 @@ async function toListener(timeoutMs) {
 	}, timeoutMs);
 	return {
 		redirectUri: `http://${HOST}:${server.address().port}${CALLBACK_PATH}`,
-		callback: callback.finally(() => close(server, timer)),
-		close: () => close(server, timer)
+		callback: callback.finally(() => {
+			close(server, timer);
+		}),
+		close: () => {
+			close(server, timer);
+		}
 	};
 }
 function toCallback(request) {
@@ -1395,7 +1420,7 @@ async function runLogin(input) {
 	try {
 		const clientId = settings.clientId;
 		const metadata = await toMetadata(settings.issuerUrl);
-		const scope = String(input.flags["scope"] ?? DEFAULT_SCOPES);
+		const scope = toText(input.flags["scope"] ?? DEFAULT_SCOPES);
 		if (input.flags["device"] === true) return await runDeviceLogin(input, metadata, scope);
 		const listener = await toListener(WAIT_MS);
 		const pkce = toPkce();
@@ -1551,7 +1576,9 @@ async function runLogout(input) {
 	} catch {
 		revoked = false;
 	}
-	await withLock(() => forget(settings.issuerUrl));
+	await withLock(() => {
+		forget(settings.issuerUrl);
+	});
 	forgetHeldTokens();
 	writeData({
 		signedOut: true,
@@ -1613,7 +1640,7 @@ async function toResponse(request, commands, run) {
 			description: "The command tree as JSON",
 			mimeType: "application/json"
 		}] });
-		case "resources/read": return answer(toResource(String(request.params?.["uri"] ?? ""), commands));
+		case "resources/read": return answer(toResource(toText(request.params?.["uri"] ?? ""), commands));
 		case "tools/call": return answer(await toToolResult(request.params, run));
 		case "ping": return answer({});
 		default:
@@ -1658,7 +1685,21 @@ function toTree(commands) {
 		subcommands: command.subcommands ? toTree(command.subcommands) : void 0
 	}));
 }
+/** Signing in needs a browser and a person, neither of which an agent's session has. */
+const REFUSED_COMMANDS = /* @__PURE__ */ new Set([
+	"login",
+	"logout",
+	"mcp"
+]);
 async function toToolResult(params, run) {
+	const name = params?.["name"];
+	if (name !== void 0 && name !== TOOL.name) return {
+		content: [{
+			type: "text",
+			text: `this server offers one tool, ${TOOL.name}`
+		}],
+		isError: true
+	};
 	const args = (params?.["arguments"])?.args;
 	if (!Array.isArray(args) || args.some((entry) => typeof entry !== "string")) return {
 		content: [{
@@ -1667,7 +1708,15 @@ async function toToolResult(params, run) {
 		}],
 		isError: true
 	};
-	const outcome = await run(args);
+	const asked = args;
+	if (REFUSED_COMMANDS.has(asked[0] ?? "")) return {
+		content: [{
+			type: "text",
+			text: `${asked[0] ?? ""} is run by a person at a terminal, not through this server. Run hardfin ${asked[0] ?? ""} yourself, then call this tool again`
+		}],
+		isError: true
+	};
+	const outcome = await run(asked);
 	return {
 		content: [{
 			type: "text",
@@ -1676,6 +1725,14 @@ async function toToolResult(params, run) {
 		isError: outcome.code !== 0
 	};
 }
+/** toRequestId reads the id of a line that could not be answered, so a client is not left waiting. */
+function toRequestId(line) {
+	try {
+		return JSON.parse(line).id ?? null;
+	} catch {
+		return null;
+	}
+}
 /** toCliRunner runs the CLI itself, so a tool call parses exactly as a terminal would. */
 function toCliRunner() {
 	return (args) => new Promise((resolve) => {
@@ -1691,11 +1748,13 @@ function toCliRunner() {
 		child.stderr.on("data", (chunk) => {
 			stderr += chunk.toString();
 		});
-		child.on("close", (code) => resolve({
-			stdout,
-			stderr,
-			code: code ?? 1
-		}));
+		child.on("close", (code) => {
+			resolve({
+				stdout,
+				stderr,
+				code: code ?? 1
+			});
+		});
 	});
 }
 /** serve answers requests on stdin until the client closes it. */
@@ -1709,9 +1768,9 @@ async function serve(commands, run = toCliRunner()) {
 		} catch (error) {
 			response = {
 				jsonrpc: "2.0",
-				id: null,
+				id: toRequestId(line),
 				error: {
-					code: -32700,
+					code: -32603,
 					message: error instanceof Error ? error.message : String(error)
 				}
 			};
@@ -1766,6 +1825,12 @@ const FILE_FLAG = {
 	valueName: "path",
 	schema: z.string()
 };
+const OUTPUT_FLAG = {
+	name: "output",
+	description: "Where to write the file, or - for standard output",
+	valueName: "path",
+	schema: z.string()
+};
 const JSON_FLAG = {
 	name: "json",
 	description: "Print machine-readable output, which is the default when stdout is not a terminal",
@@ -1778,6 +1843,7 @@ function defineOperation(operation) {
 		...operation.bodyFlags,
 		...operation.bodyFlags.some((flag) => flag.nullable) ? [UNSET_FLAG] : [],
 		...operation.upload ? [...operation.upload.fields, FILE_FLAG] : [],
+		...operation.downloads ? [OUTPUT_FLAG] : [],
 		JSON_FLAG
 	];
 	return {
@@ -1823,15 +1889,18 @@ async function runOperation(operation, input) {
 		form = built;
 	}
 	try {
-		writeData((await request({
+		const envelope = await request({
 			apiUrl: input.resolved.settings.apiUrl,
 			credential: await toRequestCredential(input.resolved.settings),
 			method: operation.method,
 			path,
 			query: toQuery(operation, input.flags),
 			body,
-			form
-		})).data);
+			form,
+			downloads: operation.downloads
+		});
+		if (operation.downloads) return toWritten(envelope.data, input);
+		writeData(envelope.data);
 		return ExitCode.OK;
 	} catch (error) {
 		if (error instanceof NoCredential) {
@@ -1846,6 +1915,29 @@ async function runOperation(operation, input) {
 		return ExitCode.ERROR;
 	}
 }
+/**
+* toWritten puts a downloaded file where it was asked for. A terminal is never written to,
+* because a person would otherwise have their session filled with a file's bytes.
+*/
+function toWritten(download, input) {
+	const asked = input.flags["output"];
+	const path = typeof asked === "string" ? asked : download.fileName ?? "-";
+	if (path === "-") {
+		if (process.stdout.isTTY) {
+			writeFailure("this answer is a file, so name where to write it with --output, or send it on with a pipe", input.isJSON);
+			return ExitCode.USAGE;
+		}
+		process.stdout.write(download.bytes);
+		return ExitCode.OK;
+	}
+	writeFileSync(path, download.bytes);
+	writeData({
+		written: path,
+		bytes: download.bytes.length,
+		contentType: download.contentType
+	});
+	return ExitCode.OK;
+}
 /** toPath fills the path template from the positional arguments, in order. */
 function toPath(operation, args) {
 	if (args.length !== operation.pathParameters.length) return;
@@ -1861,7 +1953,7 @@ function toQuery(operation, flags) {
 		if (value === void 0) continue;
 		const parsed = flag.schema.safeParse(value);
 		const carried = parsed.success ? parsed.data : value;
-		for (const entry of Array.isArray(carried) ? carried : [carried]) query.append(flag.queryName, String(entry));
+		for (const entry of Array.isArray(carried) ? carried : [carried]) query.append(flag.queryName, toText(entry));
 	}
 	return query;
 }
@@ -1883,7 +1975,7 @@ async function toForm(upload, flags) {
 		const value = flags[toOptionKey(field.name)];
 		if (value !== void 0) {
 			const parsed = field.schema.safeParse(value);
-			form.append(field.jsonPath[0] ?? field.name, String(parsed.success ? parsed.data : value));
+			form.append(field.jsonPath[0] ?? field.name, toText(parsed.success ? parsed.data : value));
 		}
 	}
 	return form;
@@ -1896,7 +1988,7 @@ function toBody(operation, flags) {
 		const value = flags[toOptionKey(flag.name)];
 		if (value === void 0) continue;
 		if (flag.element) {
-			const elements = toElements(flag, Array.isArray(value) ? value.map(String) : [String(value)]);
+			const elements = toElements(flag, Array.isArray(value) ? value.map(toText) : [toText(value)]);
 			if (elements instanceof Error) return elements;
 			set(body, flag.jsonPath, elements);
 			hasField = true;
@@ -1913,7 +2005,7 @@ function toBody(operation, flags) {
 /** toCleared sends null for each field named by --unset, which is how a field is cleared. */
 function toCleared(operation, flags, body) {
 	const named = flags["unset"];
-	const names = Array.isArray(named) ? named.map(String) : named === void 0 ? [] : [String(named)];
+	const names = Array.isArray(named) ? named.map(toText) : named === void 0 ? [] : [toText(named)];
 	for (const name of names) {
 		const flag = operation.bodyFlags.find((entry) => entry.name === name.replace(/^--/, ""));
 		if (!flag) return /* @__PURE__ */ new Error(`--unset names no field called ${name}`);
@@ -2575,6 +2667,7 @@ const surfaceCommands = [
 							name: "is-in-service-date-managed-automatically",
 							jsonPath: ["isInServiceDateManagedAutomatically"],
 							description: "Whether Hardfin sets the in-service date itself, which sending an in-service date turns off",
+							negatable: true,
 							nullable: true,
 							schema: z.boolean()
 						},
@@ -2641,6 +2734,7 @@ const surfaceCommands = [
 							name: "automatic",
 							jsonPath: ["automatic"],
 							description: "Whether Hardfin sets the asset's in-service date itself",
+							negatable: true,
 							required: true,
 							schema: z.boolean()
 						}]
@@ -3343,12 +3437,14 @@ const surfaceCommands = [
 						name: "is-customer",
 						jsonPath: ["isCustomer"],
 						description: "Whether the company is a customer",
+						negatable: true,
 						schema: z.boolean()
 					},
 					{
 						name: "is-supplier",
 						jsonPath: ["isSupplier"],
 						description: "Whether the company is a supplier",
+						negatable: true,
 						schema: z.boolean()
 					},
 					{
@@ -3448,6 +3544,7 @@ const surfaceCommands = [
 						name: "is-archived",
 						jsonPath: ["isArchived"],
 						description: "Whether the customer is archived",
+						negatable: true,
 						nullable: true,
 						schema: z.boolean()
 					},
@@ -3455,6 +3552,7 @@ const surfaceCommands = [
 						name: "is-customer",
 						jsonPath: ["isCustomer"],
 						description: "Whether the company is a customer",
+						negatable: true,
 						nullable: true,
 						schema: z.boolean()
 					},
@@ -3462,6 +3560,7 @@ const surfaceCommands = [
 						name: "is-supplier",
 						jsonPath: ["isSupplier"],
 						description: "Whether the company is a supplier",
+						negatable: true,
 						nullable: true,
 						schema: z.boolean()
 					},
@@ -3536,7 +3635,8 @@ const surfaceCommands = [
 				description: "True when the file downloads as an attachment rather than opening inline",
 				schema: z.boolean()
 			}],
-			bodyFlags: []
+			bodyFlags: [],
+			downloads: true
 		})]
 	},
 	{
@@ -3639,6 +3739,7 @@ const surfaceCommands = [
 						name: "accepts-bulk-serials",
 						jsonPath: ["acceptsBulkSerials"],
 						description: "Whether a BULK item records serial numbers on its units, which SERVICE and DEVICE items ignore",
+						negatable: true,
 						schema: z.boolean()
 					},
 					{
@@ -3775,6 +3876,7 @@ const surfaceCommands = [
 						name: "accepts-bulk-serials",
 						jsonPath: ["acceptsBulkSerials"],
 						description: "Whether a BULK item records serial numbers on its units, read only beside type",
+						negatable: true,
 						nullable: true,
 						schema: z.boolean()
 					},
@@ -3803,6 +3905,7 @@ const surfaceCommands = [
 						name: "is-archived",
 						jsonPath: ["isArchived"],
 						description: "Whether the item is archived, which cannot be null",
+						negatable: true,
 						nullable: true,
 						schema: z.boolean()
 					},
@@ -4272,18 +4375,21 @@ const surfaceCommands = [
 						name: "is-inventory",
 						jsonPath: ["isInventory"],
 						description: "Whether assets at the location count as inventory for reporting",
+						negatable: true,
 						schema: z.boolean()
 					},
 					{
 						name: "is-inventory-override",
 						jsonPath: ["isInventoryOverride"],
 						description: "Whether a zone sets its own isInventory rather than inheriting its parent site's, which a site refuses",
+						negatable: true,
 						schema: z.boolean()
 					},
 					{
 						name: "is-transient",
 						jsonPath: ["isTransient"],
 						description: "Whether assets make only occasional or temporary stops at the location, which hides it from location lists by default",
+						negatable: true,
 						schema: z.boolean()
 					},
 					{
@@ -4425,6 +4531,7 @@ const surfaceCommands = [
 						name: "is-archived",
 						jsonPath: ["isArchived"],
 						description: "Whether the location is archived, and archiving a site archives its zones",
+						negatable: true,
 						nullable: true,
 						schema: z.boolean()
 					},
@@ -4432,6 +4539,7 @@ const surfaceCommands = [
 						name: "is-inventory",
 						jsonPath: ["isInventory"],
 						description: "Whether assets at the location count as inventory for reporting",
+						negatable: true,
 						nullable: true,
 						schema: z.boolean()
 					},
@@ -4439,6 +4547,7 @@ const surfaceCommands = [
 						name: "is-inventory-override",
 						jsonPath: ["isInventoryOverride"],
 						description: "Whether a zone sets its own isInventory rather than inheriting its parent site's, which a site refuses",
+						negatable: true,
 						nullable: true,
 						schema: z.boolean()
 					},
@@ -4446,6 +4555,7 @@ const surfaceCommands = [
 						name: "is-transient",
 						jsonPath: ["isTransient"],
 						description: "Whether assets make only occasional or temporary stops at the location, which hides it from location lists by default",
+						negatable: true,
 						nullable: true,
 						schema: z.boolean()
 					},
@@ -4694,27 +4804,24 @@ function toEnvironmentReport() {
 		apiVersion: API_VERSION,
 		node: process.version,
 		platform: process.platform,
-		interactive: Boolean(process.stdin.isTTY)
+		interactive: process.stdin.isTTY
 	};
 }
 /** toConfigurationReport names every setting, its source, and never a secret's value. */
 function toConfigurationReport(resolved) {
-	const entries = Object.entries(resolved.settings).map(([key, value]) => {
+	const report = { configFile: CONFIG_FILE };
+	for (const [key, value] of Object.entries(resolved.settings)) {
 		const from = resolved.sources[key];
-		if (key === "apiKey") return [key, {
+		report[key] = key === "apiKey" ? {
 			set: value !== void 0,
 			fingerprint: toFingerprint(value),
 			from
-		}];
-		return [key, {
+		} : {
 			value: value ?? null,
 			from
-		}];
-	});
-	return {
-		...Object.fromEntries(entries),
-		configFile: CONFIG_FILE
-	};
+		};
+	}
+	return report;
 }
 function toCredentialReport(apiKey, stored) {
 	if (apiKey) return {
@@ -4810,8 +4917,7 @@ function toFlattened(value) {
 	if (value === null || typeof value !== "object" || Array.isArray(value)) return;
 	const holder = value;
 	if (holder.from === void 0) return;
-	const shown = holder.value ?? (holder.set ? holder.fingerprint ?? "set" : "not set");
-	return `${String(shown)}  (${holder.from})`;
+	return `${toText(holder.value ?? (holder.set ? holder.fingerprint ?? "set" : "not set"))}  (${holder.from})`;
 }
 /** toLines lays the report out for a person, one indented line per value. */
 function toLines(report, depth = 0) {
@@ -4873,6 +4979,7 @@ function toProgram(command) {
 		const short = flag.short ? `-${flag.short}, ` : "";
 		const value = flag.valueName ? ` <${flag.valueName}>` : "";
 		const option = new Option(`${short}--${flag.name}${value}`, flag.description);
+		if (flag.negatable) program.addOption(new Option(`--no-${flag.name}`, `${flag.description}, turned off`));
 		if (flag.repeatable) option.argParser(collect);
 		if (flag.defaultValue !== void 0) option.default(flag.defaultValue);
 		program.addOption(option);
@@ -4913,7 +5020,7 @@ async function toExitCode(command, args, flags) {
 }
 function toArgumentList(value) {
 	if (Array.isArray(value)) return value.map(String);
-	return value === void 0 ? [] : [String(value)];
+	return value === void 0 ? [] : [toText(value)];
 }
 function collect(value, previous) {
 	return [...previous ?? [], value];

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@hardfin/cli",
-    "version": "0.0.2-dev.15",
+    "version": "0.0.2-dev.17",
     "description": "Command line interface for the Hardfin API",
     "license": "Apache-2.0",
     "author": "Hardfin, Inc.",
@@ -37,7 +37,12 @@
         "check-types": "tsc --noEmit",
         "test": "vitest run",
         "test:watch": "vitest",
-        "prepublishOnly": "npm run build"
+        "prepublishOnly": "npm run build",
+        "lint": "eslint . --report-unused-disable-directives --max-warnings 0",
+        "lint:fix": "eslint . --fix",
+        "prettier:check": "prettier --check .",
+        "prettier:write": "prettier --write .",
+        "test:coverage": "vitest run --coverage"
     },
     "dependencies": {
         "@napi-rs/keyring": "^2.1.0",
@@ -45,10 +50,16 @@
         "zod": "^4.6.5"
     },
     "devDependencies": {
+        "@eslint/js": "^10.0.1",
         "@types/node": "^22.15.0",
         "@vitest/coverage-v8": "^5.0.1",
+        "eslint": "^10.11.0",
+        "eslint-plugin-unused-imports": "^4.4.1",
+        "globals": "^17.12.0",
+        "prettier": "^3.9.9",
         "tsdown": "^0.23.0",
         "typescript": "^5.9.0",
+        "typescript-eslint": "^8.70.1",
         "unrun": "^0.3.1",
         "vitest": "^5.0.1",
         "yaml": "^2.9.1"