Skip to content
OpenWaggle

Command line

Open the app, run an agent headlessly, check the Session Host, and find every openwaggle command.

The openwaggle command opens the desktop app, and runs every other OpenWaggle command without a window. Installation puts it on your PATH, and Control a Hive from outside the app shows how to work with sessions from a terminal. From a source checkout, run bun run cli:dev -- <command> instead.

Open the app

FormCommandWhat it does
No argumentsopenwaggleOpens the desktop app, or brings it to the front if it is already open
Current folderopenwaggle .Opens the desktop app on the project in the current folder
Folderopenwaggle <path>Opens the desktop app on the project at <path>
Session linkopenwaggle openwaggle://sessions/<session-id>Opens the desktop app on that session, like clicking its session link
Helpopenwaggle --helpLists every command
Versionopenwaggle --versionPrints the installed version
Command helpopenwaggle help <command>Prints the usage of one command. openwaggle --help <command> and openwaggle <command> --help do the same

openwaggle <path> accepts any existing folder. It selects that project and starts a new draft session in it, as choosing the project in the sidebar does. A file opens the folder that contains it. If the app is already open, the open app takes the project and comes to the front, so you never get a second copy. On macOS it opens a new window when none is open.

A command name wins over a folder with the same name, so write ./hive to open a folder called hive. After a session link, any further argument is a mistake, and so is an openwaggle: value that is not a session link. Neither opens the app.

Commands

CommandWhat it does
runRuns an agent in a project and streams its reply to the terminal
statusShows whether the Session Host is running and which runs are active
hostChecks on, starts, or stops the background Session Host
hiveFinds, starts, messages, steers, waits for, and exports sessions, and reviews worker delegations. See Hive CLI
schedulesCreates and manages scheduled tasks
agentsValidates, imports, explains, and edits agent definitions
accessManages named access profiles for agents and scripts. See Hive CLI
mcpAdds, lists, and signs in to MCP servers, or serves OpenWaggle over MCP
updateChecks for and installs updates
recoveryInspects or restores the copy of the database made before a migration

None of these open a window. They talk to the Session Host, the background process that runs sessions and agent runs. The Session Host starts when a command needs it and keeps running while work is active. A session you start from the terminal shows up in the desktop app whenever you open it, with its live progress.

Environment variables lists the variables the app and the openwaggle command read, such as OPENWAGGLE_USER_DATA_DIR and OPENWAGGLE_PROFILE.

Mistakes

A mistake never opens the app. openwaggle prints the error, a suggestion when one is close, and the full help to stderr, then exits with status 2. For openwaggle hvie list it prints:

openwaggle: unknown command 'hvie'. Did you mean 'hive'?

OpenWaggle 1.0.0

Usage:
  openwaggle                    Open the desktop app, or focus it if it is already open
  ...
InputExampleResult
Unknown commandopenwaggle hvie listExit 2, with a suggestion
Unknown short option-xExit 2
Mistyped help or version--hlep, --HELP, --h, --verison, --vExit 2
Value after version--version hiveExit 2
Extra or unknown help topic--help hive list, help hvieExit 2
Missing pathopenwaggle ./missingExit 2
Unknown long option, then a wordopenwaggle --json hive listExit 2 in the installed app
Command as a switch--statusExit 2, naming the command it meant
Command renamed before 1.0sessions list, delegations acceptDoes not run, and names the hive command it became
Other long switch on its own--remote-debugging-port=9222Passed to Electron, which starts the app

A development build passes an unknown long option followed by a word to Electron, which needs such arguments. A renamed command names its replacement, such as hive list or hive delegation-accept. With --json or --jsonl it reports a JSON error envelope instead of the usage text. Automation, debugging and the updater rely on other long switches reaching Electron.

run

openwaggle run starts a new session in the current folder, or in --project, and waits for its run to finish.

openwaggle run fix the failing unit tests

With a project and a model:

openwaggle run --project ../api --model anthropic/claude-sonnet-4-5 "summarize the open TODOs"

With the prompt on stdin, here a diff to review:

git diff | openwaggle run --stdin --title "Review this diff"

Give the prompt as words after run or with one of --text, --stdin or --input-file, not both. Words after -- are part of the prompt, which helps when the prompt contains something that looks like an option.

Options

OptionWhat it does
--project <path>Project folder. Without it, run uses the current folder
--text <prompt>The prompt
--stdinReads the prompt from stdin
--input-file <path>Reads the prompt from a file
--attach <path>Attaches a file. Repeat it for more files
--title <title>Session title
--workspace current|local|existing|new-worktreeWhere the session works. Goes with --workspace-id <id>, --base-ref <ref>, and --start-from-origin
--agent <name>Uses an agent definition
--model <provider/model>Model for the session
--thinking <level>Thinking level the new session starts with
--authorization ask-for-approval|yoloAccess mode for this run only. The session’s saved mode does not change. --yolo is short for --authorization yolo
--interaction-timeout-ms <ms>Interrupts the run when a question stays unanswered for <ms> milliseconds. The command then exits with status 7
--jsonlPrints the session’s Session Host events as versioned records instead of text
--idempotency-key <key>Reusing a key attaches to the run that key first started, instead of starting another
--profile <name>Runs as a named access profile. Goes with --credential-stdin or --profile-credential-file <path>

--project and --jsonl work only with run. The other options match openwaggle hive launch. See Hive CLI.

Output

The agent’s reply streams to stdout, so you can pipe it. Progress lines, tool calls, and questions go to stderr. With --jsonl, stdout gets the session’s events instead, each as an event record like hive watch prints, ending with a run-settled record that carries the exit status and, when there is one, the reason.

