#Module: cli-entry

#Classes

#CliInputError

Raised by generated executables when the route module's own inputSchema rejects parsed input — invalid input is a usage failure (exit 2), never an execution failure. Construct it through cliInputError so a schema failure carries its CliInputIssue list; the message-only form stays for failures that are not attributable to individual arguments.

#Extends

• Error

#Constructors

#Constructor

new CliInputError(message, issues?): CliInputError

#Parameters

#message

string

#issues?

readonly CliInputIssue[]

#Returns

CliInputError

#Overrides

Error.constructor

#Properties

#~effect/ErrorReporter/attributes?

readonly optional ~effect/ErrorReporter/attributes?: ReadonlyRecord<string, unknown>

#Inherited from

Error.~effect/ErrorReporter/attributes

#~effect/ErrorReporter/ignore?

readonly optional ~effect/ErrorReporter/ignore?: boolean

#Inherited from

Error.~effect/ErrorReporter/ignore

#~effect/ErrorReporter/severity?

readonly optional ~effect/ErrorReporter/severity?: Severity

#Inherited from

Error.~effect/ErrorReporter/severity

#~effect/Runtime/errorExitCode?

readonly optional ~effect/Runtime/errorExitCode?: number

#Inherited from

Error.~effect/Runtime/errorExitCode

#~effect/Runtime/errorReported?

readonly optional ~effect/Runtime/errorReported?: boolean

#Inherited from

Error.~effect/Runtime/errorReported

#cause?

optional cause?: unknown

#Inherited from

Error.cause

#issues

readonly issues: readonly CliInputIssue[]

#message

message: string

#Inherited from

Error.message

#name

name: string

#Inherited from

Error.name

#stack?

optional stack?: string

#Inherited from

Error.stack

#stackTraceLimit

static stackTraceLimit: number

The Error.stackTraceLimit property specifies the number of stack frames collected by a stack trace (whether generated by new Error().stack or Error.captureStackTrace(obj)).

The default value is 10 but may be set to any valid JavaScript number. Changes will affect any stack trace captured after the value has been changed.

If set to a non-number value, or set to a negative number, stack traces will not capture any frames.

#Inherited from

Error.stackTraceLimit

#Methods

#captureStackTrace()

static captureStackTrace(targetObject, constructorOpt?): void

Creates a .stack property on targetObject, which when accessed returns a string representing the location in the code at which Error.captureStackTrace() was called.

const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`

The first line of the trace will be prefixed with ${myObject.name}: ${myObject.message}.

The optional constructorOpt argument accepts a function. If given, all frames above constructorOpt, including constructorOpt, will be omitted from the generated stack trace.

The constructorOpt argument is useful for hiding implementation details of error generation from the user. For instance:

function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();

#Parameters

#targetObject

object

#constructorOpt?

Function

#Returns

void

#Inherited from

Error.captureStackTrace

#prepareStackTrace()

static prepareStackTrace(err, stackTraces): any

#Parameters

#err

Error

#stackTraces

CallSite[]

#Returns

any

#See

https://v8.dev/docs/stack-trace-api#customizing-stack-traces

#Inherited from

Error.prepareStackTrace

#CliUsageError

Raised for argv-shape failures: unknown commands or options, missing or malformed values.

#Extends

• Error

#Constructors

#Constructor

new CliUsageError(message): CliUsageError

#Parameters

#message

string

#Returns

CliUsageError

#Overrides

Error.constructor

#Properties

#~effect/ErrorReporter/attributes?

readonly optional ~effect/ErrorReporter/attributes?: ReadonlyRecord<string, unknown>

#Inherited from

Error.~effect/ErrorReporter/attributes

#~effect/ErrorReporter/ignore?

readonly optional ~effect/ErrorReporter/ignore?: boolean

#Inherited from

Error.~effect/ErrorReporter/ignore

#~effect/ErrorReporter/severity?

readonly optional ~effect/ErrorReporter/severity?: Severity

#Inherited from

Error.~effect/ErrorReporter/severity

#~effect/Runtime/errorExitCode?

readonly optional ~effect/Runtime/errorExitCode?: number

#Inherited from

Error.~effect/Runtime/errorExitCode

#~effect/Runtime/errorReported?

readonly optional ~effect/Runtime/errorReported?: boolean

#Inherited from

Error.~effect/Runtime/errorReported

#cause?

optional cause?: unknown

#Inherited from

Error.cause

#message

message: string

#Inherited from

Error.message

#name

name: string

#Inherited from

Error.name

#stack?

optional stack?: string

#Inherited from

Error.stack

#stackTraceLimit

static stackTraceLimit: number

The Error.stackTraceLimit property specifies the number of stack frames collected by a stack trace (whether generated by new Error().stack or Error.captureStackTrace(obj)).

The default value is 10 but may be set to any valid JavaScript number. Changes will affect any stack trace captured after the value has been changed.

If set to a non-number value, or set to a negative number, stack traces will not capture any frames.

#Inherited from

Error.stackTraceLimit

#Methods

#captureStackTrace()

static captureStackTrace(targetObject, constructorOpt?): void

Creates a .stack property on targetObject, which when accessed returns a string representing the location in the code at which Error.captureStackTrace() was called.

const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`

