@hardfin/cli 0.1.1-dev.56 → 0.1.1-dev.58

package/README.md

@@ -79,7 +79,8 @@ Inside a `key=value` flag, `=` gives a value as you typed it and `:=` gives it a
 | `value=36`              | the text "36", because a custom field may hold a serial number     |
 | `value:=36`             | the number 36                                                      |
 | `value:=true`           | the boolean true                                                   |
-| `deliverAt:=null`       | null                                                               |
+| `deliverAt=null`        | null, because the field takes it                                   |
+| `deliverAt="null"`      | the text "null"                                                    |
 | `order=2` or `order:=2` | the number 2, because the document types `order` as a whole number |
 
 A value the field does not take fails locally with exit code 2, such as `order=two`, or
@@ -104,7 +105,18 @@ hardfin location create --input location.json
 echo '{"name": "Dock 4, north side"}' | hardfin location create --input -
 ```
 
-Clear a field with `--unset`, naming the flag:
+The word `null` clears a field the API takes null for. It is read before anything else,
+whatever the field holds, and `"null"` in quotes is the text.
+
+```sh
+hardfin asset accounting update ast_4f9xk2mq7plr8stz --useful-life null     # clears it
+hardfin asset update ast_4f9xk2mq7plr8stz --description '"null"'            # the text null
+```
+
+A field the API does not take null for is sent the word as text. The same holds inside a
+`key=value` flag, as in `deliverAt=null`.
+
+`--unset` clears a field too, naming the flag:
 
 ```sh
 hardfin asset accounting update ast_4f9xk2mq7plr8stz --unset useful-life
@@ -143,6 +155,31 @@ An agent branches on `code`. A code is never renamed and never changes meaning,
 message may be reworded at any time. `hardfin agent-guide` lists every code with what it
 means, and `src/output/failure.ts` defines them.
 
+### Calling an endpoint no command covers
+
+`hardfin api` calls any path under the API. It takes the same parts a generated command does,
+named by hand.
+
+```sh
+hardfin api /customer -f page=2 -f limit=50                    # query parameters
+hardfin api -X PATCH /item/item_V1StGXR8Z5jdHi6B --input body.json   # a JSON body
+hardfin api /file/file_7hq2mx9pkr4stz8w --output photo.jpg      # a download
+hardfin api -X POST /file --file photo.jpg -F fileType=ASSET_FILE   # an upload, as multipart
+hardfin api /file/file_7hq2mx9pkr4stz8w -H 'If-None-Match: "abc"' --output photo.jpg
+```
+
+| Flag               | Sends                                                                              |
+| ------------------ | ---------------------------------------------------------------------------------- |
+| `-f key=value`     | A query parameter, repeatable                                                      |
+| `--input <path>`   | A JSON body, from a file or `-` for standard input                                 |
+| `--file <path>`    | A file as multipart, under the part name `data` unless `--file-part` names another |
+| `-F key=value`     | A field beside the file, repeatable                                                |
+| `-H "Name: value"` | A request header, repeatable                                                       |
+| `--output <path>`  | Nothing. It writes the file the endpoint answers with, or `-` for standard output  |
+
+A header cannot set `Authorization`, `X-API-Key` or `X-API-Version`, which come from your sign
+in and settings. `--file` and `--input` cannot be given together.
+
 ### Reading the commands from a program
 
 `hardfin agent-guide` describes the CLI to an agent, as Markdown or as JSON. Name a command to

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]="ec88336e-026f-5a04-9acd-43c5410c3229")}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]="a7e96225-360e-5093-91ec-0d60c0a9c032")}catch(e){}}();
 import module from "node:module";
 //#region src/cli.ts
 module.enableCompileCache?.();
@@ -14,7 +14,7 @@ process.on("unhandledRejection", (error) => void toCrash(error));
 try {
 	const answer = await toQuickAnswer(process.argv.slice(2));
 	if (answer === void 0) {
-		const { toCli, toParseExitCode, wasReportAttempted } = await import("./program-CI4W2agw.js");
+		const { toCli, toParseExitCode, wasReportAttempted } = await import("./program-C2DP0mVy.js");
 		try {
 			await toCli().parseAsync(process.argv);
 		} catch (error) {
@@ -33,7 +33,7 @@ async function toCrash(error) {
 	isCrashing = true;
 	const isJSON = process.argv.includes("--json") || !process.stdout.isTTY;
 	try {
-		const { toReported, writeCrash } = await import("./program-CI4W2agw.js");
+		const { toReported, writeCrash } = await import("./program-C2DP0mVy.js");
 		writeCrash(error, isJSON);
 		await toReported(error, isJSON, void 0, "fatal");
 	} catch {
@@ -54,4 +54,4 @@ async function toQuickAnswer(args) {
 export {};
 
 //# sourceMappingURL=cli.js.map
-//# debugId=ec88336e-026f-5a04-9acd-43c5410c3229
+//# debugId=a7e96225-360e-5093-91ec-0d60c0a9c032

package/dist/completion-tree.json

@@ -2566,6 +2566,35 @@
           "description": "A file holding the JSON request body, or - for stdin",
           "valueName": "file"
         },
+        {
+          "name": "file",
+          "description": "A file to upload as multipart, in place of a JSON body",
+          "valueName": "path"
+        },
+        {
+          "name": "file-part",
+          "description": "The name of the part the file is sent as, which is data when not given",
+          "valueName": "name"
+        },
+        {
+          "name": "form",
+          "short": "F",
+          "description": "A field sent beside the file as key=value, repeatable",
+          "valueName": "key=value",
+          "repeatable": true
+        },
+        {
+          "name": "header",
+          "short": "H",
+          "description": "A request header as Name: value, repeatable",
+          "valueName": "name: value",
+          "repeatable": true
+        },
+        {
+          "name": "output",
+          "description": "Where to write a file the endpoint answers with, or - for standard output",
+          "valueName": "path"
+        },
         {
           "name": "json",
           "description": "Print machine-readable output, which is the default when stdout is not a terminal"