@howells/cli

Agent-first CLI harness — structured JSON output, arg parsing, input hardening, and field filtering.

The shared foundation for @howells/thingscli, @howells/starlingcli, and @howells/linearcli.

Install

npm install @howells/cli

Usage

import { success, error, filterFields } from "@howells/cli";
import { flag, hasFlag, readJsonInput, getLimit, getFields, readResult } from "@howells/cli/args";
import { hardenId, validateTitle, validatePositiveInt, validateFields } from "@howells/cli/validate";

// Structured JSON output
success({ balance: "£1,481.14" }, "balance");
// → {"ok":true,"data":{"balance":"£1,481.14"},"command":"balance"}

error("No token found.", "balance");
// → {"ok":false,"error":"No token found.","command":"balance"}

// Arg parsing
const team = flag("team");        // --team ENG → "ENG"
const dryRun = hasFlag("dry-run"); // --dry-run → true
const json = readJsonInput("create"); // --json '{"title":"..."}' → parsed object

// Input hardening (defends against agent hallucinations)
hardenId("../../etc/passwd", "issue"); // exits with error
hardenId("ENG-123", "issue");          // passes

// Context window discipline
readResult("issues", data); // applies --fields and --limit automatically

API

Output (@howells/cli)

| Function | Description | |---|---| | success(data, command?, extra?) | Output JSON success envelope and exit | | error(message, command?) | Output JSON error envelope and exit | | filterFields(items, fields?) | Filter array of objects to specified fields |

Args (@howells/cli/args)

| Function | Description | |---|---| | flag(name) | Get --name value from argv | | hasFlag(name) | Check if --name is in argv | | getLimit(command) | Parse and validate --limit | | getFields(command) | Parse and validate --fields | | readJsonInput(command) | Parse --json '{...}' as object | | readResult(command, data, extra?) | Apply --fields + --limit and output |

Validate (@howells/cli/validate)

| Function | Description | |---|---| | hardenId(value, command, options?) | Reject path traversal, control chars, percent encoding, query params | | validateTitle(value, command, maxLength?) | Reject empty or overly long titles | | validatePositiveInt(value, field, command) | Parse and validate positive integers | | validateFields(value, command) | Validate comma-separated field names |

Design Principles

Built for the Agent DX CLI Scale:

1. Machine-readable output — JSON envelope on every path, including errors
2. Context window discipline — --fields and --limit are first-class
3. Input hardening — hardenId() defends against the specific ways agents fail (hallucinated paths, not typos)
4. Safety rails — readJsonInput() for raw payload input, hasFlag("dry-run") for validation

License

MIT