Text the agent controls, such as tool arguments and approval messages, can contain characters that change what a terminal shows. run prints control characters, text-direction overrides, and invisible characters (zero-width spaces, byte-order marks, variation selectors, tag characters, line separators) as escapes such as \x1b or \u202e. That way they cannot rewrite, reorder, or hide part of the line you are about to approve. Emoji, including joined sequences and subdivision flags, print normally. The reply on stdout gets the same treatment when stdout is a terminal. run leaves it untouched when you pipe it.

Questions, approvals and stopping

SituationWhat run does
Approval, in a terminalAsks Allow? [y/N]. Anything but y declines.
Question or approval, no terminalPrints the command that answers it and keeps waiting
Ctrl-CInterrupts the run and waits for it to stop
Ctrl-C againStops waiting, while the run may still be finishing in the Session Host
Reader of stdout goes awayInterrupts the run and exits, as with openwaggle run ... | head -1
Run replaced or deletedSays so and exits instead of waiting

You can answer an approval in the desktop app instead, and the terminal prompt goes away. Without a terminal, the command run prints is openwaggle hive request-respond, or openwaggle hive approval-respond for an approval.

After a Ctrl-C the session stays saved. Continue it with openwaggle hive follow-up <session-id> --text "...", or open it in the app.

Exit status

StatusMeaning
0The run completed
1The run failed, or its result could not be read
2Usage error
3Authentication error
4Authorization error
5Not found
6Conflict
7A question was not answered before --interaction-timeout-ms ran out, so OpenWaggle stopped the run
8The Session Host is unavailable, or exited during the run
130The run was interrupted, or a second Ctrl-C stopped the command waiting while the run may still be finishing

status

openwaggle status

status never starts the Session Host. It says whether the Session Host is running and lists each active run with its session, run ID, model, how long it has run, and whether it is waiting for an answer. Add --json for machine-readable output.

OpenWaggle 1.0.0
Session Host: running
Active runs: 1
  6f1c2a9e-4b7d-4f0e-9c1a-2d3e4f5a6b7c  Fix tests  (anthropic/claude-sonnet-4-5, 3m, waiting for an answer)
    Run 0b9d8c7e-1a2b-4c3d-8e9f-0a1b2c3d4e5f  in /Users/you/code/app
  • When scheduled tasks are enabled, status also lists each one and when it fires next. An enabled task keeps the Session Host running, so look here when the Session Host stays up with no window open.
  • If the running Session Host is an older version, status says that it hands over to this version once its active runs end. Any command, status included, asks an older Session Host to hand over.
  • A detail status could not read, such as a session title, shows as unavailable. status never guesses it.
  • openwaggle host status is the same command. Checking the status counts as activity, so an idle Session Host waits another 5 minutes, by default, before it exits.
  • An agent running inside OpenWaggle must pass an access profile with --profile, as with openwaggle hive. It should normally use its hive tool instead.

host start

openwaggle host start

host start starts the Session Host with no window if it is not running, then returns. With no scheduled task enabled, the Session Host exits again 5 minutes later by default. To start it at login, so scheduled tasks keep firing after a restart, see Scheduled tasks.

host stop

The Session Host exits on its own 5 minutes after its last work ends, by default, unless a scheduled task is enabled. Every update also stops it before installing. So you rarely need host stop.

openwaggle host stop

host stop makes the Session Host refuse new work at once. It exits as soon as its active runs, running actions, exports, and other work it owns finish. It never interrupts a run, and the command says what the Session Host is waiting for. Follow-ups already queued behind an active run still run first. To stop sooner, pause the queue with openwaggle hive queue-pause <session-id> --queue-revision <n>. openwaggle hive queue-list <session-id> shows the revision.

While it stops, the Session Host still answers the commands that end work. You can read sessions (but not wait on them), answer a run’s questions and approvals, interrupt a run with openwaggle hive interrupt <session-id> --expected-run <run-id> (openwaggle status lists both IDs), and stop an action in the desktop app, which keeps showing your sessions. Commands that start work fail with a message that the Session Host is stopping.

If the desktop app is open, it starts a new Session Host the next time it needs one. Only you can stop the Session Host. Named access profiles and agents cannot.

To wait until the Session Host has exited, add --wait. --timeout-ms sets how long to wait:

openwaggle host stop --wait --timeout-ms 60000

Stop for an update

openwaggle host stop --update

This is the stop an update uses. Restart to update, openwaggle update, and the install script all stop the Session Host this way before they replace the app.

  1. If agent runs are active, it asks whether to wait until they finish (the default), stop them now, or cancel.
  2. Stopping them now gives the Session Host 10 seconds to finish its work. Then it interrupts any run still active, marks it interrupted, and exits. So stopping now ends the runs within about 13 seconds.
  3. The command returns once the Session Host process is gone.

It asks on the terminal, so it also works under curl … | bash. Without a terminal, as on Windows, it waits for the runs. An older Session Host that is handing over to this version cannot be told to stop its runs, so the command only waits for them.

Ctrl-C at the question cancels, like answering c. While it waits, Ctrl-C cancels the update too, though a stop already sent to the Session Host still goes ahead. While the desktop app is open, the command leaves the Session Host alone, because the app owns it then.

Options and exit status

OptionWhat it doesDefault
--waitReturns only once the Session Host has exitedOff
--timeout-ms <ms>How long --wait waits120000 (2 minutes)
--updateStops the Session Host for an update, as described aboveOff
--jsonPrints the report as JSONOff
Statushost stophost stop --update
0The Session Host accepted the stop, or with --wait, exitedThe Session Host exited
1The Session Host refused the stop
6You cancelled, the desktop app is open, or another OpenWaggle process, such as openwaggle mcp serve, keeps starting a new Session Host
7With --wait, its work outlasted --timeout-msThe Session Host had not exited after 20 seconds
130Ctrl-C while it waits