rstropek/2026-09-14-ac/cli

inventory CLI

Agent-friendly command-line client for the IT inventory web API (see DESIGN.md, "API contract"). Never interactive: all input is flags, a --json document, or stdin. Output is compact JSON on stdout by default.

Setup

npm run build -w cli                 # compiles cli/src -> cli/dist
export INVENTORY_API_URL=http://localhost:3000   # optional, this is the default
export INVENTORY_API_KEY=<key>                   # required; create it in the
                                                  # web UI under Settings -> API keys
node cli/bin/inventory.js --help

--api-url/--api-key override the env vars for a single call. For a shorter command, npm link in cli/ once and use inventory ... (or npx inventory ... from the repo root without linking).

Output, errors, exit codes

• Default output: compact single-line JSON on stdout.
• --table: human-readable padded columns instead (global flag, works on

every command).

• Errors: JSON on stderr, never on stdout: { "error": { "code", "message", "details"? } }.
• Exit codes: 0 ok · 1 API/generic error · 2 usage or validation error

(bad flags, bad --json, bad photos) · 3 auth error (missing/invalid API key) · 4 not found.

Commands

list

inventory list [--q <text>] [--type laptop|printer] [--status active|in_repair|retired]

Filters combine with AND. Output: { "items": Device[] }.

$ inventory list --type laptop --status active --table

get <id>

$ inventory get 3f9c1e2a

Output: a Device object. Exit 4 if the id doesn't exist.

create

inventory create --type <laptop|printer> --manufacturer <m> --model <m>
  [--serial <s>] [--asset-tag <t>] [--purchase-date YYYY-MM-DD] [--location <l>]
  [--status active|in_repair|retired] [--notes <n>] [--assigned-to <userId>]
  # laptop:  --cpu <c> --ram-gb <n> --storage-gb <n> --screen-size-inches <n> --os <name>
  # printer: --technology laser|inkjet|other [--color|--no-color] [--duplex|--no-duplex] [--network|--no-network]
  [--json <file|->]

Required: --type, --manufacturer, --model (or the matching keys in --json). --json - reads a full DeviceInput document from stdin; flags always override values from it, so you can pass a full document and tweak one field with a flag. Output: the created Device.

$ inventory create --type laptop --manufacturer Dell --model "Latitude 5440" \
    --cpu "Intel Core i7-1365U" --ram-gb 16 --storage-gb 512 --os "Windows 11 Pro"

update <id>

Same options as create. The API replaces the full document (PUT), so this command fetches the current device first, layers --json (if given) and then your flags on top of it — anything you don't mention keeps its current value. Output: the updated Device. Exit 4 if the id doesn't exist.

$ inventory update 3f9c1e2a --status in_repair --notes "Screen replacement"

delete <id>

No confirmation prompt. Output: { "deleted": "<id>" }. Exit 4 if the id doesn't exist.

$ inventory delete 3f9c1e2a

analyze <photos...>

Sends 1–5 photos (jpg, jpeg, png or webp, ≤ 5 MB each) to the LLM-based photo analysis endpoint and prints the proposal. Creates nothing.

$ inventory analyze front.jpg label.jpg
{"type":{"value":"laptop","confidence":"high","reasoning":"..."},"manufacturer":{...},
 "attributes":{"ramGb":{"value":16,"confidence":"medium","reasoning":"..."}},"summary":"..."}

--as-create-json converts the proposal into a DeviceInput skeleton (values only, confidence and reasoning dropped) for piping into create:

$ inventory analyze front.jpg --as-create-json | inventory create --json -

JSON shapes

• DeviceInput (create/update body, --json document): manufacturer,

model, serialNumber?, assetTag? (organisation-issued inventory number), purchaseDate? (YYYY-MM-DD), location?, status (active|in_repair|retired, default active), notes?, assignedToUserId?, attributes ({ type: "laptop", cpu?, ramGb?, storageGb?, screenSizeInches?, operatingSystem? } or { type: "printer", technology?, colorCapable?, duplexCapable?, networkCapable? }).

• Device: DeviceInput plus id, type, createdAt, updatedAt,

assignedToUserName?.

• AnalysisResult: optional type/manufacturer/model/serialNumber/

assetTag, each { value, confidence: "high"|"medium"|"low", reasoning }, plus attributes (same shape, keyed by attribute name) and a summary string. A field is absent, not null, when the LLM couldn't tell.

See src/lib/devices/schema.ts for the authoritative Zod schema (this CLI duplicates the plain-TypeScript shape in cli/src/types.ts).

Recommended agent workflow

1. Analyze: inventory analyze <photos...> to get a proposal with

confidence per field.

1. Review: check confidence — treat low/medium fields as

suggestions to verify, not facts. Read summary for context.

1. Create: inventory analyze <photos...> --as-create-json | inventory create --json -,

optionally overriding or filling in fields with flags (e.g. --location, --assigned-to, or a corrected --serial if the photo made it illegible).

For routine inventory management, skip step 1 and use create/update/ delete/list/get directly with flags.