CLI commands

Use the CLI to initialize configuration, run work, inspect saved sessions, and manage local extensions. Run wuu --help for the command summary. In examples below, replace uppercase IDs and paths with your own values, and put flags before positional arguments unless the command documents another form.

Initialize and identify the build

wuu init
wuu version
wuu version --long
wuu version --json

init creates user configuration and refuses to overwrite an existing file. Use wuu init --force only when you intend to replace it. Configure a working model connection before starting a task.

wuu models --provider NAME --json performs live model lookup for an openai-codex provider. It is not a general offline listing of every configured provider and currently rejects other provider types. It needs the corresponding connection and authentication.

Run, continue, and review

wuu exec --workdir /path/to/project "Run the relevant tests and explain failures"
wuu exec --continue "Continue the investigation"
wuu exec resume THREAD_ID "Continue this task"
wuu exec fork THREAD_ID "Try another approach"
wuu exec review --uncommitted --permission-mode read_only
wuu exec review --base main --permission-mode read_only
wuu exec review --commit COMMIT_SHA --permission-mode read_only

wuu -c and wuu -r THREAD_ID are shortcuts for exec continuation and resume. A fork creates a new conversation from saved context; do not confuse it with a desktop worktree fork. Review uses the selected permission mode, so choose Read only for inspection.

For stdin, attachments, JSONL output, schemas, timeouts, and exit codes, see wuu exec. wuu run remains a compatibility entry point; use exec for new scripts.

Inspect sessions

wuu session list --json
wuu session list --all-workdirs --include-archived
wuu session show --json THREAD_ID
wuu session show --last
wuu session trace --json THREAD_ID
wuu session search --workdir /path/to/project "keyword"

Lists default to the current workspace. show reads metadata and history; trace replays the saved trace without rerunning tools or contacting the model. Search checks metadata and history. Prefer supported JSON output for scripts rather than parsing display text.

Archive, export, and delete

wuu session archive THREAD_ID
wuu session export --out conversation.jsonl THREAD_ID
wuu session export --json --out conversation.json THREAD_ID
wuu session delete THREAD_ID

Archive hides a session from ordinary lists without deleting it. Export normally writes a metadata header and history records as JSONL; --json writes one object containing metadata and history. --out creates or overwrites the output file. Review exports before sharing them.

Delete removes saved session data and its associated workspace artifacts. Confirm the ID and retain any results you need before using it.

Reclaim session database space

wuu session compact --json
wuu session compact --sessions-dir /path/to/sessions --timeout 10m

Close Wuu and its background workers before running this command. It rebuilds the existing sessions database, reclaims free pages, and enables incremental reclamation for older databases. It retains conversation data and requires temporary disk space for the rebuild. --timeout defaults to five minutes; interruption or timeout rolls back an unfinished rebuild. JSON output reports allocated database bytes before and after, excluding the write-ahead log and temporary files. The command also checkpoints and truncates the write-ahead log; if another process keeps it busy, stop that process and retry.

Large provider-history checkpoints are compressed losslessly when saved. Background maintenance also encodes up to 32 legacy checkpoints per pass, stopping after the checkpoint that brings the batch to 8 MiB. Ordinary history, search, exports, and full tool-output files retain their existing behavior. Routine free-page reclamation uses small batches with a 100 ms budget; full database rebuilds run only through session compact.

Builds without compressed-checkpoint support cannot resume those checkpoints. Downgrading requires restoring a database backup from before the upgrade, which also restores history to that backup point.

Inspect execution runs

wuu runs --json
wuu runs read RUN_ID

These commands read persisted execution-run manifests. They are separate from the Automation plugin’s task and run list in the desktop.

Skills and plugins

wuu skills lint .wuu/skills
wuu plugin list
wuu plugin install ./my-plugin.zip
wuu plugin approve my-plugin
wuu plugin disable my-plugin
wuu plugin remove my-plugin

See skills for lint behavior and plugins for local installation and updates. Authors can use create, dev, validate, build, test, and pack; those commands are covered in the authoring reference.

Integration and diagnostics

wuu app-server provides the persistent subprocess protocol used by clients. wuu remote and wuu relay run remote-control components. For a problem report, capture the version, command, workspace, and a minimal redacted error; see troubleshooting.