Flag reference
Every flag locac accepts, grouped by what it configures. Flags are parsed globally, and a flag a command does not read is simply ignored, so the heading each one sits under is what tells you where it actually has an effect.
Model selection
Defaults come from ~/.locac/config.json; these flags override it. See
Configuration for how the layers resolve.
| Flag | Value | Meaning |
|---|---|---|
--provider <name> | string | A built-in provider: anthropic, openai, groq, ollama, … |
--custom-provider <name> | string | A provider saved in the config's providers[] array |
--api <api> | anthropic-messages | openai-completions | openai-responses | ollama-chat | The wire protocol, for a generic endpoint |
--base-url <url> | string | Endpoint base URL |
--model <id> | string | Model id. Required; otherwise auto-picked from the nearest configured project |
--api-key <key> | string | API key. Otherwise read from the provider's environment variable |
--auth-scheme <scheme> | x-api-key | bearer | Auth header style. anthropic-messages only |
--effort <level> | low | medium | high | Reasoning budget, for openai-completions and openai-responses |
--config <path> | path | Config file to read. Default ~/.locac/config.json, or under $LOCAC_HOME |
--provider and --custom-provider are mutually exclusive in effect: naming one clears the other,
and the API key is re-picked for whichever source ends up in force.
An --effort level a model cannot carry is not silently dropped. locac prints why:
locac: reasoning effort "high" ignored — <reason>.
Run
| Flag | Value | Meaning |
|---|---|---|
--cwd <dir> | path | Target repository root. Default: the current directory |
--shell-path <path> | path | A bash-compatible shell for execute and the sandbox. Also $LOCAC_SHELL |
--db <path> | path | Session database. Default: per-project, under ~/.locac/projects |
--system <text> | string | Replace the system prompt |
--style <name> | direct | Prose style for the model's own text. Off by default |
--tools <list> | comma-separated | Allow-list of tool names |
--exclude-tools <list> | comma-separated | Deny-list, applied after --tools |
--goal <objective> | string | Autopilot: keep working toward this objective |
--plan | boolean | Plan phase: explore read-only, then present_plan |
--context-window <n> | integer > 0 | Override the model's context window, for custom endpoints |
--tools and --exclude-tools apply to subagents as well as the main loop, and submit_report is
never removable. The Tool reference lists every valid name.
Renderers
| Flag | Meaning |
|---|---|
--tui | Interactive terminal UI. The default on a real terminal |
--fullscreen | Alt-screen renderer: pinned header and input, windowed transcript. The default |
--inline | Inline <Static> scrollback renderer. Survives exit, native mouse scroll |
--print, -p | Plain streaming output, no TUI. The default when piped or non-TTY |
Approval and sandbox
| Flag | Meaning |
|---|---|
--yes, -y | Auto-approve dangerous tools (bash, execute). On skills add/update, accepts the text about to enter the system prompt |
--allow-all | An alias of --yes |
--all | On skills add, every skill in the repo; on skills update, every skill with a recorded source |
--auto | Guardian: auto-approve read-only shell commands, fail-closed on the rest |
--require-sandbox | Refuse to start unless the OS sandbox is available |
With none of these, dangerous tools raise an interactive prompt in the TUI on a real terminal, and are blocked everywhere else.
Caps
| Flag | Value | Default |
|---|---|---|
--max-iterations <n> | integer > 0 | Unset, meaning unlimited |
--max-tool-calls <n> | integer > 0 | Unset |
--max-tokens <n> | integer > 0 | Unset on the CLI; the scaffolded config sets 500000 |
--max-wall-clock-ms <n> | integer > 0 | Unset |
Hitting a cap ends the run with exit code 2.
Compaction
| Flag | Value | Default |
|---|---|---|
--reserve-tokens <n> | integer > 0 | 20% of the context window |
--keep-recent <n> | integer > 0 | 8 |
--evidence-budget-tokens <n> | integer > 0 | Half the reserve |
--compaction-mode <mode> | elide | summarize | elide (LLM-free); summarize is reserved |
--no-compaction | boolean | Off. Compaction is enabled by default |
Sessions
| Flag | Meaning |
|---|---|
--continue, -c | Continue the most recently used session |
-c is a boolean flag, so locac -c "<prompt>" puts the prompt where a subcommand would normally
be. locac reroutes that to run when the first positional is not a known command, which is why both
locac -c "…" and locac run -c "…" work.
Dashboard
Read by locac web.
| Flag | Value | Default |
|---|---|---|
--port <n> | integer 1–65535 | 4173, or web.port from the config |
--host <ip> | string | 127.0.0.1, or web.host from the config |
--enable-runs | boolean | Off. The run-launch routes are opt-in |
--db <path> | path | The per-project session database |
--cwd <dir> | path | Which project's database to open |
Evaluation
Read by locac eval.
| Flag | Value | Default |
|---|---|---|
--baseline <file> | path | Required for eval ab |
--candidate <file> | path | Required for eval ab |
--fixtures <dir> | path | <cwd>/eval/fixtures/mixed |
--trials <n> | integer | 8 |
--seed <n> | integer | 12345 |
Help
| Flag | Meaning |
|---|---|
--help, -h | Print usage and exit |
--version, -v | Print locac <version> on one line and exit 0 |
--version is answered before every other check except --help, so it still prints when the rest of
the command line is wrong (locac run --version --max-tokens nope) and never starts a run. --help
wins if both are given.
locac with no arguments prints usage and exits 1 when there is no terminal to open a TUI on;
on a real terminal it starts an interactive run instead.
Argument validation
locac refuses to start on a malformed argument rather than running with a silently wrong value.
Every one of these prints error: … followed by the usage text and exits 1:
| Input | Result |
|---|---|
| An unknown or malformed flag | error: <parser message> |
| A numeric flag that is not a positive integer | error: invalid --keep-recent "abc" (want a positive integer) |
--effort outside low/medium/high | error: invalid --effort "turbo" (want low | medium | high) |
--style naming an unknown style | error: unknown --style "terse" (want: direct) |
| A tool name that does not exist | error: unknown tool "raed" in --tools (known: …) |
--port outside 1–65535 | error: invalid --port "http" (want an integer 1–65535) |
Numeric flags are parsed with Number, not parseInt, so 8k and 80.5 are errors rather than
silent truncations to 8 and 80. Values are reported one message per bad flag, in a fixed order,
so a run with several typos always prints the same set.
Exit codes
| Code | Stop reason | Meaning |
|---|---|---|
0 | done | The run finished on its own terms |
1 | error | A failure, or a usage/validation error before the run started |
2 | budget | A cap stopped the run. Raise it and resume |
130 | aborted | Interrupted with Ctrl+C (or Esc in the TUI) |
The distinction between 0 and 2 is the one that matters in CI: a run capped part-way through
stops on whatever it had reached, which would otherwise be indistinguishable from a clean pass that
found nothing. 130 follows the shell's own SIGINT convention.
locac run "…" -p --max-tokens 2000000
case $? in
0) echo "clean" ;;
2) echo "hit a cap, resume with a bigger budget" ;;
*) echo "failed" ;;
esac