batch

Batch CLI command: registration and human-readable reporting

This page documents how the livewiki batch command is registered with the Commander CLI framework and how it formats batch run reports for human consumption.

When to use this page

• Understand how the livewiki batch command dispatches its subcommands (status, resume, list, and --only).
• Learn how token, USD, failure, and recovery-tier information is formatted into the human-readable output for batch status and result reports.
• See how exit codes are derived from run status for non-JSON output.
• Trace how failed stage-4 tasks surface their per-attempt diagnostic history in status reports.

How it fits

This file lives in the CLI package (packages/cli/src/commands/), which is the user-facing command layer of livewiki. It depends on core batch logic imported from @livewiki/core/batch (specifically runBatch, resumeBatch, runOnly) and @livewiki/core/batch-status (buildStatusReport, listRuns). The file's role is to wire a Commander subcommand to those core functions and to translate their structured results into either JSON (via the shared emit helper) or human-readable text. It also sets the process exit code based on run status, except when JSON output is requested, in which case the exit code is always 0.

The mechanics in this file are purely about CLI orchestration and presentation: it validates user input, calls the core functions, formats the returned data, and signals the outcome through the exit code.

Diagram

%% livewiki/diagrams/commands-batch.mmd

Subcommand dispatch

The registerBatch function is the single entry point that registers the batch command on the provided Commander program. It takes a Command instance and returns void.

export function registerBatch(program: Command): void {

The function receives the Commander program and registers a batch command on it. It declares three options: --only <target> to re-run a single task, --no-refine to skip LLM refinement (Commander maps this to refine === false), and --concurrency <n> to set the stage-4 worker pool size (an integer 1..16). The action handler then resolves the repository root, parses the positional arguments, and dispatches based on the first argument.