Run tasks with `wuu exec`

wuu exec runs an agent task without opening the desktop. Use it from a shell, CI job, system scheduler, or another agent. It uses Wuu’s session and execution services; first configure a model service.

Supply a task

wuu exec --workdir /path/to/repo "fix the failing test and verify it"
wuu exec - < task.md
wuu exec "investigate this failure" < error.log

Put flags before the prompt or session ID: argument parsing stops at the first positional argument. With no positional prompt, piped stdin supplies the task. With both, stdin is appended inside a <stdin> block. A task needs text or an attachment; a bare - explicitly requires nonempty stdin.

Attach local images with repeated --image flags and PDFs with repeated --file flags. Other document formats are not accepted by --file. Relative attachment paths resolve from --workdir, or the current directory when it is omitted.

wuu exec --image screenshot.png "find the layout problem"
wuu exec --file report.pdf "summarize the findings"

--image-original disables resizing for the supplied images. Whether the model can use an attachment still depends on its provider and input capabilities.

Continue, fork, or review

wuu exec resume --last "continue from the failure"
wuu exec resume --json THREAD_ID "continue this task"
wuu exec fork THREAD_ID "try another approach"
wuu exec review --uncommitted
wuu exec review --base main
wuu exec review --commit COMMIT_SHA

resume --last selects the latest visible session in the workspace. --continue or -c in the first position after exec is its shortcut. --resume or -r in that position is a shortcut for resume; without further arguments it lists available sessions. fork creates a separate conversation from the source history.

On resume or fork, explicit --provider, --model, --effort, and --variant selections apply to the acquired session before execution. Without these flags, the saved session selection is retained. A resume saves changes to that session; a fork saves them only to the new session. Neither changes workspace defaults or the configuration file.

review creates a review prompt for the chosen scope and uses the normal tools to inspect it. It is not a separate static analyzer. Choose --permission-mode read_only when the task should not edit files.

Control a run

Flags	Effect
--provider, --model, --effort, --variant	Select the model route and supported reasoning settings
--profile	Select an agent profile
--permission-mode	Use standard, read_only, or unconfined
--workdir	Set the workspace directory
--config	Explicitly trust one configuration file
--ignore-user-config	Explicitly trust project configuration instead of user configuration
--env KEY=VALUE	Set a run environment variable; repeatable
--no-tools	Disable local tools
--max-turns N	Set the model/tool loop limit; zero uses the configured default
--timeout 20m	Set a deadline including stdin collection; zero sets no CLI deadline
--ephemeral	Create an in-memory session instead of a resumable saved session
--json	Write a JSONL event stream
--output-last-message FILE	Write the final answer to a file after successful execution
--output-schema FILE	Validate the final answer against a JSON Schema
--input-json	Read the task and options as one JSON object from stdin

Normal startup uses user configuration plus permitted project overrides. The two explicit trust flags change that boundary; review the supplied configuration before using them in automation. See configuration for layering and permissions for command confinement. exec is noninteractive: human question services fail immediately with service_unavailable, and interactive external-engine approvals are declined. This includes nonblocking question offers, which would otherwise have no reader. Plugins may recover from that service error; it does not itself determine the run’s exit code. For a client that can answer questions, use the app-server protocol.

Deadlines and cancellation

--timeout starts before stdin is read and keeps the same deadline through execution. A timeout supplied only inside --input-json starts after input is decoded; use the CLI flag when the producer might never close stdin. Even a positional prompt consumes piped stdin, so use </dev/null when no input is intended. SIGINT and SIGTERM cancel input collection or the active execution and return exit code 5; expiration of the deadline returns 4.

Cancellation attempts to settle the active Run and performs bounded cleanup, so process exit can follow the deadline by a cleanup interval: up to 2 seconds for the interrupt request, then up to 10 seconds for controller shutdown and durable result persistence. Cleanup failures are reported on stderr and retained in the returned error; a prior cancellation or output-failure exit code is preserved. Keep draining stdout and stderr until exit. If stdout stops accepting data, cancellation does not wait indefinitely for it: the final JSONL result is best effort and may be missing or incomplete. A disconnected output pipe cancels execution and returns 6. SIGKILL cannot perform cleanup or emit a result.

Capture output

In text mode stdout contains the final answer after successful execution. Progress, session identifiers, and diagnostics go to stderr. In JSONL mode stdout contains one event object per line; consume the terminal result and the process exit code, not the first turn_completed. A run can contain automatic continuation or structured-output correction turns.

Pending events are bounded. A consumer that falls too far behind can lose its subscription with an explicit overflow error (exit 6), rather than silently losing events or retaining an unlimited backlog. Always set a timeout for an unattended pipeline; a connected reader that stops draining is not a broken pipe.

wuu exec --json --timeout 20m "review the current changes" > events.jsonl
wuu exec --output-last-message report.md "summarize this repository"
wuu exec --json --output-schema schema.json "return the requested report"

The schema path resolves from the workspace. The last-message output path instead resolves from the invoking process’s current directory; an existing file is overwritten. Successful schema validation adds structured_result to the JSONL result. See JSONL events for fields and failure handling.

Machine input

wuu exec --input-json <<'JSON'
{
  "prompt": "investigate this failure",
  "stdin": "panic: example failure",
  "workdir": "/path/to/repo",
  "permission_mode": "read_only",
  "json": true,
  "timeout": "10m"
}
JSON

The object accepts prompt, stdin, files, images, file_attachments, image_attachments, workdir, provider, model, effort, variant, permission_mode, config, profile, ignore_user_config, env, max_turns, no_tools, json, ephemeral, timeout, output_last_message, and output_schema. Path arrays use the same rules as the attachment flags; structured attachment arrays use the app-server shapes. env is an array of KEY=VALUE strings. Unknown fields and multiple JSON values are rejected, and a positional prompt cannot accompany --input-json.

Prefer supplying an option in one place. Nonempty CLI selections take precedence; attachment and environment arrays are combined. Boolean true and nonzero CLI values take precedence over the corresponding input values, so an explicitly passed false or zero is not a reliable way to override JSON input. The review subcommand does not accept --input-json.

Exit codes

Code	Meaning
0	Completed successfully
1	Run failed without a more specific classification
2	Invalid arguments, configuration, or input
3	Permission denied
4	Timed out
5	Interrupted or cancelled
6	Protocol or output-stream error
7	Provider, model, authentication, or network failure
8	Unrecovered local/tool failure
9	Target session already has an active execution

Argument parsing and cancellation during stdin collection can end before any JSONL event is written. Treat a missing result, a failed result, or a nonzero exit code as failure. Do not infer success from a partial answer. Inspect saved sessions and execution records through wuu session and wuu runs.