@hardfin/cli 0.0.2-dev.10 → 0.0.2-dev.12

package/README.md

@@ -47,9 +47,28 @@ and the shape of the last segment decide the verb.
 | `PATCH /asset/{assetKey}` | `hardfin asset update <assetKey>` |
 | `PATCH /asset/{assetKey}/accounting` | `hardfin asset accounting update <assetKey>` |
 
-A path parameter becomes a positional argument. A query parameter becomes a flag, named in
-kebab case, and an array parameter becomes a flag you repeat. An enum parameter carries its
-values, so a wrong value fails locally with exit code 2 rather than at the API.
+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 |
+
+```sh
+hardfin asset ownership create ast_4f9xk2mq7plr8stz \
+  --customer-id cst_a1 --date 2026-09-23 --sale-price 1500.00
+
+hardfin asset move execute create \
+  --move assetId=ast_a1,locationId=loc_x \
+  --move assetId=ast_b2,locationId=loc_y
+```
+
+An enum carries its values, so a wrong one fails locally with exit code 2 rather than at the
+API. A required field missing is caught the same way, before any request is made.
 
 ### Overrides
 
@@ -185,6 +204,53 @@ environment, so `hardfin login` works out of the box.
 | `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
+
+```sh
+source <(hardfin completion zsh)     # this shell, now
+hardfin completion zsh >> ~/.zshrc   # every shell after this one
+```
+
+`bash`, `zsh`, `fish` and `powershell` each get a script. The script asks the CLI what may
+follow what you have typed, so completions never fall behind the commands, including the ones
+generated from the API document.
+
+## Serving an agent
+
+```sh
+hardfin mcp
+```
+
+It speaks the Model Context Protocol on standard input and output, so Claude, Codex or any
+other client can run Hardfin commands.
+
+```sh
+claude mcp add hardfin -- hardfin mcp
+```
+
+### One tool, and resources for the rest
+
+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 |
+
+Fifty tools would describe the same surface and crowd out the work. An agent that needs the
+list reads a resource, or runs `["--help"]`.
+
+A tool call runs the CLI itself, so an agent and a person get identical parsing, output and
+exit codes.
+
+### What it signs in as
+
+The server uses whatever credential this machine holds, so an agent acts as the person who
+ran `hardfin login`. Give an agent an API key through `HARDFIN_API_KEY` when it should act
+as an integration instead.
+
 ## Diagnosing a problem
 
 `hardfin status` prints everything a support request needs, and is the first thing to send.