Skip to content

Progress Indicators

Padrone provides a built-in progress indicator system for commands that take time — async operations, network calls, file processing, etc. Progress indicators are auto-managed by default (start before validation, succeed/fail after execution) but can also be driven manually from within an action handler.

import { createPadrone, padroneProgress } from 'padrone';
const program = createPadrone('app')
.command('deploy', (c) =>
c
.async()
.extend(padroneProgress('Deploying...'))
.action(async () => {
await deploy();
return { version: '2.0' };
})
);

Running app deploy shows a spinner with “Deploying…” that auto-succeeds when the action resolves.

Use padroneProgress() to configure automatic progress indicators. Register it with .extend() on a command. The indicator starts before validation and is automatically stopped on success or failure. With run(), which skips the validate phase, it starts right before the action.

When stderr is not a TTY (piped output), in CI, or with TERM=dumb, the built-in renderer doesn’t animate and only prints the final success or error line, using the latest message.

c.extend(padroneProgress('Deploying...'))
c.extend(padroneProgress({
message: {
validation: 'Validating inputs...', // Shown during async validation
progress: 'Deploying...', // Shown during execution
success: 'Deployed successfully!', // Shown on success
error: 'Deploy failed', // Shown on failure
},
spinner: 'line', // Spinner preset
bar: true, // Enable progress bar
time: true, // Show elapsed time
eta: true, // Show estimated time remaining
}))

The message field accepts a string (shorthand for the progress message) or an object with per-phase messages. The validation message is shown first (during schema validation), then replaced by the progress message when execution begins.

A string sets the progress message — used during execution and as fallback for other phases:

padroneProgress('Deploying...')
// Equivalent to:
padroneProgress({ message: 'Deploying...' })
// Equivalent to:
padroneProgress({ message: { progress: 'Deploying...' } })

Use an object to configure messages for each phase:

padroneProgress({
message: {
validation: 'Validating...',
progress: 'Deploying...',
success: 'Done!',
error: 'Failed',
},
})

The success and error fields accept callbacks that receive the actual result or error:

padroneProgress({
message: {
progress: 'Deploying...',
success: (result) => `Deployed v${result.version}`,
error: (err) => `Deploy failed: ${err.message}`,
},
})

Callbacks can return an object with message and indicator to override the success/error icon per-call:

padroneProgress({
message: {
progress: 'Running checks...',
success: (result) => ({
message: `All ${result.count} checks passed`,
indicator: '🎉',
}),
error: () => ({
message: 'Checks failed',
indicator: '💥',
}),
},
})

Static values also support the object form:

padroneProgress({
message: {
progress: 'Building...',
success: { message: 'Build complete', indicator: '🏗️' },
},
})

Pass null to suppress the success or error message entirely (the spinner just clears):

padroneProgress({
message: {
progress: 'Working...',
success: null, // No success message
},
})

Callbacks can also return null:

success: (result) => result.silent ? null : `Done: ${result.count} items`

Messages can be provided at the runtime level via progressConfig.message in the context. Command-level message fields take precedence per-field, so you can set shared defaults and override specific phases per command. padroneProgress() without arguments takes every message from the context, falling back to 'Working...'; a string shorthand (padroneProgress('Syncing...')) sets all messages and ignores the context ones:

const program = createPadrone('app')
.context<{ progressConfig: PadroneProgressDefaults }>()
.command('sync', (c) =>
c.extend(padroneProgress({
message: { progress: 'Syncing...' }, // overrides context progress
})).action(() => 'synced')
);
program.cli({
context: {
progressConfig: {
message: { success: 'Done!' }, // shared default for success
},
},
});

When padroneProgress() is registered, the action context provides a typed progress property on ctx.context:

c.extend(padroneProgress('Importing...'))
.action((args, ctx) => {
for (const item of items) {
process(item);
ctx.context.progress.update(`Importing ${item.name}...`);
}
return `Imported ${items.length} items`;
})

