CLI API reference
Command routing, argv parsing, prompts, and Bun runner exports for @rhythmjs/cli.
On this page
RhythmCli#
new RhythmCli<I, D>(options?)#- Create a command router. It is a
Pipeline, likeRhythm, with request-time middleware and commands but no startup phase.Iis the context the cli needs from its host (checked when mounted) andDis what its ownderive()calls add; both are usually inferred. Options arename, which labels failures (mounted cli "name" failed), andtype(default"cli"). There is noprefixoption. cmd(command, ...handlers)#- Add a command: space-separated words, literal unless they start with
:.:nameis required,:name?optional (absent when not given), and:name+,:name*and**:namecapture the remaining words as astring[]; a bare*or**lands inparams["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 aderive()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.paramsis untyped in it. Aderive()widens the context type. callback()#- The cli as a
(ctx) => Promise<ctx>function, used bymount()andtoCliHandler(). 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,stderrand a writableexitCode. Output goes through the functions in@rhythmjs/cli/output:log(ctx, ...)(stdout),error(ctx, ...)(stderr) andfail(ctx, message, code = 1)(printserror: messageto stderr and sets the exit code). createCliContext(argv, io?)#- Build the base context.
iois{ stdout, stderr }, each with awrite(text)method; it defaults to the process streams.
Running#
From @rhythmjs/cli/run.
toCliHandler(app, io?)#- Takes a
RhythmCli, or aRhythmhost that mounts one, and returns(argv: string[]) => Promise<number>: the exit code. An unmatched command reportserror: unknown command 'x'(exit code 2, orno 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. Ause()middleware that addsctx.positionalsandctx.flagsfromctx.argv. withPrompt(createIO?)#- From
@rhythmjs/cli/prompt. Ause()middleware that addsctx.promptand closes its input when the command finishes.createIOsupplies custom I/O and defaults tocreateStdioPromptIO. createPrompt(io)#- From
@rhythmjs/cli/prompt. Returns{ prompt, close }for the givenask,writeand optionalclosefunctions. createStdioPromptIO()#- From
@rhythmjs/cli/prompt. The default I/O: writes toprocess.stdoutand reads lines through Bun's async-iterableconsole. 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.