rhythmjs

Search documentation

Search guides, the tutorial and every package.

On this page

RhythmCli#

new RhythmCli<I, D>(options?)#
Create a command router. It is a Pipeline, like Rhythm, with request-time middleware and commands but no startup phase. I is the context the cli needs from its host (checked when mounted) and D is what its own derive() calls add; both are usually inferred. Options are name, which labels failures (mounted cli "name" failed), and type (default "cli"). There is no prefix option.
cmd(command, ...handlers)#
Add a command: space-separated words, literal unless they start with :. :name is required, :name? optional (absent when not given), and :name+, :name* and **:name capture the remaining words as a string[]; a bare * or ** lands in params["0"]. Order is required, then optional, then at most one catch-all; anything else throws at registration. Matching uses the words before the first flag. Handlers compose left to right; the first may be a derive() that widens the context for the rest. Params are typed from the command string.
use(middleware)#
Add cli-level middleware. It wraps every command of this cli and runs only when a command matched, so a guard never answers an unknown command. ctx.params is untyped in it. A derive() widens the context type.
callback()#
The cli as a (ctx) => Promise<ctx> function, used by mount() and toCliHandler().
sources / parent / options#
Inherited from Pipeline.

A cli mounts into a Rhythm host with mount(cli) from @rhythmjs/rhythm, or runs on its own through toCliHandler(cli).

Context#

From @rhythmjs/cli/context.

RhythmCliContext#
The base context: argv, stdout, stderr and a writable exitCode. Output goes through the functions in @rhythmjs/cli/output: log(ctx, ...) (stdout), error(ctx, ...) (stderr) and fail(ctx, message, code = 1) (prints error: message to stderr and sets the exit code).
createCliContext(argv, io?)#
Build the base context. io is { stdout, stderr }, each with a write(text) method; it defaults to the process streams.

Running#

From @rhythmjs/cli/run.

toCliHandler(app, io?)#
Takes a RhythmCli, or a Rhythm host that mounts one, and returns (argv: string[]) => Promise<number>: the exit code. An unmatched command reports error: unknown command 'x' (exit code 2, or no command given); a thrown error is reported as an error line (exit code 1). It rejects at compile time an app that requires input the runner cannot supply.

Argv and prompts#

parseArgv(argv)#
From @rhythmjs/cli/argv. Returns { positionals, flags }. Flag values are strings or booleans; -- switches to raw positionals.
withParsedArgv()#
From @rhythmjs/cli/argv. A use() middleware that adds ctx.positionals and ctx.flags from ctx.argv.
withPrompt(createIO?)#
From @rhythmjs/cli/prompt. A use() middleware that adds ctx.prompt and closes its input when the command finishes. createIO supplies custom I/O and defaults to createStdioPromptIO.
createPrompt(io)#
From @rhythmjs/cli/prompt. Returns { prompt, close } for the given ask, write and optional close functions.
createStdioPromptIO()#
From @rhythmjs/cli/prompt. The default I/O: writes to process.stdout and reads lines through Bun's async-iterable console.
RhythmPrompt / RhythmPromptIO#
Prompt method and I/O interfaces exported from @rhythmjs/cli/prompt.

Subpath exports: @rhythmjs/cli, ./argv, ./prompt, ./context, and ./run. See interactive prompts and Running on Bun for examples.