padroneProgress() uses the context-providing interceptor mechanism — it declares .provides<{ progress: PadroneProgress }>(), so ctx.context.progress is fully typed when the interceptor is registered on the command.

Method Description
update(value) Update message, progress, or both (see below)
succeed(message?, options?) Mark as succeeded and stop
fail(message?, options?) Mark as failed and stop
stopAndPersist({ symbol?, text?, prefixText?, suffixText? }) Stop and leave a final line with a custom symbol (see below)
stop() Stop without success/fail status
eta.start() / eta.stop() / eta.reset() Control the ETA display at runtime
pause() Temporarily hide (for clean output)
resume() Redraw after pause()

With the built-in renderer, once the indicator is stopped (by succeed(), fail() or stop()), further calls are ignored, so calling succeed() yourself in an action replaces the auto-managed final message instead of printing a second one. Custom renderers should do the same.

The update() method accepts several forms:

// Update message only
ctx.context.progress.update('Step 2...');
// Set progress ratio (0–1) — shows the bar
ctx.context.progress.update(0.5);
// Update both at once
ctx.context.progress.update({ message: 'Downloading...', progress: 0.75 });
// Switch to indeterminate bar (no percentage, shows animation)
ctx.context.progress.update({ indeterminate: true });
// Back to determinate
ctx.context.progress.update(0.9);
// Start elapsed timer on demand (when time wasn't set in config)
ctx.context.progress.update({ time: true });
// Stop elapsed timer
ctx.context.progress.update({ time: false });
// Text before the indicator and after the message (kept in the final line)
ctx.context.progress.update({ prefixText: '[2/3]', suffixText: '(12 MB)' });

stopAndPersist() stops the indicator and leaves a final line with a symbol of your choice, like ora — for outcomes that are neither a success nor a failure:

c.extend(padroneProgress('Checking for updates...'))
.action((args, ctx) => {
if (upToDate) return ctx.context.progress.stopAndPersist({ symbol: 'ℹ', text: 'Already up to date' });
// ...
})

It takes { symbol, text, prefixText, suffixText }: symbol defaults to ' ' (lined up under ✔/✖ lines, '' for none) and text to the current message. Like succeed(), it replaces the auto-managed final message. Without a terminal, only that final line is printed. A custom renderer may leave stopAndPersist out; the context’s progress.stopAndPersist() then calls its succeed(text, { indicator: symbol }).

prefixText and suffixText can also be set up front, in the config or through progressConfig in the context:

c.extend(padroneProgress({ message: 'Uploading...', prefixText: '[upload]' }))
// [upload] ⠹ Uploading... → [upload] ✔ Uploading...

Show elapsed time and estimated time remaining alongside the indicator:

c.extend(padroneProgress({
message: 'Syncing...',
bar: true,
time: true, // Show elapsed time (⏱ 0:05)
eta: true, // Show ETA based on progress rate (ETA 0:30)
}))

This renders as: 40% ████████░░░░░░░░░░░░ ⏱ 0:10 | ETA 0:06 ⠹ Syncing...

When both time and eta are shown, they are separated by |.

The time option shows a running ⏱ M:SS (or H:MM:SS) counter. When set in the config, it starts automatically when the indicator is created. It can also be toggled on demand:

// Start timer explicitly mid-action
ctx.context.progress.update({ time: true });
// Stop timer display
ctx.context.progress.update({ time: false });

The eta option shows ETA M:SS — an estimated time remaining based on the rate of numeric progress updates. It requires at least two update(number) calls to calculate a rate.

The displayed ETA counts down every second between progress updates, then recalculates when the next numeric update arrives.

Enable a progress bar with the bar option:

c.extend(padroneProgress({
message: 'Downloading...',
bar: true,
}))

The bar renders as: 40% ████████░░░░░░░░░░░░ Downloading...

When no progress number has been set, the bar shows an indeterminate animation. Once update(number) is called, it switches to a determinate bar with a percentage.

