Skip to content

Exit Codes & Signals

Scripts, CI steps and container supervisors read your app through one number. Every run ends in exactly one ReplExecutionOutcomeKind, and a single table maps that outcome to the exit code.

OutcomeProduced byDefault
SuccessA success-like result, plain data, void, a clean interactive exit0
Help--help, a bare invocation that prints help0
UsageErrorUnknown command, ambiguous prefix, invalid option, unknown --output format2
BindingErrorAn argument that cannot be converted, or a service the binder cannot resolve2
HandlerErrorResults.Error, Validation, NotFound, Cancelled1
HandlerExceptionThe handler or a middleware threw1
CompletedWithFailuresResults.CompletedWithFailures(report)1
FrameworkErrorA hosted service failed to start or stop, an unsupported hosting capability1
InterruptedCtrl+C, Ctrl+Break or SIGTERM claimed by Repl (see Process signals)130 / 143
CancelledThe caller’s own CancellationToken stopped the runnot mapped: the exception propagates, unless ExitCodes.Cancelled or a Resolver is set (a resolver receives 130)
HandlerExitCodeResults.Exit(n)n, verbatim

An int returned by a handler is data: int Count() => 3 prints 3 and exits 0. Results.Exit(n) is the only way for a handler to choose the code itself; a C# 15 union whose active case is Results.Exit(n) exits with n too (Union return values).

A test runner, a linter or a batch import can run to the end and still report failures. That is not a handler error: the report is the result. Return it with Results.CompletedWithFailures:

app.Map("tests run", async (ITestRunner runner, CancellationToken ct) =>
{
var report = await runner.RunAllAsync(ct);
return report.Failed == 0
? Results.Success("All tests passed.", report)
: Results.CompletedWithFailures(report);
});

The report renders as a normal result, with no error prefix, and the run exits with ExitCodes.CompletedWithFailures (1 by default). Over MCP it is not a tool error: the agent reads the report.

ReplOptions.ExitCodes is an ExitCodeOptions. Set any code, and add a Resolver for the final say:

app.Options(options =>
{
options.ExitCodes.UsageError = 64; // EX_USAGE, for scripts that follow sysexits
options.ExitCodes.CompletedWithFailures = 3; // tell "tests failed" from "the run failed"
options.ExitCodes.Cancelled = 130; // return a code instead of throwing
options.ExitCodes.Resolver = outcome =>
outcome.Kind == ReplExecutionOutcomeKind.HandlerException ? 70 : outcome.ExitCode;
});

The resolver receives a ReplExecutionOutcome with the outcome Kind, the ExitCode already mapped, the Result, the Exception and the Route template of the command. It also runs for the codes of interactive commands that decorate shell-integration marks; Scope tells the two apart. It must not throw: a failing resolver falls back to the mapped code.

Keep codes within 0–255. Repl does not clamp them, and POSIX shells only see the low eight bits.

A module that follows another tool’s conventions can declare its own codes by implementing IReplModuleExitCodes. They apply to its commands wherever the module is mounted, before the application’s table:

public sealed class TestRunnerModule : IReplModuleExitCodes
{
// dotnet test conventions: 2 = tests failed, 5 = invalid command line.
public ReplExitCodeOverrides ExitCodes { get; } = new() { CompletedWithFailures = 2, UsageError = 5 };
public void Map(IReplMap map) => map.Map("tests run", RunTests);
}

A module covers Success, UsageError, BindingError, HandlerError, HandlerException and CompletedWithFailures. Help, cancellation, interruption and framework errors describe the whole run and keep the application’s codes. The execution pipeline explains which module owns a refused invocation.

With UseCliProfile() or UseDefaultInteractive(), a one-shot run owns process signals:

SignalTypical sourceExit code
SIGINTCtrl+C130
ControlBreakCtrl+Break, Windows only130
SIGTERMdocker stop, a service manager, kill (Unix only)143

On Windows, taskkill, closing the console window or a service stop do not raise SIGTERM; a Windows host translates those into the caller’s cancellation token itself.

run First signal Ctrl+C or SIGTERM 1 the handler's token is cancelled Handler returns after its cleanup 2 Process exits 130 or 143 3 a non-zero code from the handler wins Second signal not intercepted: the operating system ends the process
What happens between a first signal and the exit code, and where a second signal cuts the sequence short.

The first signal cancels the handler’s CancellationToken, so the command can clean up and return. A second signal is not intercepted: the operating system terminates the process. Repl adds no grace-period timeout of its own; a supervisor that needs one escalates itself. If a handler returns its own non-zero code after the signal, that code wins.

The handler receives a token scoped to the run, which Repl disposes when the run ends. Await work with it; do not keep it for background work.

An app with no profile, UseEmbeddedConsoleProfile(), and the Run overloads that receive an external IServiceProvider, IHost or IReplHost leave signals to the caller. Override the default for one run with ReplRunOptions:

var exitCode = await app.RunAsync(
args,
new ReplRunOptions { ProcessSignalHandling = ProcessSignalHandlingMode.None },
stoppingToken);

Inside the interactive loop, Ctrl+C keeps its usual meaning: the first press cancels the running command and the session continues.

CommandExecution.ExitCode in Repl.Testing follows the configured table, and OutcomeKind gives the outcome itself. Signals have their own entry points:

  • ReplProcessSignalHarness drives the signal lifecycle in memory. It is deterministic and runs on every platform, and it can declare which platform’s rules apply.
  • ReplProcessProbe starts your real executable and sends it real signals, on Unix. Use it for the few guarantees only a process can prove, such as actually exiting 143.
await using var harness = ReplProcessSignalHarness.Create(CreateApp);
var run = await harness.StartRunAsync("work");
harness.SendSignal(ReplProcessSignal.Interrupt);
var result = await run.Completion;
result.OutcomeKind.Should().Be(ReplExecutionOutcomeKind.Interrupted);
result.ExitCode.Should().Be(130);

The testing toolkit documentation explains what each half can and cannot prove.