REPL Mode
Padrone includes a built-in REPL (Read-Eval-Print Loop) that lets users interactively run commands in a persistent session. The REPL supports command history, tab completion, scoped sessions, and customizable output formatting.
Starting a REPL
Section titled “Starting a REPL”Call .repl() on your program to start an interactive session. It returns an AsyncIterable that yields a result for each executed command:
import { createPadrone } from 'padrone';import * as z from 'zod/v4';
const program = createPadrone('myapp') .configure({ version: '1.0.0' }) .command('greet', (c) => c .arguments(z.object({ name: z.string() }), { positional: ['name'] }) .action((args) => `Hello, ${args.name}!`) ) .command('add', (c) => c .arguments(z.object({ a: z.number(), b: z.number() })) .action((args) => args.a + args.b) );
for await (const result of program.repl()) { // Each successfully executed command yields a result console.log(result.command.name, result.result);}Errors during execution are caught and printed to the terminal without crashing the session.
REPL from the CLI
Section titled “REPL from the CLI”Users can enter the REPL from the command line using the --repl flag (in cli() and eval(); for serve, MCP and tool() calls it’s an unknown option):
# Start REPLmyapp --repl
# Start REPL scoped to a subcommandmyapp --repl dbBuilt-in Commands
Section titled “Built-in Commands”All REPL built-in commands use a dot prefix to avoid collisions with user-defined commands:
| Command | Description |
|---|---|
.help |
Show REPL commands and keybindings |
.exit |
Exit the REPL |
.quit |
Exit the REPL (alias) |
.clear |
Clear the screen |
.history |
Show command history (with the saved history, when historyFile is set) |
.scope <cmd> |
Scope the session to a subcommand subtree |
.scope .. or .. |
Go up one scope level |
. |
Execute the current scoped command |
Scoped REPLs
Section titled “Scoped REPLs”Scoped REPLs let you focus on a subcommand tree. When scoped, commands are interpreted relative to the scope and the prompt updates to reflect it:
const program = createPadrone('myapp') .command('db', (c) => c .command('migrate', (c) => c .command('up', (c) => c.action(() => 'migrated up')) .command('down', (c) => c.action(() => 'migrated down')) ) .command('seed', (c) => c.action(() => 'seeded')) );
// Start scoped to 'db'for await (const result of program.repl({ scope: 'db' })) { // User types 'migrate up' instead of 'db migrate up'}The prompt reflects the current scope:
myapp ❯ .scope dbmyapp/db ❯ migrate up# Runs: db migrate upmyapp/db ❯ .scope migratemyapp/db/migrate ❯ up# Runs: db migrate upmyapp/db/migrate ❯ ..myapp/db ❯ .# Runs: db (executes the scoped command itself)myapp/db ❯ ..myapp ❯ .scope db migratemyapp/db/migrate ❯The scope option is strongly typed to valid command paths in your program.
A mistyped .scope target gets a suggestion (Unknown command: dbb / Did you mean "db"?), and inside a scope help <command> shows help for the scope’s commands (help migrate in db is help db migrate), with the same suggestions for a typo.
Tab Completion
Section titled “Tab Completion”The REPL provides tab completion for:
- Command names and subcommands
- Option names (e.g.,
--port,--host), including global options and the help flags - Aliases
Tab completion is enabled by default. Disable it with completion: false.
History
Section titled “History”The REPL supports up/down arrow key navigation through command history. You can provide initial history entries and view the session history with .history:
for await (const result of program.repl({ history: ['greet World', 'add --a 1 --b 2'],})) { // Up arrow cycles through history}historyFile keeps history between sessions: true stores it in repl_history under the program’s state directory (program.dirs.state, e.g. ~/.local/state/myapp on Linux), or pass a path. Entries are saved as they’re entered, one per line, and .history lists the saved ones too. historySize caps how many are kept (default 1000; 0 keeps none). The file is created readable only by the user (mode 0600), like shell history:
program.repl({ historyFile: true, historySize: 500 });Customizing the REPL
Section titled “Customizing the REPL”Prompt
Section titled “Prompt”program.repl({ prompt: 'app> ', // Or dynamic: prompt: () => `${getCurrentBranch()}> `,});The default prompt is the program name (bold in ANSI-capable terminals) and the scope path, followed by ❯: myapp/db ❯ .
Greeting and Hint
Section titled “Greeting and Hint”program.repl({ greeting: 'Welcome! Type a command to get started.', hint: 'Press Tab for completions, Ctrl+C twice to exit.',});Set greeting: false or hint: false to suppress them. The default greeting shows the program name and version. The default hint shows .help and .exit instructions.
Output Spacing
Section titled “Output Spacing”Control separators before and after command output:
program.repl({ // Blank line before and after each command output spacing: true,
// Repeated character spacing: '-', // Prints a line of dashes
// Several lines: a blank line, then a line of dashes spacing: [true, '-'],
// Independent before/after spacing: { before: true, after: '-', },});Output Prefix
Section titled “Output Prefix”Prefix each line of command output:
program.repl({ outputPrefix: '| ',});This adds | before each line of output, creating a visual distinction.
Exit Behavior
Section titled “Exit Behavior”- Type
.exitor.quitto exit gracefully. Plainexitandquitwork too, unless the program (or the current scope) has a command with that name, which then runs instead - Press Ctrl+D (end of input)
- Press Ctrl+C once to see an exit hint
- Press Ctrl+C twice to force exit
While a command runs inside the REPL (including one started with --repl or the repl command), Ctrl+C interrupts that command, not the session.
All REPL Options
Section titled “All REPL Options”| Option | Type | Default | Description |
|---|---|---|---|
prompt |
string | (() => string) |
"<name> ❯ " |
REPL prompt |
greeting |
string | false |
Program name + version | Welcome message |
hint |
string | false |
Help/exit instructions | Hint shown below greeting |
history |
string[] |
[] |
Initial history entries |
historyFile |
boolean | string |
none | File that keeps history between sessions (true: repl_history in program.dirs.state) |
historySize |
number |
1000 |
Most history entries kept (0: none) |
completion |
boolean |
true |
Enable tab completion |
spacing |
PadroneReplSpacing | { before?, after? } |
none | Output separators |
outputPrefix |
string |
none | Prefix for output lines |
scope |
string |
none | Start scoped to a command path |
runtime |
Partial<PadroneRuntime> |
none | Runtime overrides for the session (readLine, output, error, …) |
context |
TContext |
none | Context each command receives; the repl command and --repl pass on the one given to cli() |