CliArgs class final

A parsed run configuration (interactive or headless).

Inheritance

Constructors

CliArgs({String? model, String provider = 'openai-completions', bool providerExplicit = false, String? baseUrl, String? systemPrompt, String? systemPromptFile, String? visionModel, String? visionBaseUrl, String? transcribeModel, String? transcribeBaseUrl, List<String> plugins = const [], List<String> promptTemplateDirs = const [], String? mode, String? cwd, String? sessionRoot, String? session, String? prompt, String? promptFile, String? cubeName, String? cubeConfigPath, ToolsConfig? tools, CompactionEngine? compactionEngine, String? logFile, RedactionConfig? redact, TrajectoryCliCommand? trajectory, ConfigCliCommand? config, ExtCliCommand? ext, JsrCliCommand? jsr, SessionCliCommand? sessionList, List<String> positionals = const [], String? output, String? outputFormat, List<String> attachments = const [], bool waitForJobs = false, bool piMode = false, bool ompMode = false, bool debugSecrets = false, bool noFormat = false, bool streamThinking = false})
Creates a CliArgs.
const

Properties

attachments → List<String>
--attach <path> (repeatable, issue #155): files attached to the first user message of a headless run as image content blocks.
final
baseUrl → String?
--base-url <url>.
final
compactionEngine → CompactionEngine?
--compaction-engine <classic|structured>: the RUNTIME scope of the engine selector (issue #148) — wins over the project and global compaction: sections, this invocation only.
final
config → ConfigCliCommand?
The fa config <verb> subcommand (e.g. export-providers), when the invocation routed to the headless config manager instead of a prompt run.
final
cubeConfigPath → String?
--cube-config <path>: apply the cube sandbox profile from an explicit manifest path (highest cube precedence).
final
cubeName → String?
--cube <name>: apply the cube sandbox profile <cwd>/.fah/cubes/<name>.yaml for this run. Wins over the cube: config section; --cube-config beats it.
final
cwd → String?
--cwd <dir>.
final
debugSecrets → bool
--debug-secrets (gh-1059): log every secure-store preload read — found / absent / error: <diagnostic> — so a degraded keychain boot is diagnosable instead of silently keyless. Same effect as the truthy FA_DEBUG_KEYS env var.
final
ext → ExtCliCommand?
The fa ext <verb> subcommand, when the invocation routed to the JS extension manager instead of a prompt run.
final
hashCode → int
The hash code for this object.
no setterinherited
isHeadless → bool
Whether this invocation runs a single headless prompt instead of the interactive REPL.
no setter
jsr → JsrCliCommand?
The fa jsr <verb> subcommand (gh-1033), when the invocation routed to the jsr widget CLI pass-through instead of a prompt run.
final
logFile → String?
--log-file <path>: tee every line the CLI prints (assistant text, tool trace, diagnostics) to path as it is produced, so a run nested inside a parent CLI's output capture leaves a readable, tail -f-able trace file behind. The file is truncated on start. The FA_LOG_FILE env var is the twin default when the flag is absent (flag wins).
final
mode → String?
--mode <name> (code | architect | review).
final
model → String?
--model <id>.
final
noFormat → bool
--no-format: render assistant markdown raw (byte-identical passthrough) even on a color TTY (issue #774). Same effect as the FA_NO_FORMAT env var.
final
ompMode → bool
--omp (issue #680): boot the omp load-mode preset — the curated essential tool set in the schema, everything else discoverable. Wins over the FA_AGENT_MODE env twin and the agent.mode config (flag > env > config).
final
output → String?
--output <mode> (issue #155): 'events' (HEP v1 JSONL on stdout) or 'events=full' (full tool arguments). 'json' only rides --version.
final
outputFormat → String?
--output-format <format> (issue #695): text (default) or stream-json — NDJSON agent events on stdout for headless runs (pi --mode json / claude-code stream-json parity). --mode json is an exact alias. Null = text (the flag was absent).
final
piMode → bool
--pi: the pi benchmark mode (issue #679) — 4-tool surface (read, write, edit, bash), bare prompt. Wins over FA_PI_MODE and the config agent.mode (AC3: flag > env > config).
final
plugins → List<String>
--plugin <name> (repeatable).
final
positionals → List<String>
Positional arguments: the headless prompt source. Joined with spaces, or resolved as a file by resolveHeadlessPrompt when the first one names an existing file. Empty for interactive REPL mode.
final
prompt → String?
The -p/--prompt headless prompt, used verbatim (no file resolution). Mutually exclusive with promptFile and positionals.
final
promptFile → String?
--prompt-file <path> (alias -f): read the file as UTF-8 text and send it verbatim as the headless prompt — never further resolved. Mutually exclusive with prompt and positionals. The path is resolved by the executable's IO layer; a missing/unreadable file is a usage error (CliArgsException from resolveHeadlessPrompt).
final
promptTemplateDirs → List<String>
--prompt-template-dir <path> (repeatable).
final
provider → String
--provider <kind> (default: openai-completions, via OpenRouter).
final
providerExplicit → bool
Whether --provider was passed explicitly. When false, the executable prefers the saved provider: from ~/.fah/config.yaml (the persisted /provider switch) over the openai-completions default.
final
redact → RedactionConfig?
The redact: section of the saved CLI config (layered secret redaction); null = absent, defaults apply at pipeline assembly.
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
session → String?
--session <name>.
final
sessionList → SessionCliCommand?
The fa session <verb> subcommand (issue #198), when the invocation routed to the session lister instead of a prompt run.
final
sessionRoot → String?
--session-root <dir>.
final
streamThinking → bool
--stream-thinking (gh-1198): the opt-in live thinking stream for this run — line-mode/headless runs print thinking deltas dimmed, live, like the TUI. Wins over the output.streamThinking config for the run; the config default keeps the byte-identical legacy output.
final
systemPrompt → String?
--system-prompt <text>: a per-invocation system prompt override, used verbatim. Wins over the config prompts: section and the built-in mode prompts. Mutually exclusive with systemPromptFile.
final
systemPromptFile → String?
--system-prompt-file <path>: a per-invocation system prompt override read from a Markdown file. Mutually exclusive with systemPrompt.
final
tools → ToolsConfig?
--tools <id>=on|off,...: the runtime availability scope, parsed eagerly so a malformed token fails as a usage error instead of a startup config error. Wins over the FA_TOOLS env twin; both stack over the config scopes at resolution.
final
trajectory → TrajectoryCliCommand?
The fa trajectory <verb> subcommand, when the invocation routed to the trajectory reader instead of a prompt run.
final
transcribeBaseUrl → String?
--transcribe-base-url <url>.
final
transcribeModel → String?
--transcribe-model <id>.
final
visionBaseUrl → String?
--vision-base-url <url>.
final
visionModel → String?
--vision-model <id>.
final
waitForJobs → bool
--wait-for-jobs (issue #450): headless opt-in — keep the process alive until every detached background job settles or an armed timer delivers (bounded by the waiting.waitCeilingMinutes config, default 30). Without it a headless run prints the detach summary and exits.
final

Methods

noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
toString() → String
A string representation of this object.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited