CLI Mode

When you pass arguments to your app, Repl dispatches the command and exits — standard CLI behavior.

Invocation

myapp <route> [arguments] [options]

Examples:

myapp client list
myapp client 42 show
myapp client 42 show --json

Output formats

Every command supports output format flags out of the box:

Flag	Output
(none)	Human-readable text / table
--json	JSON
--xml	XML
--yaml	YAML
--markdown	Markdown table

$ myapp contacts list --json
[
  { "id": 1, "name": "Alice" },
  { "id": 2, "name": "Bob" }
]

Help and discovery

--help is built in at every level:

$ myapp --help
Commands:
  client
  report

$ myapp client --help
Commands:
  client list
  client {id} show
  client {id} remove

Help also lists a Global Options: section covering the built-in flags and any custom global options you registered, with their descriptions.

Shell completion

Register Repl’s completion scripts to get tab completion in your shell:

# Auto-detect current shell
myapp completion install

# Explicit shell
myapp completion install --shell bash
myapp completion install --shell powershell
myapp completion install --shell zsh
myapp completion install --shell fish
myapp completion install --shell nu   # Nushell

This writes a managed block to the shell’s profile file. Tab completion then works for all routes, context segments, and option names.

What completion returns:

• Command literals and context segments from your graph.
• The route’s own options, plus static global options (--help, --interactive, --no-interactive, --no-logo, output aliases, --output:<format>, --answer:<name>, and the result-flow flags --result:page-size, --result:cursor, --result:pager, --result:all).
• Enum member names for a pending enum-typed option.
• .WithCompletion(...) provider values — opt-in per provider.

Every shell Tab spawns a new process and blocks the shell until the app answers, so a slow completion provider (network, database) must never run there implicitly. A provider only serves shell completion when its registration opts in:

app.Map("contact inspect {clientId}", (string clientId) => Inspect(clientId))
   .WithCompletion(
       "clientId",
       (ctx, input, ct) => LookupClientIdsAsync(input, ct),
       CompletionProviderScope.InteractiveAndShell);

The default scope (CompletionProviderScope.Interactive) keeps the provider on in-process surfaces only: the interactive Tab menu and the complete ambient command. Each provider invocation is also bounded by ShellCompletionOptions.ProviderTimeout (default: 1 second) — a stalled provider degrades completion to the static candidates instead of blocking the shell.

Shell completion and the interactive REPL autocomplete draw candidates from the same source and parse prior tokens the same way. Two deliberate differences remain: on an empty token after a complete command, shell completion lists option names while the interactive menu shows parameter placeholders (options appear from the first typed -); and the interactive menu runs every registered provider while the shell bridge only runs opted-in ones.

Other commands:

myapp completion status         # show current installation status
myapp completion uninstall      # remove the managed block
myapp completion detect-shell   # show which shell was detected

The completion bridge (completion __complete) is hidden from --help — it is a protocol command used by the shell scripts.

Automatic installation — configure how completion is offered at startup:

SetupMode	Behavior
Manual (default)	User runs install explicitly
Prompt	Offers installation once on the first interactive startup
Auto	Installs automatically when a supported shell is detected

app.Options(o =>
{
    o.ShellCompletion.SetupMode = CompletionSetupMode.Prompt;
});

Response files

Any argument prefixed with @ is a response file:

myapp @deploy.rsp

deploy.rsp:

deploy
--environment
production
--region
us-east-1

Tokens are read one per line. Useful for long or repeatable invocations, and for passing arguments in CI without quoting issues. Response files are not recursive.

Machine-readable help

Add --help --json to get a structured help payload — useful for agents and tooling:

$ myapp client --help --json
{
  "name": "client",
  "commands": [
    { "route": "list", "description": "..." },
    { "route": "{id:int} show", "description": "..." }
  ]
}

Exit codes

Condition	Exit code
Success	0
All named errors — command not found, validation failure, cancellation, unhandled exception	1
Custom (explicit)	any N — use Results.Exit(N) in a handler to return an arbitrary code

All error conditions produce exit code 1 by default. To signal a specific failure mode to callers or scripts, return Results.Exit(N) from your handler with the code that makes sense for your application.

Next step

→ REPL Mode