CLI API reference

RhythmCli#

new RhythmCli({ prefix? })#

Create a command controller with an optional space-separated prefix, joined onto every command registered on this instance. A cli does not extend Rhythm; it compiles commands and middleware down to a single middleware.

command(path, ...handlers)#

Add a command pattern with named :tokens captured into ctx.args. A trailing :token? is optional (left out of ctx.args when absent, e.g. "new :name?"), and a trailing ** captures the remaining arguments into ctx.args._, joined by spaces (e.g. "run :script **"). Order is required, then optional, then at most one **; anything else throws when the command is registered. One or more handlers compose left to right; a leading derive middleware types the context for the handlers after it.

use(fn)#

Add a middleware. It takes only functions; mount a nested cli as use(child.middleware()); the mount is opaque, so the child carries its own full prefix. A middleware wraps only the commands registered after it. There is no startup context or register(); startup values live on the host Rhythm app.

entries#

A read-only snapshot of registered middlewares and commands, in order.

middleware()#

Compile this cli to a plain middleware: the one form that mounts anywhere, into a Rhythm app or into another cli. The middleware is tagged with the cli as its source, so a parent module lists it in its sources.

RhythmCliContext and RhythmCliResponse are exported from @rhythmjs/cli/context. parseArgv and ParsedArgv are available from @rhythmjs/cli/argv.

Running, parsing, and prompts#

toCliHandler(app)#

From @rhythmjs/cli/run: takes the Rhythm host app and returns (argv: string[]) => Promise<number>. Piped stdin arrives via Bun.stdin.stream(); a TTY leaves ctx.stdin null.

createPrompt()#

From @rhythmjs/cli/run: returns { prompt, close }, reading answers through Bun's async-iterable console.

createPrompt(io)#

The lower-level @rhythmjs/cli/prompt export takes ask, write, and optional close functions.

parseArgv(argv)#

The @rhythmjs/cli/argv export returns { positionals, flags }. Flag values are strings or booleans; -- switches to raw positionals.

RhythmCliOptions / RhythmCliCommandContext#

Root type exports describing constructor options and matched command arguments (ctx.args).

RhythmPrompt / RhythmPromptIO#

Prompt method and I/O interfaces exported from @rhythmjs/cli/prompt.

Subpath exports: @rhythmjs/cli, ./argv, ./prompt, ./context, and ./run, plus the compatibility aliases ./adapters/context and ./adapters/bun. See interactive prompts and Running on Bun for examples and cleanup.