Pass an object for full control:

c.extend(padroneProgress({
message: 'Downloading...',
bar: {
width: 30, // Bar width in characters (default: 20)
filled: '▓', // Filled character (default: '█')
empty: '░', // Empty character (default: '░')
animation: 'pulse', // Indeterminate animation style (default: 'bounce')
},
}))

Three built-in animation presets for indeterminate state:

Animation Description
bounce A filled segment slides back and forth (default)
slide A filled segment slides left-to-right and wraps around
pulse The entire bar fades through gradient characters (░▒▓█▓▒░)

You can switch a bar to indeterminate mode at any time via update():

ctx.context.progress.update({ indeterminate: true, message: 'Waiting for server...' });
// ... later, back to determinate:
ctx.context.progress.update(0.5);

Padrone includes four built-in spinner presets:

Preset Frames
dots ⠋ ⠙ ⠹ ⠸ ⠼ ⠴ ⠦ ⠧ ⠇ ⠏
line - \ | /
arc ◜ ◠ ◝ ◞ ◡ ◟
bounce ⠁ ⠂ ⠄ ⡀ ⢀ ⠠ ⠐ ⠈
c.extend(padroneProgress({ message: 'Loading...', spinner: 'line' }))
c.extend(padroneProgress({
message: 'Loading...',
spinner: { frames: ['🌑', '🌒', '🌓', '🌔', '🌕'], interval: 150 },
}))

Set spinner: false to show static text without animation:

c.extend(padroneProgress({ message: 'Processing...', spinner: false }))

By default, the spinner hides when the bar is visible. Use spinner: true to always show the spinner alongside the bar:

c.extend(padroneProgress({
message: 'Installing...',
bar: true,
spinner: true, // Always show spinner, even with bar
}))

This renders as: 40% ████████░░░░░░░░░░░░ ⠋ Installing...

The default renderer outputs to stderr with ANSI escape codes. For non-terminal environments (web UIs, testing), pass a custom renderer:

c.extend(padroneProgress({
message: 'Working...',
renderer: (message, options) => ({
update(value) { /* ... */ },
succeed(msg) { /* ... */ },
fail(msg) { /* ... */ },
stop() { /* ... */ },
pause() { /* ... */ },
resume() { /* ... */ },
eta: { start() {}, stop() {}, reset() {} },
}),
}))

The built-in terminal renderer is also exported as createTerminalProgress for cases where you want to wrap or extend the default behavior.

import { type PadroneProgressRenderer } from 'padrone';
function createMockProgress() {
const indicators = [];
const factory: PadroneProgressRenderer = (message) => {
const calls = [];
const indicator = {
update: (value) => calls.push(`update:${JSON.stringify(value)}`),
succeed: (msg) => calls.push(`succeed:${msg}`),
fail: (msg) => calls.push(`fail:${msg}`),
stop: () => calls.push('stop'),
pause: () => {},
resume: () => {},
eta: { start() {}, stop() {}, reset() {} },
};
indicators.push({ message, indicator, calls });
return indicator;
};
return { factory, indicators };
}
const { factory, indicators } = createMockProgress();
const program = createPadrone('app')
.command('cmd', (c) =>
c.extend(padroneProgress({ message: 'Working...', renderer: factory }))
.action(() => 'done')
);
program.eval('cmd');
// indicators[0].calls → ['succeed:undefined']

For work in several steps, ctx.context.progress.tasks() runs a list of tasks and draws it live, like listr2: a spinner on the running task, ✔ for done, ✖ for failed, ↓ for skipped and ↩ for rolled-back ones. Without a TTY (or with TERM=dumb, or in CI), plain lines are printed instead: ❯ Title when a task starts, › message for its updates, and the result line when it finishes.

