Interceptors & Extensions
Padrone’s architecture is built on two complementary systems:
- Extensions: Build-time composition — reusable bundles of commands, configuration, and interceptors applied via
.extend(). Most of Padrone’s built-in features (help, version, REPL, color, signal handling, auto-output, stdin, interactive, suggestions) are implemented as extensions. - Interceptors: Runtime phase interception — middleware that wraps the command lifecycle (parse, validate, execute, etc.) with an onion model. Extensions typically register interceptors under the hood.
This extension-first architecture means the core is minimal — features are layered on via the same .extend() and .intercept() APIs you use for your own code.
Architecture Overview
Section titled “Architecture Overview”When you call createPadrone('myapp'), built-in extensions are automatically applied:
| Extension | What it does | Interceptor Order |
|---|---|---|
| help | --help/-h flag, help command and <cmd> help, error-phase help display |
-1001.5 |
| version | --version flag (any command), -v/-V (root), version [--verbose] [--check] command |
-1000 |
| repl | --repl flag, repl command |
-1000 |
| color | --color[=always|never|auto|<theme>]/--no-color flag |
-1001 |
| suggestions | “Did you mean?” for unknown commands/options | -500 |
| signal | SIGINT/SIGTERM handling, double-tap force-exit (forceExitMs, onForceExit), AbortSignal propagation |
-2000 |
| autoOutput | Auto-print results (strings, promises, iterators) and, in cli(), errors the help extension didn’t print |
-1100 |
| stdin | Pipe stdin into argument fields (text, lines, or stream); not read for serve, MCP and tool() calls |
-1001 |
| interactive | --interactive/-i flag, auto-prompting for missing fields |
-999 |
Each can be disabled individually:
const program = createPadrone('myapp', { builtins: { repl: false, color: false },});Additional opt-in extensions are available for advanced features:
| Extension | Import | What it does |
|---|---|---|
padroneEnv(schema) |
'padrone' |
Parse environment variables into args (vars, or prefix for every option, APP_DB__HOST for nested ones (nestedSeparator); APP_TAGS=a,b for arrays (arraySeparator); empty variables count as unset unless allowEmpty) |
padroneConfig(options) |
'padrone' |
Load args from config files (xdg, searchParents ('project', stopDir), packageJson, merge, extends options; function configs with defineConfig(); $production overrides by envName), --profile profiles (profiles), per-command sections (sections), and a config get|set|unset|list|path|edit command (command, with --local/--file) |
padroneProgress(config) |
'padrone' |
Auto-managed progress indicators and progress.tasks() task lists (no-op for serve, MCP and tool() calls) |
padroneLogger(options) |
'padrone' |
Structured logging to stderr with levels (--verbose repeatable; shortFlags, env, stdout, format: 'json', redact, serializers, destination (one or several, each with its own level and format) options; child({ requestId }) bindings) |
padroneJson(options?) |
'padrone' |
--json flag: results and errors as JSON; --jq and --template filter and format the result; fields adds gh-style --json name,url |
padroneFormat(options?) |
'padrone' |
--output/-o <format>: text, json, yaml, csv, tsv or table; tableFlags adds --columns, --sort, --no-header; sanitize and csvFormulaEscape for untrusted data |
padroneConfirm(options?) |
'padrone' |
Confirmation prompt (or --yes, or <PROGRAM>_YES=1) before mutation: true commands; .configure({ confirm }) sets a command’s question (or false), nonInteractive: 'fail' | 'yes' | 'no' decides without a terminal |
padroneCredentials(options?) |
'padrone' |
Secret storage for actions (ctx.context.credentials.get/set/delete): the OS keychain (macOS security, Linux secret-tool), else a 0600 file; refused for serve, MCP and tool() calls unless remote: true |
padroneTiming() |
'padrone' |
Execution timing (--time; Done in … / Failed after …, format option) |
padroneUpdateCheck(config) |
'padrone' |
Background version checking (notice from the cached latest version; a stale cache refreshes in a detached process, so exit is never delayed) |
padroneUpgrade(options?) |
'padrone' |
Self-update command (upgrade, --check, --exit-code, --to, --channel; asks padroneConfirm() only when there is something to install; verify checks the release first) using the package manager the program was installed with |
padroneAliases(options?) |
'padrone' |
User-defined command aliases (alias set co checkout --force, $1/$@ placeholders), expanded before routing; alias import/export share them as YAML or JSON |
padroneResponseFiles(options?) |
'padrone' |
Response files: my-cli @args.txt reads arguments from args.txt (@@ escapes a leading @; relativeTo: 'file' for nested ones) |
padroneExternalCommands(options?) |
'padrone' |
Git-style external subcommands: my-cli foo runs my-cli-foo from PATH (see External Commands) |
padronePlugins(options?) |
'padrone' |
Plugins users install at runtime, with plugins list|install|uninstall|link (see Runtime Plugins) |
padroneInk() |
'padrone/ink' |
React (Ink) rendering support; remote: 'exit' returns an app’s last frame to serve, MCP and tool() calls |
padroneMcp() |
'padrone/mcp' |
MCP server integration |
padroneServe() |
'padrone/serve' |
REST server integration |
padroneTracing(config) |
'padrone/tracing' |
OpenTelemetry tracing (pass api: { context, trace } for span parenting); spans are named <caller> <command>, with a server kind for serve and MCP |
padroneCompletion(options?) |
'padrone/completion' |
Shell completion generation (dynamic, with descriptions, field complete callbacks, .configure({ complete }) hooks and hints; mode: 'static', descriptions: false) |
padroneMan(options?) |
'padrone/man' |
Man page generation: the version and date (SOURCE_DATE_EPOCH when set) in .TH, parent and subcommand pages under SEE ALSO; section and install dir |
Extensions
Section titled “Extensions”An extension is a function that receives a builder and returns a modified builder. Extensions can add commands, arguments, interceptors, and configuration — anything the builder supports.
Using Extensions
Section titled “Using Extensions”Apply extensions with .extend():
import { createPadrone, padroneEnv, padroneConfig, padroneProgress } from 'padrone';
const program = createPadrone('myapp') .extend(padroneEnv(envSchema)) .extend(padroneConfig({ files: 'app.config.json' })) .command('deploy', (c) => c .extend(padroneProgress('Deploying...')) .action(async () => { /* ... */ }) );Extensions compose naturally — chain multiple .extend() calls to layer functionality. Extensions applied at the program level affect all commands; extensions applied inside a .command() callback affect only that command.
Output Formats
Section titled “Output Formats”padroneJson() adds --json (with --jq and --template), and padroneFormat() adds --output/-o <format>:
import { createPadrone, padroneFormat, padroneJson } from 'padrone';
const program = createPadrone('myapp') .extend(padroneJson({ fields: true })) .extend(padroneFormat({ tableFlags: true, columns: { id: 'ID', name: 'Name' } })) .command('users', (c) => c.action(() => fetchUsers()));
// myapp users --json=id,name only these fields of each user// myapp users --jq '.[] | select(.admin) | [.id, .name] | @tsv'// myapp users -o yaml// myapp users -o csv --columns id,name --sort -createdAt --no-header// myapp users -o tableField selection. With fields: true, --json=a,b keeps only those keys of the result (of each item, for arrays and streamed items); --jq and --template then apply to what’s left. The list must be attached with = so --json never takes the next argument (myapp user --json 42 keeps 42 as a positional). With fields: 'required' (like gh), --json a,b also works, and a bare --json fails with Specify one or more comma-separated fields for --json: …. The available fields are availableFields when given (a list, or (command) => list | undefined), checked before the command runs; otherwise they’re the keys of the result, checked when it’s printed.
jq. --jq runs a built-in subset of jq on the JSON result, like gh --jq: paths (.a.b, .[0], .[2:4], .[], ?), pipes, ,, //, and/or/not, comparisons, arithmetic (+ - * / % with jq’s rules for strings, arrays and objects), if … then … elif … else … end, variables (.id as $id | …, {$id}), array and object construction, and the common builtins: select, map, sort_by, group_by, unique_by, min_by/max_by, min/max, keys, length, has, add, join, split, ltrimstr/rtrimstr, startswith/endswith, test, sub/gsub (with jq’s regex flags: test("x"; "i")), to_entries/from_entries, tostring/tonumber/tojson/fromjson and more, with_entries, generators (range, limit(n; f), first(f)/last(f), any/all with a generator and condition, recurse/.., values/nulls/scalars and the other type selectors), paths (paths, paths(f), leaf_paths, getpath, setpath, delpaths, tostream), $ENV/env, error, string interpolation ("\(.name) (\(.id))"), plus the @csv, @tsv, @json, @text, @html, @uri, @sh, @base64 and @base64d formats, also applied to each value interpolated into a string (@sh "rm \(.path)"). It’s lazy, so first(f) and limit stop the generator early. Strings print raw and other values as JSON: compact, one per line, when stdout isn’t a terminal, and indented on one. Every run has a step budget, so a runaway expression like [range(1e9)] fails fast with an error: jqLimits: { maxSteps, remoteMaxSteps } sets it (10_000_000 by default, 1_000_000 for serve, MCP and tool() calls, which also see an empty $ENV, so a remote client can’t read the server’s environment). Pass jq: (input, expression, { env }) => outputs to plug in a full implementation.
Formats. text (the default) is how auto-output prints results without the extension; json is the same as a bare --json that prints every field (errors print as JSON too); yaml uses a small built-in emitter (streamed items as --- documents); csv (RFC 4180 quoting) and tsv (tabs and newlines escaped as \t/\n) print an object, or an array of objects, as rows under a header, and streamed items one row each (the header comes from the first item); table renders the rows with the table primitive (a stream is rendered when it ends; a cell with newlines takes several lines). A string result (such as --help or --version) prints as text under every format but json, and any other result that isn’t an object prints as text under csv, tsv and table. Options: formats restricts the accepted list, default sets the format without -o, flags renames the flag (['output', 'o']), tableFlags adds --columns a,b (pick and order), --sort <column> (-column for descending; sorted streams wait for the end) and --no-header for table, csv and tsv; unknown columns are errors. columns: { id: 'ID', createdAt: 'Created' } sets the default columns, in order, with their header labels (or pass (command) => columns | undefined for per-command columns); --columns can still pick any key. pipedTable: 'tsv' prints -o table as tab-separated rows when stdout isn’t a terminal, like gh, so scripts get one line per row; it’s opt-in because -o table asks for a table, and by default one is printed wherever it goes. csvLineEnding: 'crlf' ends csv lines with \r\n (RFC 4180). For data you don’t control, sanitize: true strips terminal escape sequences (colors, cursor moves, OSC titles and hyperlinks) and control characters from the values yaml, csv, tsv and table print, like go-gh’s asciisanitizer (tabs and line breaks stay; the table primitive takes the same sanitize option), and csvFormulaEscape: true puts a ' before csv/tsv cells that start with =, +, -, @, a tab or a carriage return, so spreadsheets don’t run them as formulas (OWASP CSV injection); numbers like -5 stay as they are. Both are off by default.
Under JSON output, an error’s message leaves out the “Did you mean” hint, which is in suggestions instead. --json, --jq and --template take precedence over -o. Serve, MCP and tool() calls get raw results either way. A command’s own --output/-o option wins over the extension’s.
Credential Storage
Section titled “Credential Storage”padroneCredentials() keeps tokens and API keys for the program, like gh auth or keytar. Actions get ctx.context.credentials with async get(name), set(name, secret), delete(name), list() and backend():
import { createPadrone, padroneCredentials } from 'padrone';
const program = createPadrone('my-cli') .extend(padroneCredentials()) .command('login', (c) => c.action(async (_, ctx) => { await ctx.context.credentials.set('github', await ctx.prompt.password('GitHub token')); return `Saved to ${await ctx.context.credentials.backend()}`; }), ) .command('logout', (c) => c.action((_, ctx) => ctx.context.credentials.delete('github')));Backends. backend: 'auto' (the default) uses the OS keychain when its tool works, else a file:
- macOS: the login keychain through
/usr/bin/security(generic passwords,-s <service> -a <name>). The secret is written withsecurity -ion stdin (hex-encoded with-X), so it never shows up inps; the service and name do, and can’t contain quotes or backslashes. Secrets that aren’t printable ASCII are stored base64-encoded behind apadrone-base64:prefix, assecuritywould print them in hex. - Linux (and the BSDs): the Secret Service (GNOME Keyring, KWallet) through libsecret’s
secret-tool, with keytar’sservice/accountattributes; the secret goes through stdin. Withoutsecret-toolor a reachable Secret Service (a headless session without D-Bus), it falls back to the file. - Windows: no keychain support (the Credential Manager has no CLI that reads secrets); the file is used.
- The file:
credentials.jsoninprogram.dirs.data(orfile),{ [service]: { [name]: secret } }, written atomically with mode0600in a0700directory. Secrets are plain text there, readable by the user’s own processes, likegh’shosts.yml.
backend: 'keychain' fails where there’s no keychain instead of falling back, 'file' always uses the file, and a PadroneCredentialBackend object ({ name, get, set, delete, list? }, each taking the service and the name; list(service) gives credentials.list()) stores secrets anywhere else. service defaults to the program name. Tools are spawned with argv, never through a shell; runner replaces the spawner (tests pass a fake so they never touch the real keychain), and platform overrides process.platform.
Remote callers. Serve, MCP and tool() calls get a credentials object whose methods reject (Credentials aren't available to "mcp" calls), so a command that reads a token can’t hand it to an HTTP client or an AI model. Pass remote: true when commands only use the secrets themselves (e.g. to call an API) and never return them.
Writing Custom Extensions
Section titled “Writing Custom Extensions”A PadroneExtension is a function (builder) => builder:
import type { PadroneExtension } from 'padrone';
// Simple extension that adds a shared interceptorconst withLogging = (builder) => builder.intercept(defineInterceptor({ name: 'logger' }, () => ({ execute: (ctx, next) => { console.log(`Running: ${ctx.command.name}`); return next(); }, })));
// Extension that adds commands and configurationconst withAdmin = (builder) => builder .command('admin', (c) => c .command('status', (s) => s.action(() => 'healthy')) .command('reset', (s) => s.configure({ mutation: true }).action(() => 'reset')) );
const program = createPadrone('myapp') .extend(withLogging) .extend(withAdmin);Interceptors that ask the user something use createPrompt(ctx) from 'padrone' with any phase context: the same text/password/confirm/select/multiselect/group kit actions get as ctx.prompt, which returns defaults or throws a PromptUnavailableError where it can’t ask (see Interactive Prompting).
Extension Pattern: Interceptor + Command
Section titled “Extension Pattern: Interceptor + Command”Most built-in extensions follow this pattern — register a command (if needed) and an interceptor:
function myFeature(options?: MyOptions) { return (builder) => builder .command('my-feature', (c) => c.configure({ hidden: true }).action(() => { /* ... */ }) ) .intercept(myFeatureInterceptor(options));}Runtime Plugins
Section titled “Runtime Plugins”Extensions are applied when the program is built. padronePlugins() lets users add their own at runtime, like oclif’s plugins: a plugin is a module that default-exports an extension (or a program, mounted under its name), and the plugins are loaded at startup, before routing, so their commands route, show in help and complete like the program’s own.
import { padronePlugins } from 'padrone';
createPadrone('my-cli').extend(padronePlugins({ command: true })).cli();// my-cli-plugin-deploy/index.js: a pluginexport default (program) => program.command('deploy', (c) => c.arguments(z.object({ env: z.string() })).action((args) => `Deployed to ${args.env}`));my-cli plugins install my-cli-plugin-deploy # installs it into the plugins directory with the package managermy-cli plugins link ../my-cli-plugin-deploy # or uses a local checkout, while developing itmy-cli plugins list # --json for scriptsmy-cli plugins info my-cli-plugin-deploymy-cli plugins update # or one plugin by namemy-cli deploy --env prodmy-cli plugins uninstall my-cli-plugin-deployPlugins are recorded in plugins.json in the plugins directory (plugins under program.dirs.data by default, or dir); packages lists plugins the program always loads. A plugin that fails to load is reported on stderr and skipped. Plugins run with the program’s permissions, so installed ones are pinned: plugins.json records each one’s version and a SHA-256 of its module file, and one that changed since (plugins update re-records them) isn’t loaded. allow restricts installable names (['my-cli-plugin-*', '@acme/*']), ignoreScripts skips install scripts, a plugin may declare the padroneApi semver range it needs (checked against apiVersion), and one that redefines a command the program has is refused unless override is set. The plugins commands are built-in and only run on the command line. In tests, pass exec (runs the package manager) and import (loads a module) so nothing is installed. The loader is a start-phase interceptor that applies the plugins to the program and continues with next({ program }), which runs the rest of the pipeline on the program with the plugins; with no plugins, a sync program stays sync. See padronePlugins().
External Commands
Section titled “External Commands”padroneExternalCommands() gives a program git-style external subcommands, like cargo or clap’s allow_external_subcommands: my-cli foo --bar runs the executable my-cli-foo from PATH with --bar, with the terminal’s stdio, and exits with its exit code. They’re spawned without a shell, only for local callers (never for serve, MCP or tool()), and listed in help under “External Commands” and in shell completion. The program’s own commands always win, and when there’s no such executable the usual “Unknown command” error follows. Options: prefix (default '<program>-'), path (default the PATH variable), list, env (the variables they inherit: names, PREFIX_* patterns or a function; default all), and spawn to run them yourself (in tests, for example). See padroneExternalCommands().
Lifecycle Hooks
Section titled “Lifecycle Hooks”For code that runs around every action of a command subtree, .hook() is simpler than an interceptor, like cobra’s PersistentPreRun / PersistentPostRun or commander’s hook('preAction'):
program .globalArgs(z.object({ token: z.string().optional() })) .hook('preAction', async (ctx) => { // Runs before the action of every command below, after validation if (!ctx.args.token && ctx.command.path !== 'login') throw new Error('Run "my-cli login" first'); }) .hook('postAction', (ctx, result) => { // Runs after a successful action, with its result audit(ctx.command.path, result); });An ancestor’s preAction runs before a descendant’s and its postAction after; postAction is skipped when the action fails. Handlers get the action context plus args (typed as the command’s own, which its global args always match) and dryRun. Async hooks are awaited. Under the hood each hook is an execute-phase interceptor on the command (inherited by its subcommands, innermost), so hooks run inside interceptors such as padroneConfirm(), for dry runs and for run(). See .hook().
Interceptors
Section titled “Interceptors”Interceptors let you intercept the command lifecycle using a middleware pattern. They wrap each phase with an onion model, giving you full control to modify inputs, short-circuit execution, add logging, or implement cross-cutting concerns.
The full lifecycle is: start → parse → route → validate → execute → shutdown (with error on failure).
Defining Interceptors with defineInterceptor()
Section titled “Defining Interceptors with defineInterceptor()”The recommended way to create interceptors is with defineInterceptor(). It returns a factory function that creates fresh phase handlers per execution, enabling cross-phase state sharing via closures:
import { defineInterceptor } from 'padrone';
const auditInterceptor = defineInterceptor({ name: 'audit', order: 10 }, () => { // Closure state — fresh per execution, shared across phases let startTime: number;
return { start: (ctx, next) => { startTime = Date.now(); return next(); }, execute: (ctx, next) => { const result = next(); auditLog({ command: ctx.command.name, duration: Date.now() - startTime }); return result; }, };});The first argument is metadata (name, order, optional id). The second argument is a factory function that returns phase handlers.
Metadata properties:
| Property | Type | Description |
|---|---|---|
name |
string |
Display name for the interceptor |
order |
number |
Execution order — lower = outermost (default: 0) |
id |
string |
Deduplication key — when multiple interceptors share an id, the last one wins |
disabled |
boolean |
Skip this interceptor during execution |
inherit |
boolean |
When false, applies only to the command it’s registered on (default: true) |
options |
Record<string, OptionArity> |
Options the interceptor reads from rawArgs that aren’t in the command’s schema, keyed by long name or single-char flag. Tells the parser whether each takes a value: 'flag', 'value', 'optional' or 'array' |
env |
Record<string, string | string[]> | (arg, command) => string | string[] | undefined |
Environment variables the interceptor reads into args, keyed by arg name (or a function of the arg and the command whose help is shown). Shown in help as (env: NAME) for the command’s own options |
helpOptions |
HelpArgumentInfo[] | (command) => HelpArgumentInfo[] |
Options (from options) listed in the help of the commands the interceptor applies to, e.g. { name: 'profile', type: 'string', optional: true, description: '...' } |
async |
boolean |
The interceptor may make the validate phase async (e.g. loading files). Commands it applies to count as async at runtime, so they aren’t warned about returning a Promise from validation |
callers |
PadroneCaller[] |
Run only for these callers ('cli', 'eval', 'run', 'repl', 'serve', 'mcp', 'tool'); skipped for the others, like disabled. LOCAL_CALLERS and REMOTE_CALLERS are exported. It still counts as registered for requires |
on |
Record<string, handler> |
Custom event handlers keyed by event id (.on(event, handler) adds one with a typed payload; see Custom Events) |
extraCommands |
(command) => { name, description?, group? }[] |
Commands the interceptor runs that aren’t in the command tree (e.g. from a commandNotFound handler), under command: listed in help on the command line and offered by shell completion |
If your interceptor reads its own flag from rawArgs (like the built-in --help or --config), declare it in options so the parser knows how to read it. A flag option given a value (--yes=false) arrives as that string, so treat false, 'false', '0', 'no' and 'off' as off. For example, options: { profile: 'value', p: 'value' } makes --profile dev deploy read dev as the value and still route to deploy. The command’s own schema takes precedence when both define the same name.
Simple Interceptor Objects
Section titled “Simple Interceptor Objects”For simple cases, you can also pass an object directly to .intercept():
const logger: PadroneInterceptor = { name: 'logger', execute: (ctx, next) => { console.log(`Running: ${ctx.command.name}`); const result = next(); console.log(`Done: ${ctx.command.name}`); return result; },};
program.intercept(logger);Registering Interceptors
Section titled “Registering Interceptors”Use .intercept() on programs or individual commands:
const program = createPadrone('myapp') .intercept(logger) // Applies to all commands .command('deploy', (c) => c .intercept(deployGuard) // Only applies to 'deploy' .arguments(schema) .action(handler) );.intercept() is immutable — it returns a new builder with the interceptor added.
Execution Phases
Section titled “Execution Phases”Interceptors can hook into seven phases — four core phases (parse, route, validate, execute) and three lifecycle phases (start, error, shutdown):
Start Phase
Section titled “Start Phase”Runs before everything else, wrapping the entire pipeline. Only root-level interceptors run during start — subcommand interceptors are not invoked. Available in eval() and cli() only (not parse() or run()).
const startup = defineInterceptor({ name: 'startup' }, () => ({ start: (ctx, next) => { console.log('Starting up...'); const result = next(); // Runs the full parse → validate → execute pipeline console.log('Pipeline complete'); return result; },}));Context:
| Property | Type | Description |
|---|---|---|
command |
PadroneCommand |
The root command |
input |
string | string[] | undefined |
Raw CLI input: the string passed to eval()/REPL, or the argv array from cli() (each entry one token) |
signal |
AbortSignal |
Cancellation signal (provided by the signal extension) |
context |
unknown |
User-provided context from cli()/eval() |
caller |
string |
Invocation method ('cli', 'eval', 'repl', etc.) |
auth |
unknown |
Who made the request: what serve/MCP’s auth returned, or eval()’s auth (undefined if unknown) |
runtime |
ResolvedPadroneRuntime |
The resolved runtime |
program |
AnyPadroneProgram |
The root program |
Result: The full pipeline result (passed through from parse → validate → execute).
Parse Phase
Section titled “Parse Phase”Runs when CLI input is being parsed into a command and raw arguments. Only root-level interceptors run during parsing — subcommand interceptors are not invoked.
An interceptor that reads its own flags from rawArgs in the parse phase (like --verbose) should also read them in the validate phase when parse didn’t run, so it works when applied to a single command. The built-in logger, timing and --json extensions do this.
const parseLogger = defineInterceptor({ name: 'parse-logger' }, () => ({ parse: (ctx, next) => { console.log('Input:', ctx.input); const result = next(); console.log('Parsed command:', result.command.name); return result; },}));Context:
| Property | Type | Description |
|---|---|---|
command |
PadroneCommand |
The root command |
input |
string | string[] | undefined |
Raw CLI input: the string passed to eval()/REPL, or the argv array from cli() (each entry one token) |
signal |
AbortSignal |
Cancellation signal |
context |
unknown |
User-provided context from cli()/eval() |
caller |
string |
Invocation method |
auth |
unknown |
Who made the request: what serve/MCP’s auth returned, or eval()’s auth (undefined if unknown) |
Result:
| Property | Type | Description |
|---|---|---|
command |
PadroneCommand |
Resolved command |
rawArgs |
Record<string, unknown> |
Parsed raw arguments |
positionalArgs |
string[] |
Positional argument values |
Route Phase
Section titled “Route Phase”Runs after the target command is resolved (post-parse), before validation. Both root and command-level interceptors participate. Use for per-command setup like authorization checks, resource loading, or logging.
const auth = defineInterceptor({ name: 'auth' }, () => ({ route: (ctx, next) => { if (ctx.command.meta?.requiresAuth && !isAuthenticated()) { throw new Error('Not authenticated'); } return next(); },}));Context:
| Property | Type | Description |
|---|---|---|
command |
PadroneCommand |
Resolved target command |
rawArgs |
Record<string, unknown> |
Parsed raw arguments |
positionalArgs |
string[] |
Positional argument values |
signal |
AbortSignal |
Cancellation signal |
context |
unknown |
User-provided context |
caller |
string |
Invocation method |
auth |
unknown |
Who made the request: what serve/MCP’s auth returned, or eval()’s auth (undefined if unknown) |
Result: void
Validate Phase
Section titled “Validate Phase”Runs after routing, when raw arguments are being validated against the schema.
const defaults = defineInterceptor({ name: 'inject-defaults' }, () => ({ validate: (ctx, next) => { // Inject values before validation ctx.rawArgs.region ??= 'us-east-1'; return next(); },}));Context:
| Property | Type | Description |
|---|---|---|
command |
PadroneCommand |
Resolved command |
rawArgs |
Record<string, unknown> |
Mutable raw arguments — modify before next() |
positionalArgs |
string[] |
Positional argument values |
signal |
AbortSignal |
Cancellation signal |
context |
unknown |
User-provided context |
caller |
string |
Invocation method |
auth |
unknown |
Who made the request: what serve/MCP’s auth returned, or eval()’s auth (undefined if unknown) |
Result:
| Property | Type | Description |
|---|---|---|
args |
unknown |
Validated arguments |
argsResult |
StandardSchemaV1.Result |
Full validation result |
Execute Phase
Section titled “Execute Phase”Runs when the command’s action handler is being invoked.
const timer = defineInterceptor({ name: 'timer' }, () => ({ execute: (ctx, next) => { const start = performance.now(); const result = next(); const duration = performance.now() - start; console.log(`Completed in ${duration.toFixed(0)}ms`); return result; },}));Context:
| Property | Type | Description |
|---|---|---|
command |
PadroneCommand |
Resolved command |
args |
unknown |
Mutable validated arguments — modify before next() |
dryRun |
boolean | undefined |
true under --dry-run: the command’s dry-run handler runs instead of its action. Skip your own side effects |
signal |
AbortSignal |
Cancellation signal |
context |
unknown |
User-provided context |
caller |
string |
Invocation method |
auth |
unknown |
Who made the request: what serve/MCP’s auth returned, or eval()’s auth (undefined if unknown) |
Result:
| Property | Type | Description |
|---|---|---|
result |
unknown |
Action handler return value (the dry-run handler’s under --dry-run) |
Error Phase
Section titled “Error Phase”Called when the pipeline throws an error. Error handlers can log, transform, or suppress errors. Only runs for eval() and cli(). Runs in two layers: command-level error handlers run first (for route/validate/execute failures), then root-level error handlers (for all failures including parse).
const errorReporter = defineInterceptor({ name: 'error-reporter' }, () => ({ error: (ctx, next) => { // Log and pass through reportToSentry(ctx.error); return next(); },}));
const errorRecovery = defineInterceptor({ name: 'error-recovery' }, () => ({ error: (ctx, next) => { // Suppress the error and return a fallback result if (ctx.error instanceof NetworkError) { return { error: undefined, result: cachedValue }; } // Transform the error return { error: new AppError('Something went wrong', { cause: ctx.error }) }; },}));Context:
| Property | Type | Description |
|---|---|---|
command |
PadroneCommand |
The resolved command (target command for command-level, root for root-level) |
error |
unknown |
The error that was thrown |
signal |
AbortSignal |
Cancellation signal |
context |
unknown |
User-provided context |
caller |
string |
Invocation method |
auth |
unknown |
Who made the request: what serve/MCP’s auth returned, or eval()’s auth (undefined if unknown) |
Result:
| Property | Type | Description |
|---|---|---|
error |
unknown | undefined |
The error to throw. Set to undefined to suppress. |
result |
unknown |
Replacement result when suppressing the error. |
Calling next() passes to the next error handler. The innermost core returns { error } unchanged, which re-throws after shutdown runs. Command-level error handlers can suppress errors before they reach root-level handlers.
Shutdown Phase
Section titled “Shutdown Phase”Always runs after the pipeline completes — whether it succeeded or failed. Use for cleanup like closing connections or flushing logs. Only runs for eval() and cli(). Runs in two layers: command-level shutdown handlers run first (for the route/validate/execute scope), then root-level shutdown handlers (for the full pipeline scope). When the command fails, its shutdown handlers run once the error has been through the root-level error handlers (which print it in cli()), so a command-level padroneTiming() reports after the error, like a root-level one. A command-level shutdown handler that throws doesn’t skip the root-level ones; its error is rethrown after them.
const cleanup = defineInterceptor({ name: 'cleanup' }, () => ({ shutdown: (ctx, next) => { if (ctx.error) { console.error('Failed:', ctx.error); } db.close(); return next(); },}));Context:
| Property | Type | Description |
|---|---|---|
command |
PadroneCommand |
The resolved command (target command for command-level, root for root-level) |
error |
unknown | undefined |
The error, if the pipeline failed |
result |
unknown | undefined |
The pipeline result, if it succeeded |
signal |
AbortSignal |
Cancellation signal |
context |
unknown |
User-provided context |
caller |
string |
Invocation method |
auth |
unknown |
Who made the request: what serve/MCP’s auth returned, or eval()’s auth (undefined if unknown) |
Middleware Order
Section titled “Middleware Order”Interceptors compose as an onion — the first registered interceptor is the outermost wrapper:
program .intercept(interceptorA) // Outermost — runs first on entry, last on exit .intercept(interceptorB) // Inner .intercept(interceptorC); // Innermost — runs last on entry, first on exitProgram-level interceptors always wrap subcommand interceptors:
Program interceptors (outermost) → Subcommand interceptors (inner) → Action handler (core)Explicit Ordering
Section titled “Explicit Ordering”Use the order property to control position. Lower values run as outermost wrappers:
const auth = defineInterceptor({ name: 'auth', order: -10 }, () => ({ execute: (ctx, next) => { if (!isAuthenticated()) throw new Error('Not authenticated'); return next(); },}));
const metrics = defineInterceptor({ name: 'metrics', order: 10 }, () => ({ execute: (ctx, next) => { const result = next(); reportMetrics(ctx.command.name); return result; },}));Interceptors with the same order (default: 0) preserve their registration order.
Built-in extensions use negative orders to ensure they wrap user interceptors:
-2000 signal (outermost)-1100 autoOutput-1001.5 help-1001 color, stdin-1000 version, repl-999 interactive-500 suggestions 0 user interceptors (default)Deduplication with id
Section titled “Deduplication with id”When multiple interceptors share the same id, the last one wins. This lets you override built-in behavior. It holds across the root and a command too: a command-level interceptor with the id of a root one replaces it for the route, validate, execute, error and shutdown phases of that command (the root one still runs start and parse, which only root interceptors take part in):
// The built-in auto-output interceptor has id: 'padrone:auto-output'// Override it to disable for a specific command:builder.intercept(defineInterceptor({ name: 'no-auto-output', id: 'padrone:auto-output', disabled: true,}, () => ({})));Cross-Phase State
Section titled “Cross-Phase State”Use the defineInterceptor factory’s closure to share state across phases within a single execution. Each execution gets a fresh factory call, so state is isolated:
const auditInterceptor = defineInterceptor({ name: 'audit' }, () => { let startTime: number; let parsedCommand: string;
return { parse: (ctx, next) => { startTime = Date.now(); const result = next(); parsedCommand = result.command.name; return result; }, execute: (ctx, next) => { const result = next(); auditLog({ command: parsedCommand, duration: Date.now() - startTime }); return result; }, };});Short-Circuiting
Section titled “Short-Circuiting”Return early without calling next() to skip the rest of the chain:
const dryRun = defineInterceptor({ name: 'dry-run' }, () => ({ execute: (ctx, next) => { if (ctx.args.dryRun) { console.log('Dry run — skipping execution'); return { result: undefined }; } return next(); },}));Overriding Phase Inputs
Section titled “Overriding Phase Inputs”Pass overrides to next() to modify values for downstream interceptors:
const signalInterceptor = defineInterceptor({ name: 'signal' }, () => ({ start: (ctx, next) => { const controller = new AbortController(); // Downstream phases see the new signal return next({ signal: controller.signal }); },}));This is how the built-in signal extension propagates the AbortSignal — it creates an AbortController in the start phase and passes the signal downstream via next({ signal }).
Context-Providing Interceptors
Section titled “Context-Providing Interceptors”Interceptors can declare what they add to the context using .provides() and what they require with .requires(). The types have no runtime effect but enable typed ctx.context access:
const withDb = defineInterceptor({ name: 'with-db' }) .provides<{ db: Database }>() .factory(() => ({ execute: (ctx, next) => { const db = createDatabase(); return next({ context: { db } }); // merged into the existing context }, }));
// When this interceptor is registered, ctx.context.db is typedThe padroneProgress() extension uses this pattern — it declares .provides<{ progress: PadroneProgress }>() so ctx.context.progress is fully typed when the extension is applied.
Pass interceptor ids to .requires() (or requires in the meta) to also check at runtime that they’re registered on the command or a parent. A command that runs without one fails with Interceptor "audit" requires "padrone:logger", which isn't registered on this command or its parents:
const audit = defineInterceptor({ name: 'audit' }) .requires<{ logger: PadroneLogger }>('padrone:logger') .factory(() => ({ execute: (ctx, next) => { ctx.context.logger.info(`running ${ctx.command.path}`); return next(); }, }));Custom Events
Section titled “Custom Events”Extensions can talk to each other through custom events, like oclif’s runHook. Define an event with its payload type, handle it with .on() on an interceptor, and emit it with ctx.emit() from an action or an interceptor phase:
import { defineEvent, defineInterceptor } from 'padrone';
export const deployed = defineEvent<{ env: string; version: string }>('myapp:deployed');
const slack = defineInterceptor({ name: 'slack' }).on(deployed, async (payload, ctx) => { await postToSlack(`Deployed ${payload.version} to ${payload.env}`);});
program .intercept(slack) .command('deploy', (c) => c.action(async (args, ctx) => { const version = await deploy(args.env); await ctx.emit(deployed, { env: args.env, version }); }), );ctx.emit() runs the handlers of the interceptors on the running command’s chain (root and command-level, skipping disabled ones, non-inherited ones from parents and those callers filters out), one after another in interceptor order, and resolves once they’ve all run; a handler’s error rejects it. Handlers get the payload and a context with the command, runtime, context, caller, signal, program and emit. program.emit(event, payload) emits outside any execution, to the root’s interceptors (caller: 'run'). Handlers can also be given in the meta: on: { [deployed.id]: handler } (the payload is then untyped). .on() returns a new interceptor (same id, meta and factory) and leaves the one it’s called on unchanged, so adding a handler to a shared, exported interceptor doesn’t affect other programs using it; the same goes for .requires().
Command Not Found
Section titled “Command Not Found”commandNotFound is a built-in event emitted when routing finds no command for a name (my-cli deploi, or my-cli db migrat under a group), like oclif’s command_not_found hook. A handler can run something in its place with event.handle(action), or route another input with event.reroute(input); if none does, the usual “Unknown command” error follows, with “Did you mean” suggestions (event.suggestions has them too). padroneExternalCommands() is built on it.
import { commandNotFound, defineInterceptor, LOCAL_CALLERS } from 'padrone';
const legacy = defineInterceptor({ name: 'legacy-names' }).on(commandNotFound, (event) => { // `my-cli publish …` was renamed to `my-cli release …` if (event.name === 'publish') event.reroute(['release', ...event.args]);});
const fallback = defineInterceptor({ name: 'fallback', callers: LOCAL_CALLERS }).on(commandNotFound, (event) => { if (event.command.parent) return; // top-level names only event.handle((ctx) => runScript(event.name, event.args, ctx.signal));});event.args holds the words typed after the name, as typed; event.command is the command it was looked up in. The action given to handle() runs through the execute interceptors of that command’s chain, and its return value is the run’s result. The event is only emitted when a handler is registered, so a program without one stays synchronous. Interceptors can also list the commands they run this way in help and completion with the extraCommands meta.
Sync Preservation
Section titled “Sync Preservation”Interceptors preserve sync/async behavior. If your interceptor and all inner interceptors are synchronous, the entire chain stays synchronous. Only return a Promise when you need async operations:
// Sync interceptor — chain stays syncconst syncInterceptor = defineInterceptor({ name: 'sync' }, () => ({ execute: (ctx, next) => { console.log('before'); const result = next(); console.log('after'); return result; },}));
// Async interceptor — chain becomes asyncconst asyncInterceptor = defineInterceptor({ name: 'async' }, () => ({ execute: async (ctx, next) => { await someAsyncWork(); return next(); },}));Which Methods Run Which Phases
Section titled “Which Methods Run Which Phases”| Method | Start | Parse | Route | Validate | Execute | Error | Shutdown |
|---|---|---|---|---|---|---|---|
eval() / cli() |
Yes | Yes | Yes | Yes | Yes | Yes | Yes |
parse() |
No | Yes | No | Yes | No | No | No |
run() |
No | No | No | No | Yes | No | No |
To run an interceptor for some callers only, set callers in its meta: defineInterceptor({ name: 'stdin', callers: LOCAL_CALLERS }, ...) skips it for serve, mcp and tool() calls.
How Built-in Extensions Use Interceptors
Section titled “How Built-in Extensions Use Interceptors”Understanding how built-in features are implemented helps illustrate the interceptor model:
Signal handling (padroneSignalHandling, order: -2000) — The outermost interceptor. In the start phase, creates an AbortController and subscribes to OS signals via runtime.onSignal(); it also aborts when the caller’s signal (eval(input, { signal })) does. Passes the signal to all downstream phases via next({ signal }). The signal is aborted with a SignalError as its reason, so ctx.signal.throwIfAborted() (or an aborted fetch) exits with the signal’s code (130 for SIGINT). In the error phase, wraps errors with signal info. In shutdown, cleans up subscriptions. Implements double-tap SIGINT force-exit within forceExitMs (default 2000; 0 turns it off), and force-exit on a repeated SIGTERM/SIGHUP (only after a first process signal: a run aborted by the caller’s signal isn’t force-exited by the next Ctrl+C), using closure state shared across phases; onForceExit(signal) runs right before the exit. Configure it with createPadrone(name, { builtins: { signal: { forceExitMs, onForceExit } } }). The REPL (--repl or the repl command) releases the process signals of the run that started it, so Ctrl+C interrupts the command running inside it.
Auto-output (padroneAutoOutput, order: -1100) — In the execute phase, intercepts the action result and writes it to runtime.output(). Handles promises (awaits), iterators (consumes and outputs each value), and plain values. In the error phase of cli(), prints the message of any error that no inner extension printed (help prints routing and validation errors), whichever phase threw it. Under JSON output (--json), it prints every error as { "error": { ... } } on stdout instead. Extensions that print an error themselves call markErrorReported(error) so it isn’t printed twice.
Help (padroneHelp, order: -1001.5) — Adds a help command and registers an interceptor with parse, validate, execute, and error phases. The parse phase detects --help flags; the execute phase renders the help, so flags read later in parsing (--no-color, --json) apply. Under JSON output the help is returned as an object. The error phase formats routing/validation errors with help text in CLI mode.
Config file loading (padroneConfig, order: -999.5) — Not included by default; must be explicitly applied via .extend(padroneConfig(...)). In the validate phase, loads the config file from the file system (or via a custom loadConfig function) and merges values into rawArgs before schema validation. Only keys the command has options for are applied (by option name, alias or kebab-case name), so one config file can serve every command; null means unset (in nested objects too), nested objects are filled key by key under CLI values, and positionals typed on the command line win. It runs inside env (env values win) and outside interactive prompting (values from config aren’t prompted for). --config/-c (and with profiles: true, --profile <name>) is declared through meta.options and listed in help through meta.helpOptions; a profile selected by --profile or <PROGRAM>_PROFILE applies the config’s profiles.<name> over its top-level values, and the sections of the commands on the way (sections, 'auto' by default: a key the running command has an option for stays its value) (serve: { ... }) apply next. --config and --profile are read only for local callers: for serve, MCP and tool() calls they stay unknown options (unless profiles: { remote: true }), so a request can’t make the program read a local file or switch profiles. Like env, it skips built-in commands (builtin: true, isBuiltinCommand) unless builtins: true, and names the file in validation errors about the values it filled. With command: true, it adds a config group whose set/unset write the JSON file (and edit any file but a script) in the user config directory (program.dirs.config); the group disables the interceptor for itself.
Interactive prompting (padroneInteractive, order: -999) — In the validate phase, prompts for missing field values via runtime.prompt() and injects responses into rawArgs before validation.
Suggestions (padroneSuggestions, order: -500) — In parse and validate error paths, enriches error messages with fuzzy-matched “Did you mean?” suggestions: commands and their aliases (plus padroneAliases() names for a top-level command, and the extraCommands interceptors list, like external commands), and options, including those extensions declare (--json, --yes, --interactive; not help’s own --detail/--all, nor hidden options). With builtins: { suggestions: { run: 'prompt' } }, an unknown command in cli() or the REPL asks “Run “deploy” instead?” and, if accepted, parses again with the correction.
Disabling and Overriding Built-in Extensions
Section titled “Disabling and Overriding Built-in Extensions”Disabling at Creation
Section titled “Disabling at Creation”const program = createPadrone('myapp', { builtins: { help: false, version: false, repl: false, color: false, suggestions: false, signal: false, autoOutput: false, stdin: false, interactive: false, },});help also accepts options instead of false: builtins: { help: { showHelpOnError: true } } prints the full help after a routing or validation error, instead of the default one-line --help hint. builtins: { help: { pager: true } } shows help taller than the terminal through a pager, like git ($PAGER, or less -FRX; only in cli() on a terminal; --no-pager prints it directly). For other long output, call ctx.runtime.page(text) from an action. builtins: { help: { pickSubcommand: true } } asks which subcommand to run, with a select prompt, when a command that only groups subcommands runs without one (like gh); --help still shows help. builtins: { help: { topics } } adds help topics (app help environment), listed under “Additional help topics”.
Overriding via Deduplication
Section titled “Overriding via Deduplication”Built-in interceptors use id fields like 'padrone:help', 'padrone:auto-output', etc. Register an interceptor with the same id to replace the built-in behavior:
// Custom help interceptor that replaces the built-in oneprogram.intercept(defineInterceptor({ name: 'custom-help', id: 'padrone:help', order: -1000,}, () => ({ parse: (ctx, next) => { // Custom help flag handling return next(); },})));