Advanced Input & Startup
Most applications need only Map and RunAsync. The APIs on this page are for the other cases: keeping the syntax of an existing command line, checking input against application rules, or embedding Repl in a larger system that needs a say before commands run.
Try ordinary routes, option aliases, route constraints and context validation first. Reach for these hooks when the old interface cannot be expressed that way.
Choose an extension point
Section titled “Choose an extension point”| Need | Extension point | Runs |
|---|---|---|
| Read options before creating application objects or registering services | Preparation | Once, before composition |
| Act with the run’s services before dispatch | Startup hook | Once per run or session |
| Translate legacy textual syntax | Argument preprocessor | Before strict parsing and routing |
| Inspect parsed values, redirect a request, handle an external action | Invocation hook | After preliminary parsing, before final validation |
| Accept or refuse input using parsed values and services | Input validator | While typing, on completion, and on submission |
| Wrap ordinary command execution | Middleware | After binding |
Translate an existing command line
Section titled “Translate an existing command line”An argument preprocessor receives the arguments before Repl parses them and returns an ArgumentPreprocessingResult: Continue, Replace or Handled.
app.UseArgumentPreprocessor((input, ct) => input.Arguments is ["/find", var query] ? ArgumentPreprocessingResult.Replace(["query", query]) : ArgumentPreprocessingResult.Continue());
app.Map("query {text}", (string text, int limit = 3) => $"{text}, at most {limit} results");/find "hello world" becomes ["query", "hello world"], with argument boundaries kept; nothing is turned back into a shell string. Repl then parses, binds and validates the replacement as usual. Preprocessors run in registration order, and OriginalArguments keeps the initial input.
To pick a default command, replace an empty invocation:
app.UseArgumentPreprocessor((input, _) => input.Mode == InputProcessingMode.Execution && input.Arguments.Count == 0 ? ArgumentPreprocessingResult.Replace(["serve"]) : ArgumentPreprocessingResult.Continue());Intercept a parsed invocation
Section titled “Intercept a parsed invocation”An invocation hook sees the input after Repl has resolved the route and typed the values, and before final validation. It can inject typed parameters, options groups, typed global options and services:
app.UseInvocationHook((ReplInvocationContext context, SearchPolicy policy) =>{ if (context.Parsed.Command != "query {text}" || context.Parsed.Input.Purpose != InputPurpose.Command // leave help and completion alone || !context.Parsed.TryGetValue<int>("limit", out var limit) || limit != 0 || !context.Parsed.TryGetValue<string>("text", out var text)) { return ReplInvocationResult.Continue(); }
return ReplInvocationResult.Replace(ReplInvocationRequest.ForCommand( "query {text}", new Dictionary<string, object?> { ["text"] = text, ["limit"] = policy.MaximumLimit }, context.Parsed.GlobalValues // a replacement drops globals unless carried over .Where(pair => pair.Value.State == InputValueState.Available) .ToDictionary(pair => pair.Key, pair => pair.Value.Value)));});An ReplInvocationResult continues, replaces the whole request, or handles it with a result of its own. A replacement is parsed again, and routing, constraints, validators, binding and middleware still apply to it. context.Channel tells CLI, interactive, hosted, programmatic and MCP invocations apart. Hooks run on submission, help and explicit completion, never on the background preview.
The same ReplInvocationRequest can be passed straight to app.RunAsync(request). Its values bind as they are, without being turned into tokens and parsed back, which is also the path MCP tool calls take. See submit native values.
Validate parsed values
Section titled “Validate parsed values”An input validator checks rules that span several values or need application services. It returns an InputValidationResult:
app.UseInputValidator((ParsedInputContext input, SearchPolicy policy) =>{ // Command is the full route template. An omitted --limit arrives as its default, 3, and is checked; // 0 is left to the invocation hook above, which replaces it with the policy maximum. if (input.Command != "query {text}" || !input.TryGetValue<int>("limit", out var limit) || limit == 0) return InputValidationResult.Valid();
return limit >= 1 && limit <= policy.MaximumLimit ? InputValidationResult.Valid() : InputValidationResult.Invalid($"The result limit must be between 1 and {policy.MaximumLimit}.");});SearchPolicy is the application’s own record SearchPolicy(int MaximumLimit), registered as a singleton, as in sample 09.
Validators run in registration order, during live preview, completion and submission, so the user sees the refusal while typing. Incomplete and Invalid both block a submitted invocation. Interactive ambient commands such as help and exit, and input that enters a context, pass through validators too.
Prepare before composition
Section titled “Prepare before composition”Some applications must read their own options before they can build anything: a port, a data directory, a mode. ReplStartup parses declared global options and runs preparation hooks before any application object or service exists:
var prepared = await ReplStartup.CreateBuilder() .UseGlobalOptions<StartupOptions>() .UsePreparationHook((StartupOptions options) => ArgumentPreprocessingResult.Continue(options.Port > 0 ? InputValidationResult.Valid() : InputValidationResult.Invalid("Port must be positive."))) .PrepareAsync(args);
if (!prepared.CanContinue) return await prepared.CompleteAsync(); // renders help or the refusal, with the exit policy
var port = prepared.GetOptions<StartupOptions>().Port;var app = ReplApp.Create(prepared, services => services.AddSingleton(new Listener(port)));
app.UseStartupHook((ReplStartupContext context, Listener listener) => context.Purpose is not (InputPurpose.Help or InputPurpose.Completion) && context.RemainingArguments is ["/port"] ? ArgumentPreprocessingResult.Handled(listener.Port) : ArgumentPreprocessingResult.Continue());
app.Map("serve", (Listener listener) => $"Serving on {listener.Port}.");return await app.RunAsync(prepared);The prepared declarations transfer to the app, so do not call UseGlobalOptions<T>() again. CoreReplApp.Create(prepared) and services.AddRepl(prepared, ...) accept the same result. A startup hook runs once per run or session, with the run’s services; it also works without explicit preparation, but then the service provider already exists when it runs.
Callback order and failures
Section titled “Callback order and failures”For a submitted input, argument preprocessors run first, then startup hooks once per run, then parsing and route resolution, then invocation hooks, and finally validators, binding, middleware and the handler. The repository documents the full order, including the earlier preparation stages.
A failing callback is an application error, not invalid input: it is reported as input_callback_error and exits as a HandlerException (see Exit Codes & Signals).
Further reading
Section titled “Further reading”- Advanced input adaptation and validation — preview and completion modes, native values, structured globals, the shell completion bridge.
- Advanced startup preparation and hooks — lifecycle order, externally owned providers, concurrency rules.
- Routes & Parameters — the ordinary input model to try first.