The first line of the trace will be prefixed with ${myObject.name}: ${myObject.message}.

The optional constructorOpt argument accepts a function. If given, all frames above constructorOpt, including constructorOpt, will be omitted from the generated stack trace.

The constructorOpt argument is useful for hiding implementation details of error generation from the user. For instance:

function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();

#Parameters

#targetObject

object

#constructorOpt?

Function

#Returns

void

#Inherited from

Error.captureStackTrace

#prepareStackTrace()

static prepareStackTrace(err, stackTraces): any

#Parameters

#err

Error

#stackTraces

CallSite[]

#Returns

any

#See

https://v8.dev/docs/stack-trace-api#customizing-stack-traces

#Inherited from

Error.prepareStackTrace

#Interfaces

#CliInputIssue

One input-validation failure of a routed command, already spelled in CLI terms (#465): the argument the user typed rather than the schema path.

#Properties

#expected

readonly expected: string

The plain-language expectation, e.g. number <= 55000 or one of: json, text.

#message

readonly message: string

The schema's own message for the issue, kept for machine consumers.

#received?

readonly optional received?: unknown

The value the command received at the issue path; absent when nothing was received.

#target

readonly target: string

The CLI spelling of the failing argument: --flag for a named option, <name> for a positional, --input.<path> for a projected MCP command, or input when the issue is not attributable to one argument.

#CliRenderedDocument

#Properties

#root

readonly root: CliRenderedDocumentNode

#status

readonly status: "failed" | "represented-error" | "success"

#value?

readonly optional value?: unknown

#version

readonly version: number

#GeneratedCliExecuteContext

#Properties

#args

readonly args: readonly string[]

The raw argv the command consumed, for the provider invocation's args.

#json

readonly json: boolean

True when --json was passed; plain commands already emit canonical JSON.

#signal

readonly signal: AbortSignal

#terminal

readonly terminal: AgentTerminal

The process's terminal capability (#511), probed once by the shell; the executable mounts it as request.terminal.

#GeneratedCliInputSchema

#Methods

#parse()

parse(input): unknown

#Parameters

#input

unknown

#Returns

unknown

#GeneratedCliRenderContext

#Properties

#args

readonly args: readonly string[]

The raw argv the command consumed, for the dispatch invocation's args.

#signal

readonly signal: AbortSignal

#terminal

readonly terminal: AgentTerminal

The process's terminal capability (#511), the same value that selected the output mode.

#GeneratedCliRenderSession

One rendered run: a live render-event stream plus its validation and teardown.

#Properties

#close

readonly close: () => Promise<void>

#Returns

Promise<void>

#events

readonly events: () => ReadableStream<CliRenderedEvent>

#Returns

ReadableStream<CliRenderedEvent>

#validate

readonly validate: (value) => unknown

Validates the complete document's value (the route's resultSchema.parse).

#Parameters

#value

unknown

#Returns

unknown

#GeneratedCliWebCommand

#Properties

#run

readonly run: (argv, context) => Promise<number>

#Parameters

#argv

readonly string[]

#context

GeneratedCliWebContext

#Returns

Promise<number>

#GeneratedCliWebContext

#Properties

#name

readonly name: string

#signal

readonly signal: AbortSignal

#writeErr

readonly writeErr: (text) => void

#Parameters

#text

string

#Returns

void

#writeOut

readonly writeOut: (text) => void

#Parameters

