woopcode docs
v1.0.0 GitHub

CLI

woopcode [options] [command]

With no command, Woopcode starts the interactive session in the current directory.

Options#

Option Description
-p, --prompt <prompt> Run a single prompt without the interface and exit
--no-auto-approve With --prompt, reject tool edits and commands instead of approving them
-m, --model <model> Model id for this run only; the saved selection is left alone
-c, --continue Reopen the newest session in this project
--resume <session> Reopen a session by name, id or id prefix
--new Start a fresh session — what a bare launch already does
--fork-session With --continue or --resume, branch instead of writing into it
-n, --name <name> Name a new session so it can be resumed by name
--no-session-persistence With --prompt, do not save the session
--events <path> With --prompt, write a JSONL record of the run
-V, --version Print the version
-h, --help Print usage

Commands#

Command Description
woopcode Start the interactive session
woopcode agent The same thing, named explicitly
woopcode models List the models Woopcode knows about
woopcode providers Inspect and configure providers
woopcode sessions List, inspect and prune saved conversations

woopcode#

Starts the session in the current working directory. Woopcode reads the repository it is launched from, so the directory matters.

cd path/to/your-projectwoopcode

Sessions#

A bare launch starts a fresh session, keeping whatever was saved before. The flags go back to one:

woopcode --continue                 # the newest session in this projectwoopcode --resume auth-refactor     # by namewoopcode --resume 3f9c1a2b          # by id prefixwoopcode --resume                   # pick from a listwoopcode --new                      # explicit about the defaultwoopcode --continue --fork-session  # branch rather than continue in placewoopcode -n auth-refactor           # name the session as it starts

A reference that matches nothing exits with status 1 rather than dropping you into a session you did not ask for.

Headless#

--prompt runs one turn without the interface and exits. There is nobody to answer an approval prompt, so tool edits and shell commands are approved automatically.

woopcode --prompt "summarise the auth flow"

--no-auto-approve inverts that: edits and commands are rejected rather than approved. The agent can read and reason, and anything that would change the checkout is refused.

woopcode --prompt "summarise the auth flow" --no-auto-approve

A headless run starts its own session rather than continuing the one you have open interactively, and prints the id to stderr:

woopcode -p "summarise the auth flow" 2> >(grep '^session ')woopcode -p --resume 3f9c1a2b "now write the tests"woopcode -p --no-session-persistence "one-off question"

woopcode models#

woopcode models [-m <model-id>]

Prints the model table. With -m, --model <model-id>, prints one row.

woopcode models --model gemini-3.6-flash

An unknown id prints Model "<id>" not found. and exits without error.

woopcode providers#

Subcommand Description
list Every provider with its default and auth status
login Store an API key and make that provider the default
logout Remove a stored API key
set Change the default provider without touching keys

login takes the provider and the key:

woopcode providers login --provider google --api-key "$GOOGLE_API_KEY"
Option Applies to Description
-p, --provider <name> all four Which provider to act on
-a, --api-key <key> login The key to store

Google Gemini, OpenAI and Anthropic Claude are all implemented; every provider providers list shows can run a session.

Switching provider also moves the model: a selection belonging to another provider is replaced with that provider's default, because the two are stored independently and a Gemini model id sent to Anthropic fails on the first turn.

woopcode sessions#

Subcommand Description
list Saved sessions in this project, newest first
show Print one session's transcript
prune Delete sessions past the retention period

A bare woopcode sessions is the listing.

woopcode sessionswoopcode sessions list --all          # every project on this machinewoopcode sessions show auth-refactorwoopcode sessions prune --days 7

show and prune take a name, id or id prefix. An ambiguous reference lists the candidates and exits 1 rather than picking one.

prune without --days uses retentionDays from providers.json, which defaults to 30. It also runs on its own at most once a day when a session starts.

Exit codes#

Woopcode exits 0 on success and non-zero when a command fails to parse. A turn that the agent could not complete is reported in the output, not in the exit code.

See also#

Added in woopcode@0.6.0