Skip to content

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.

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

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.

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.

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 table

Field 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.

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 with security -i on stdin (hex-encoded with -X), so it never shows up in ps; the service and name do, and can’t contain quotes or backslashes. Secrets that aren’t printable ASCII are stored base64-encoded behind a padrone-base64: prefix, as security would print them in hex.
  • Linux (and the BSDs): the Secret Service (GNOME Keyring, KWallet) through libsecret’s secret-tool, with keytar’s service/account attributes; the secret goes through stdin. Without secret-tool or 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.json in program.dirs.data (or file), { [service]: { [name]: secret } }, written atomically with mode 0600 in a 0700 directory. Secrets are plain text there, readable by the user’s own processes, like gh’s hosts.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.

A PadroneExtension is a function (builder) => builder:

import type { PadroneExtension } from 'padrone';
// Simple extension that adds a shared interceptor
const withLogging = (builder) =>
builder.intercept(defineInterceptor({ name: 'logger' }, () => ({
execute: (ctx, next) => {
console.log(`Running: ${ctx.command.name}`);
return next();
},
})));
// Extension that adds commands and configuration
const 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).

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));
}

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 plugin
export default (program) =>
program.command('deploy', (c) => c.arguments(z.object({ env: z.string() })).action((args) => `Deployed to ${args.env}`));
Terminal window
my-cli plugins install my-cli-plugin-deploy # installs it into the plugins directory with the package manager
my-cli plugins link ../my-cli-plugin-deploy # or uses a local checkout, while developing it
my-cli plugins list # --json for scripts
my-cli plugins info my-cli-plugin-deploy
my-cli plugins update # or one plugin by name
my-cli deploy --env prod
my-cli plugins uninstall my-cli-plugin-deploy

Plugins 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().

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().

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 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.

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);

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.

Interceptors can hook into seven phases — four core phases (parse, route, validate, execute) and three lifecycle phases (start, error, shutdown):

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).

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

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

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

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)

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.

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)

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 exit

Program-level interceptors always wrap subcommand interceptors:

Program interceptors (outermost) → Subcommand interceptors (inner) → Action handler (core)

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)

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,
}, () => ({})));

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;
},
};
});

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();
},
}));

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 }).

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 typed

The 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();
},
}));

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().

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.

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 sync
const syncInterceptor = defineInterceptor({ name: 'sync' }, () => ({
execute: (ctx, next) => {
console.log('before');
const result = next();
console.log('after');
return result;
},
}));
// Async interceptor — chain becomes async
const asyncInterceptor = defineInterceptor({ name: 'async' }, () => ({
execute: async (ctx, next) => {
await someAsyncWork();
return next();
},
}));
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.

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”
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”.

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 one
program.intercept(defineInterceptor({
name: 'custom-help',
id: 'padrone:help',
order: -1000,
}, () => ({
parse: (ctx, next) => {
// Custom help flag handling
return next();
},
})));