#text

string

#Returns

void

#ParsedGeneratedCliArgv

#Properties

#input

readonly input: Readonly<Record<string, unknown>>

#json

readonly json: boolean

#ndjson

readonly ndjson: boolean

#RunGeneratedCliOptions

#Properties

#argv

readonly argv: readonly string[]

#commands

readonly commands: readonly CompiledCliCommand[]

#description?

readonly optional description?: string

#execute

readonly execute: (command, input, context) => Promise<unknown>

Runs one resolved plain command with parsed input; returns the validated result.

#Parameters

#command

CompiledCliCommand

#input

Readonly<Record<string, unknown>>

#context

GeneratedCliExecuteContext

#Returns

Promise<unknown>

#name

readonly name: string

#render?

readonly optional render?: (command, input, context) => GeneratedCliRenderSession | Promise<GeneratedCliRenderSession>

Opens one rendered run for a resolved .tsx command with parsed input.

#Parameters

#command

CompiledCliCommand

#input

Readonly<Record<string, unknown>>

#context

GeneratedCliRenderContext

#Returns

GeneratedCliRenderSession | Promise<GeneratedCliRenderSession>

#signal?

readonly optional signal?: AbortSignal

#terminal?

readonly optional terminal?: AgentTerminal

The terminal capability to report and select the output mode from (#511). Omitted, the shell probes this process's stdout and stderr once.

#version

readonly version: string

#web?

readonly optional web?: GeneratedCliWebCommand

Framework-owned command dispatched before authored routes (#564).

#writeErr?

readonly optional writeErr?: (text) => void

#Parameters

#text

string

#Returns

void

#writeOut?

readonly optional writeOut?: (text) => void

#Parameters

#text

string

#Returns

void

#RunGeneratedRenderedScriptOptions

#Properties

#argv

readonly argv: readonly string[]

#createSession

readonly createSession: (argv, context) => GeneratedCliRenderSession

Opens one rendered run for the script with the mode flags removed from argv.

#Parameters

#argv

readonly string[]

#context

#signal

AbortSignal

#terminal

AgentTerminal

#Returns

GeneratedCliRenderSession

#name

readonly name: string

#signal?

readonly optional signal?: AbortSignal

#terminal?

readonly optional terminal?: AgentTerminal

The terminal capability to report and select the output mode from (#511); probed from the process when omitted.

#writeErr?

readonly optional writeErr?: (text) => void

#Parameters

#text

string

#Returns

void

#writeOut?

readonly optional writeOut?: (text) => void

#Parameters

#text

string

#Returns

void

#Type Aliases

#CliOutputMode

CliOutputMode = "json" | "markdown" | "ndjson" | "tty"

The four output modes of one rendered invocation: interactive tty updates progress in place before the final document; piped markdown emits exactly one final document with no partial fallbacks; json emits the canonical validated final value; ndjson emits the sequence-numbered render-event stream (an Agent Bundle CLI/script dialect — never MCP JSON-RPC, never written to an MCP server's stdout).

#CliRenderedDocumentNode

CliRenderedDocumentNode = { children: readonly CliRenderedDocumentNode[]; kind: "result"; metadata?: unknown; } | { kind: "markdown"; text: string; } | { kind: "text"; text: string; } | { kind: "context"; text: string; } | { kind: "json"; value: unknown; } | { completed: number; kind: "progress"; message?: string; total?: number; } | { data: string; kind: "image"; mimeType: string; } | { data: string; kind: "audio"; mimeType: string; } | { kind: "resource"; mimeType?: string; name: string; uri: string; } | { code: string; kind: "error"; message: string; }

Structural mirrors of the runtime package's versioned Agent Document and render-event contracts (AGENT_DOCUMENT_VERSION 1). The generated executable feeds real runtime values through these shapes; keeping them structural means this shell never imports @agent-bundle/runtime — the generated bundle resolves the runtime from the consumer project instead.

#CliRenderedEvent

CliRenderedEvent = { document: CliRenderedDocument; sequence: number; type: "shell"; } | { completed: number; message?: string; sequence: number; total?: number; type: "progress"; } | { boundaryId: string; document: CliRenderedDocument; sequence: number; type: "replace"; } | { boundaryId?: string; error: { code: string; message: string; }; sequence: number; type: "error"; } | { document: CliRenderedDocument; sequence: number; type: "complete"; }

#Variables

#cliInputError

const cliInputError: (command, input, error) => CliInputError

Maps a route module's inputSchema failure onto a CliInputError whose issues name the CLI argument, the expectation, and the received value (#465). Any other thrown value keeps its message, exactly as before. Generated executables, the routed-CLI test harness, and the rendered-command harness all call this so every surface reports the same text.

#Parameters

#command

CompiledCliCommand

#input

unknown

#error

unknown

#Returns

CliInputError

#cliInputInvalidCode

const cliInputInvalidCode: "CLI_INPUT_INVALID" = "CLI_INPUT_INVALID"

The machine-readable error code of an input-validation failure in --json and --ndjson output.

#cliInputIssueLine

const cliInputIssueLine: (issue) => string

The one-line human rendering of one input issue.

#Parameters

#issue

CliInputIssue

#Returns

string

#confirmationRequiredMessage

const confirmationRequiredMessage: (server, tool) => string

The fail-closed confirmation diagnostic shared by bulk and explicit MCP tool projections.

#Parameters

#server

string

#tool

string

#Returns

string

#mapGeneratedCliInput

const mapGeneratedCliInput: (command, inputSchema, projectionModule, input) => Promise<unknown>

Applies projection defaults, mapInput, and the route schema at the generated CLI boundary.

#Parameters

#command

CompiledCliCommand

#inputSchema

GeneratedCliInputSchema

#projectionModule

Readonly<Record<string, unknown>> | undefined

#input

Readonly<Record<string, unknown>>

#Returns

Promise<unknown>

#parseGeneratedCliArgv

const parseGeneratedCliArgv: (command, argv) => ParsedGeneratedCliArgv

Parses argv and applies projected-tool confirmation exactly as the generated CLI shell does.

#Parameters

#command

CompiledCliCommand

#argv

readonly string[]

#Returns

ParsedGeneratedCliArgv

#projectCliDocumentToMarkdown

const projectCliDocumentToMarkdown: (document) => string

Projects one final Agent Document onto stable Markdown (the piped and TTY final output).

#Parameters

#document

CliRenderedDocument

#Returns

string

#renderedDocumentExitCode

const renderedDocumentExitCode: (policy, document, value) => number

The exit code a completed rendered run sets once its value has passed the route's resultSchema: 1 for a non-success document, else the policy's code. Throws when the result policy finds no valid exitCode (the shell reports the message and exits 1). Generated bins export this decision so the Workbench production path records the bin's own verdict.

#Parameters

#policy

"result" | "zero"

#document

Pick<CliRenderedDocument, "status">

#value

unknown

#Returns

number

#runGeneratedCliEntry

const runGeneratedCliEntry: (options) => Promise<number>

Runs one routed-CLI invocation to completion and returns the process exit code. Help and machine output go through writeOut; diagnostics through writeErr; nothing here touches process.

#Parameters

#options

RunGeneratedCliOptions

#Returns

Promise<number>

#runGeneratedCliProcess

const runGeneratedCliProcess: (options) => Promise<void>

The generated executable envelope: wires process argv, stdout/stderr, SIGINT/SIGTERM (which reach the framework AbortSignal and exit 130/143), and the process exit code around runGeneratedCliEntry.

#Parameters

#options

Omit<RunGeneratedCliOptions, "argv" | "signal" | "writeErr" | "writeOut">

#Returns

Promise<void>

#runGeneratedRenderedScript

const runGeneratedRenderedScript: (options) => Promise<number>

Runs one rendered script (src/scripts/<name>.tsx) to completion and returns the process exit code. The framework dialect reserves exactly --json and --ndjson (before a -- terminator); every other argument passes through to the script component's argv prop untouched. Exit codes derive from the final document status: 0 on success, 1 otherwise.

#Parameters

#options

RunGeneratedRenderedScriptOptions

#Returns

Promise<number>

#runGeneratedRenderedScriptProcess

const runGeneratedRenderedScriptProcess: (options) => Promise<void>

The generated rendered-script envelope, mirroring runGeneratedCliProcess.

#Parameters

#options

Omit<RunGeneratedRenderedScriptOptions, "argv" | "signal" | "writeErr" | "writeOut">

#Returns

Promise<void>

#References

#AgentTerminal

Re-exports AgentTerminal