The run command

locac run is the command that actually drives an audit. Everything else in the CLI either prepares for a run, resumes one, or reads what one produced.

locac run ["<prompt>"] [flags]

Two shorthands exist:

• locac with no arguments, on a real terminal, is locac run: it opens the TUI and lets you type the prompt in the input box.
• locac -c ["<prompt>"] continues the most recently used session instead of creating a new one. See Sessions and forking.

The prompt

The prompt is the first positional argument. It is optional only when the TUI is going to open:

locac run "audit the archive extraction path for traversal and zip-slip"
locac run --tui                    # opens idle; type the prompt in the box
locac run -p                       # error: run needs a prompt

Off a TTY, or with --print, a missing prompt is an error rather than a silently empty run.

Piped stdin

Anything piped into locac is appended to the prompt, wrapped in the same ⟦untrusted-output <nonce>⟧ fence a tool result gets:

git diff | locac run "audit this diff" -p
locac run "explain this crash" -p < crash.log

Three details matter:

• Print mode only. The TUI owns stdin for raw-mode keystrokes, so a piped run must use --print (or be non-TTY, where print mode is already the default). Otherwise the pipe is left undrained.
• An empty prompt stays empty. cat suspect.c | locac run -p does not start a run whose entire content is attacker-authored. With no operator prompt, the "run needs a prompt" refusal applies.
• The fence nonce is per-invocation and random, so the piped bytes cannot close the fence and escape into instruction territory.

locac detects a pipe by the file type of fd 0, a FIFO or a regular file, not by isTTY. That is what keeps a plain locac run -p "…" from blocking forever on a read that will never see data.

Choosing a renderer

The fullscreen renderer pins the header and input, windows the transcript to the viewport, scrolls with the wheel and PgUp/PgDn, and returns to following the tail with Ctrl+End. The inline renderer writes the transcript into normal terminal scrollback, so it is still there after the process exits.

--print also prints a one-line statusline when the run finishes:

⌁ claude-opus-4-8 · 14 turn(s) · 283914 tok · $1.4210 · goal · done

Cost is omitted when it is zero, and the mode segment appears only for --plan and --goal.

Approval modes

Dangerous tools, bash and execute, are gated. Which gate you get depends on the flags and on whether the terminal can answer a prompt:

--yes and --allow-all are checked before --auto, so combining them approves everything.

--auto classifies commands lexically. It is a convenience layer over the OS sandbox, not a replacement for it; see --require-sandbox below.

Requiring the sandbox

locac run "…" --require-sandbox

Without this flag a host with no working OS sandbox still runs unconfined and says so in a notice line. --require-sandbox turns that into a refusal:

error: --require-sandbox: no OS sandbox on this host (<reason>)

The verdict is not a capability guess. locac runs a no-op command through the sandbox against the root this run will confine, so a sandbox that is installed but non-functional is reported as absent. A partial sandbox is reported too, with its caveat: on Linux, that is bubblewrap's filesystem and network confinement without the AF_UNIX-blocking stage.

Sandbox prerequisites per OS are in Installation; locac selftest reports what this host actually gets and why.

Restricting the toolset

--tools "read,search,find,ls,outline,code_search,glob"    # allow-list
--exclude-tools "bash,execute"                            # deny-list, applied after --tools

• Both are comma-separated tool names, and both apply to subagents as well as the main loop. Every valid name is in the Tool reference.
• submit_report is never removable, because a subagent has to be able to answer its parent.
• Names are validated against the whole tool universe. A typo is a startup error, not a silently empty toolset:

  error: unknown tool "raed" in --tools (known: bash, code_search, coverage, …)
  

  Copy
• Naming a tool this particular run does not wire is allowed and simply does nothing: coverage before anything has produced an lcov file, or present_plan outside plan mode.
• The list is trimmed, deduplicated and sorted before use, so --tools "read, read ,ls" and --tools "ls,read" are the same filter.

An allow-list of readers is the recommended first pass on an unfamiliar repository.

Plan mode

locac run "audit the auth module" --plan
locac resume <session-id> "go ahead"

--plan runs a read-only exploration phase that ends with present_plan. The plan is not executed in that session turn; resuming the session without --plan runs the execute phase.

Goal mode

locac run --goal "find and prove one High-or-better RCE in the upload handler" --auto

--goal is autopilot: instead of stopping when the model would otherwise be done, the loop keeps feeding the objective back in until the objective is met or a cap fires. It composes with a prompt: the prompt starts the work, the goal decides when the work is finished.

Caps

Every cap is optional, and each one is a positive integer:

Hitting any of them ends the run with stop reason budget and exit code 2, distinct from a clean finish, so a pipeline can tell "nothing found" apart from "ran out of budget, raise it and resume".

A malformed value is a startup error, not a silent retune:

error: invalid --keep-recent "abc" (want a positive integer)

That check exists because Number.parseInt("abc") is NaN, and every comparison against NaN is false, so a NaN cutoff turned compaction into a permanent no-op with nothing in the output to say so. --max-tool-calls 8k and --max-tokens 80.5 are rejected for the same reason.

Other run flags

Model selection flags (--provider, --model, --api, --base-url, --api-key, --auth-scheme, --effort, --custom-provider) are covered in Configuration, and every flag in the CLI is listed in the Flag reference.

Compaction flags

Compaction is on by default and is LLM-free: it elides old tool output and leaves a [elided <n> chars of <tool> output — recall seq=<N>] marker the agent can expand with the recall tool.

Stopping a run

Ctrl+C on a headless run is not a bare SIGINT. The first one aborts the loop at a message boundary, so the transcript stays balanced and resumable and the sandbox reaps its process group:

^C — finishing the current step, then stopping (Ctrl+C again to force)

A second Ctrl+C hits the default handler and kills the process. An aborted run exits 130.

In the TUI, Esc is the same abort path.

Next

Sessions and forking covers resuming, renaming, deleting, and branching the runs this command creates.