HEIGHT: FLUID
SCAFFOLD COMMAND LINE INTERFACES
THAT AGENTS CAN DRIVE.[FLAGS · JSON · EXIT CODES]
Most CLIs ask questions and print decorated text. An agent can't answer a prompt or parse a banner. mkcmd-agent generates Bun + TypeScript CLIs that take flags, print one JSON object with --json, and exit 0, 1 or 2.
mkcmd-agent init --name my-cli --description "Does one thing well"
> Created my-cli
> 10 files: src/core/cli.ts, AGENTS.md, test/cli.test.ts ...
> Next: cd my-cli && bun install
An agent's first three calls
REF: B-02
FIG. A · LEARN THE CLI
my-cli describe
> {"name":"my-cli","commands":[{"name":"hello","usage":"my-cli hello --name <name> [flags]",
> "flags":[{"name":"--name","type":"string","required":true,...}],
> "examples":["my-cli hello --name Ada --json"]}]}
FIG. B · FAIL, THEN SUCCEED
my-cli hello --json
echo $?
my-cli hello --name Ada --json
> {"ok":false,"command":"hello","error":{"code":"usage","message":"Missing required flag: --name.","hint":"Example: my-cli hello --name Ada --json"}}
> 2
> {"ok":true,"command":"hello","result":{"greeting":"Hello, Ada!"}}
Component assembly
REF: B-03
01
Flags, not prompts
Every input is a flag. A missing required flag fails fast with exit 2 and a working example. Nothing waits on stdin.
02
One JSON object
--json prints {ok, command, result} or {ok: false, error: {code, message, hint}}. Logs go to stderr, so stdout always parses.
03
describe
Every command, flag, default and example as JSON. An agent reads it once instead of guessing at --help text.
04
Typed commands
defineCommand infers flag types from their specs. run returns data and throws CliError to fail. The framework does the rest.
05
add
mkcmd-agent add writes a command file and registers it. Nobody hand-edits the command list.
06
Tests and AGENTS.md
Generated projects ship subprocess tests of the contract and an AGENTS.md that tells the next agent how the CLI works.
Specifications
- RUNTIMEBUN
- LANGUAGETYPESCRIPT
- FRAMEWORK DEPENDENCIESNONE
- OUTPUTTEXT OR --JSON
- EXIT CODES0 / 1 / 2
- LICENSEMIT