/ 
Langertha-Raider-0.504
/ Langertha::Raider::CLI::Main

NAME

Langertha::Raider::CLI::Main - Internal command-line entry point behind bin/raider

VERSION

version 0.504

SYNOPSIS

# Internal to Langertha-Raider -- no API promise.
exit Langertha::Raider::CLI::Main->new->run(@ARGV);

DESCRIPTION

Internal module. Its interface may change without notice.

Everything raider does with its command line: the hall, acp, config explain, config migrate, session, provider inspect, provider add, provider list, provider show and provider remove subcommands, option parsing, the skill exports, and then either the REPL (Langertha::Raider::CLI::REPL) or one prompt (Langertha::Raider::CLI::Runner), which ends only once the background subagents it started have ended and their notifications have been answered (ADR 0027 §3). "run" returns the exit status.

-p / --print (ADR 0030 §4, as Claude Code) makes it one prompt even on a terminal: from the words given, else read from standard input to its end. A one-shot prompt -- with -p or not -- that starts with / goes through "oneshot_command": a skill or custom command runs, a reporting built-in prints and exits 0, a REPL-only one is a usage error.

Exit status

0 -- success, including --help, --version, the exports, config explain, config migrate (also with nothing to migrate, and --dry-run), session list, session show, session fork, session rm, provider inspect of a valid manifest, provider add that stored the binding, provider list, provider show and provider remove that removed the alias, and leaving the REPL.
1 -- the run failed: the engine, a tool or the network raised an error (with a machine format, the output is the failed document); a one-shot /NAME whose render aborted (a !`cmd` refused or failed, ADR 0030 §2), with nothing sent; for config migrate: the migration was refused (a new file or a backup already exists, .raider is no directory, the home directory) or a step failed; for provider inspect: the manifest was refused (address, redirect), could not be fetched or is not valid; for --provider also: its endpoint is not usable (another origin, not https, a refused address, a dialect or auth type this raider has no adapter for, no models, a model on several endpoints), or a stored alias that no longer matches what was accepted; for provider add: no terminal, an answer other than y, a manifest that was refused, not fetched or not valid; for provider remove: no terminal and no --yes, or an answer other than y. With a machine format a failed --provider is also the refused or failed document.
2 -- usage error: unknown option, a -o that is not KEY=VALUE, an unknown config subcommand, no prompt, more than one machine format, a machine format with -i, -p with -i, or an unknown machine format version; a one-shot /NAME that is no command, or a REPL-only built-in ("oneshot_command"); for config migrate: a word after it or a machine format; for sessions: a --session value that is no session id, more than one of --session, --continue and --no-session, an unknown or ambiguous session, or --continue without any session; for provider inspect: no target or more than one, a target that is no host or https origin (also a bare name: no dot, no port, no https://), or a --stream-* flag; for --provider: a target that is none, a bare name that is no stored alias (nothing is fetched), -e, -o engine=, -o url= or config explain with it, a model the manifest does not list, no -m where it lists several models, or no -k where the endpoint needs a key; --allow-internal without --provider, or with a stored alias; for provider add: not two words, an alias or variable name that is none, a HOST that is none (also a bare name), auth asked for and no --credential-env, a machine format; for provider show and provider remove: not one word, or an alias that is not stored.
3 -- configuration error: the config file (.raider/config.yml, else .raider.yml; for config migrate the .raider.yml to migrate) cannot be read, the engine is unknown, or a pack detection rule is invalid.
4 -- the session to continue (--session, --continue, session resume) or to remove (session rm) is in use: another raider has it open for writing and holds its lock. Unlike a usage error the same command can work later, which is why it has a status of its own.
130, 143 -- a one-shot run was cancelled by SIGINT or interrupted by SIGTERM (see "run_prompt" in Langertha::Raider::CLI::Runner). It writes the cancelled or interrupted document (or a note), then dies of that same signal, which a shell reports as 128 plus the signal number; see "die_of_signal" in Langertha::Raider::CLI::Runner.

The hall and acp subcommands keep their own exit statuses. The REPL's two-strike Ctrl-C leaves with 0.

output

The Langertha::Raider::CLI::Output for everything but diagnostics. Defaults to one on STDOUT.

err

Filehandle for diagnostics. Defaults to STDERR.

in

Filehandle a prompt or the REPL input is read from. Defaults to STDIN.

usage

The --help text.

version_line

The --version line: raider's version (that of Langertha::Raider), then that of Langertha core.

raider 0.503 (Langertha 0.503)   # for example

parse_options

my ( $opt, @prompt ) = $main->parse_options(@argv);

Parses the options; returns the option hash (with -o pairs in engine_options, and a machine format in machine as format, stream and version) and the remaining words, or nothing after reporting a usage error.

app_args

my %args = $main->app_args($opt);

Constructor arguments for Langertha::Raider::CLI from the parsed options, without config and the skill sources. With a machine format the live trace is off unless --trace asks for it, and then goes to "err", so stdout carries only the machine output.

run

my $exit = $main->run(@argv);

Does what the command line says and returns the exit status.

oneshot_command

my ( $exit, $request ) = $main->oneshot_command($app, '/review src/App.pm', session => $session_for);

A one-shot prompt that starts with / (ADR 0030 §4), resolved by "resolve" in Langertha::Raider::CLI::Commands. Returns the run request to send ("dispatch" in Langertha::Raider::CLI::Commands) -- or, when nothing is to be sent, the exit status:

  • a path such as /etc/hosts is broken: the line as an ordinary prompt;

  • a user-invocable catalogue entry: its run request; a render that aborts is printed on "err" and gives 1;

  • /mcp__SERVER__PROMPT ARGS, a prompt of a configured MCP server: its run request (the servers are started for it); an unknown one gives 2, a failing one 1;

  • a built-in that only reports ("oneshot_report_commands"): its report on "output", then 0 -- also with a machine format, where the report is the plain text and there is no document;

  • /init (its run request) and /compact (acts, then 0): "oneshot_run_commands";

  • any other built-in: 2, it needs the REPL;

  • an unknown command: 2.

session (a code reference) gives the session for ${CLAUDE_SESSION_ID}, asked only when an entry is rendered.

oneshot_report_commands

help context skills agents hooks memory permissions config stats metrics packs mcp: the built-ins a one-shot run prints and leaves (/mcp connects the configured MCP servers first and stops them after; /mcp reconnect is REPL-only, ADR 0029).

oneshot_run_commands

init compact: the built-ins a one-shot run runs.

resume_session

my ( $exit, $session, @notes ) = $main->resume_session($app, $ref);

Opens the session $ref names ("resolve_session"; the newest one of the project when undef, for --continue) for writing through "open_session" in Langertha::Raider::Application and replays it into the app's raider through "restore" in Langertha::Raider::CLI::Sessions. Returns undef, the Langertha::Raider::Session and the notes of the resume -- or, after reporting why, just the exit status: 2 when there is no such session or $ref is ambiguous, 4 when another raider has it open, 1 when it cannot be opened or replayed otherwise.

session_command

my $exit = $main->session_command(list => undef, $opt);
my $exit = $main->session_command(show => $id, $opt);

raider session list, show ID, fork ID and rm ID for the project in -r (or the working directory), through the Langertha::Raider::Application of that project and Langertha::Raider::CLI::Sessions; a document format (--json, --msgpack, --yaml) writes them as one document. rm of a session another raider has open ends with 4, as a resume of it would; a fork or removal that fails otherwise with 1.

migrate_usage

The raider config migrate --help text.

migrate_command

my $exit = $main->migrate_command(@argv);

raider config migrate [--dry-run] [options] through Langertha::Raider::Config::Migrate: the report ("migrate_report" in Langertha::Raider::CLI::Output) on "output", then, without --dry-run, the migration. A refusal or a failed step is reported on "err". Takes --dry-run, -r, --no-color and --help; the other options of raider are accepted and have no effect, as for the session commands. A word after it or a machine format is a usage error: the report is for humans only.

provider_usage

The raider provider inspect --help text.

provider_command

my $exit = $main->provider_command(inspect => @argv);

raider provider inspect TARGET [options] through Langertha::Raider::CLI::Provider. Takes --allow-internal, a document format (--json, --msgpack, --yaml; no stream), --no-color and --help; the other options of raider are accepted and have no effect, as for the session commands. Exactly one target is a must.

provider_usage_error

my $problem = $main->provider_usage_error($opt, $config_cmd);

Why --provider or --allow-internal cannot go with the rest of the command line, or undef. --provider decides the engine and its URL, so it excludes -e, -o engine= and -o url=, and it does not go with config explain; --allow-internal only goes with --provider.

resolve_session

my $id = $main->resolve_session($store, '3f2a');

The whole id of the session a command-line reference names -- the id, a unique start of it or its four hex digits ("resolve" in Langertha::Raider::SessionStore). An unknown or ambiguous reference is reported on "err" and gives undef.

new_session

my $session = $main->new_session($app, $machine);

Starts the session a one-shot run is recorded in ("create_session" in Langertha::Raider::Application) and names it on "err" (with a machine format the document names it instead). A session that cannot be written is reported and the run goes on without one.

interrupt_startup

$main->interrupt_startup(TERM => $machine, $t0);

Ends raider on a SIGINT or SIGTERM that arrives with a machine format before the run starts: the interrupted document (or its run.finished), then death by the signal, as for an interrupted run ("interrupt" in Langertha::Raider::CLI::Runner).

SEE ALSO

SUPPORT

Issues

Please report bugs and feature requests at https://github.com/Getty/langertha-raider/issues.

IRC

Join #langertha on irc.perl.org or message Getty directly.

CONTRIBUTING

Contributions are welcome! Please fork the repository and submit a pull request.

AUTHOR

Torsten Raudssus <torsten@raudssus.de> https://raudssus.de/

COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Torsten Raudssus.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

https://raudssus.de/