c.extend(padroneProgress('Releasing...')).action(async (_args, ctx) => {
await ctx.context.progress.tasks([
{ title: 'Install dependencies', task: () => install() },
{
title: 'Build',
// Subtasks are drawn nested under their task
task: (task) =>
task.tasks(
[
{ title: 'Typecheck', task: () => typecheck() },
{ title: 'Bundle', task: (t) => bundle((file) => t.update(file)) },
],
{ concurrent: true },
),
},
{ title: 'Publish', skip: () => !process.env.NPM_TOKEN && 'no NPM_TOKEN', task: () => publish() },
]);
});

Each task is { title, task, skip?, retry?, rollback? }. skip is true, a reason string, or a function returning one. The task function receives:

Member Description
update(message) Show a status line under the running task
setTitle(title) Change the task’s title
skip(reason?) Stop the task and mark it skipped
tasks(subtasks, options?) Run subtasks nested under this task
signal Aborted when the command is cancelled
retry { count, error? }: which retry this attempt is (0 for the first attempt) and the previous attempt’s error

A failing task with retry: 3 runs up to three more times (retry: { tries: 3, delay: 1000 } waits a second between attempts), shown as [retry 1/3] with the last error. Once its retries are used up, rollback: (task, error) => ... undoes its partial work; the task is then shown as rolled back, and tasks() still rejects with its error (or with the rollback’s own error if that fails):

await ctx.context.progress.tasks([
{ title: 'Download', retry: { tries: 3, delay: 500 }, task: () => download() },
{
title: 'Migrate database',
task: () => migrate(),
rollback: async (t) => {
t.update('restoring backup');
await restore();
},
},
]);

Options: concurrent runs tasks at the same time (true for all, or a number as a limit), and exitOnError (default true) stops starting tasks after a failure; with false every task runs. Either way tasks() rejects with the first error. rendererOptions: { collapseSubtasks: true } hides the subtasks of a task once it’s done or skipped, like listr2. The progress indicator is hidden while the list is drawn, and output written through the runtime pauses the list. Pass taskRenderer (a PadroneTaskListRenderer) to draw lists yourself; it receives the live task states (and the rendererOptions) and is told when they change. createSimpleTaskList is the built-in plain-line renderer: pass it as taskRenderer for log-friendly output even on a terminal.

When auto-progress is active, runtime.output and runtime.error are automatically wrapped to pause/resume the indicator. This prevents garbled output when writing to the terminal while a spinner or bar is animating.

Manual calls to ctx.context.progress.pause() and ctx.context.progress.resume() are available if you need explicit control; output written while paused doesn’t bring the indicator back before resume(). ctx.context.progress.isPaused tells whether the indicator is hidden right now (by pause(), output, a prompt, the editor or the pager), and isActive whether it (or a task list) is still running: false once it finished, and always when progress output is silent (e.g. under serve).

padroneProgress() is an extension that registers a context-providing interceptor. It:

  1. Registers an interceptor that wraps the validate and execute phases with progress indicator management
  2. Provides typed context via .provides<{ progress: PadroneProgressContext }>() so ctx.context.progress (the indicator plus tasks()) is fully typed
  3. Creates the indicator using the configured renderer (defaults to the built-in terminal renderer)
  4. Uses a shutdown handler as a safety net — if the indicator is not cleaned up by validate/execute (e.g., an outer interceptor threw), the command-level shutdown phase stops it
  5. Follows streamed results — when the action returns an iterator or async iterator, the indicator succeeds (or fails) once the stream is fully consumed, whether by auto-output or by the caller. A consumer that stops early (break) stops the indicator without a success message

This means progress indicators interact naturally with other interceptors. The indicator starts before validation interceptors run and is cleaned up after execution. Interceptor errors are caught and reflected in the progress indicator:

program
.intercept(defineInterceptor({ name: 'auth' }, () => ({
execute: (ctx, next) => {
// If this throws, the progress indicator shows the error
checkAuth();
return next();
},
})))
.command('deploy', (c) =>
c.extend(padroneProgress('Deploying...')).action(handler)
);