Reference

CLI reference

The verde CLI surface — updates, offline state, live browser and chat control, persistent terminal sessions, integrations, completion, and exit codes.

Overview

verde is both the desktop launcher and a CLI for reading persisted state and controlling a running app. CLI-only commands run before SDL startup, so you can use them from scripts without opening a window.

bash

verde                         # Launch the desktop app
verde app                     # Launch the desktop app explicitly
verde --help                  # Show CLI help
verde version [--json]        # Print version metadata
verde update [--json]         # Install the latest Verde release
verde capabilities [--json]   # Print supported CLI/live features
verde open <url> [--json]     # Open a URL in this Verde workspace's browser pane
verde completion <shell>      # Print shell completion script
verde state <command>         # Read persisted state while the app is closed
verde notify [options]        # Update the current terminal surface
verde integrations <command>  # Inspect and install optional provider hooks
verde theme <command>         # Import, validate, export, or reset themes
verde session <command>       # Manage persistent terminal sessions
verde mcp                     # Run Verde's stdio MCP bridge
verde herdr <command>         # Open or inspect Herdr-backed remote workspaces
verde live <command>          # Control or inspect the running app

Use --json when scripting. Live IPC responses use a stable envelope:

json

{ "id": 1, "ok": true, "result": {} }

Errors return ok: false with an error.code and error.message.

Updates

bash

verde update
verde update --json

verde update launches the official installer for the current platform. For an Arch installation owned by the verde-bin AUR package, it reports the detected yay or paru command instead so the package manager remains the owner of the installation. On Linux and macOS, restart Verde after the installer finishes. On Windows, the updater waits for the running app to exit, installs the new release, and starts Verde again. The command requires network access to the release assets.

You can also check and install releases from Settings → Updates. For an AUR install, Verde opens yay or paru in an interactive terminal pane so sudo password prompts and package progress remain visible. The card shows the installed version, release notes, Check now, Install update, and the Check automatically preference.

Theme packages

Theme commands run without launching the desktop UI. Imports accept local JSON, ordinary HTTP(S) URLs, and GitHub blob links. A successful import installs and activates the theme; it then appears alongside Verde and Omarchy in the Settings theme dropdown.

bash

verde theme import <file-or-url> [--dry-run] [--json]
verde theme validate <file-or-url> [--json]
verde theme export [file] [--name <name>] [--json]
verde theme reset [--json]

# Hosted example from the Verde theme gallery
verde theme validate https://verdeai.dev/themes/kanagawa.json
verde theme import https://verdeai.dev/themes/kanagawa.json

validate and import --dry-run do not change verde.json. export resolves Omarchy-derived colors into a portable package, so the result can be used on Linux, macOS, or Windows. Theme packages only apply allowlisted visual colors and optional UI/terminal font sizes; font-family and command settings are never imported.

Offline state commands

State commands read Verde's persisted SQLite state and do not require the app to be running.

bash

verde state path [--json]
verde state workspaces [--json]
verde state panes --project <id|index|path|current> [--json]
verde state threads --project <id|index|path|current> [--json]
verde state transcript --project <id|index|path|current> --thread <index|provider-id> [--json]

path prints the SDL pref path and state.sqlite location.
workspaces lists imported projects and the selected workspace. projects remains an alias for compatibility.
panes prints the saved workspace layout and terminal dock state for a project.
threads lists saved chat threads for a project.
transcript prints one saved chat transcript by thread index or provider thread id.

Live discovery commands

Live commands talk to the running desktop app over current-user local IPC: a Unix socket on Linux/macOS or a named pipe on Windows. Start the app first.

bash

verde live capabilities [--json]
verde live status [--json]
verde live projects [--json]
verde live active [--json]
verde live panes [--project <id|index|path|current>] [--json]
verde live threads [--project <id|index|path|current>] [--json]
verde live terminals [--project <id|index|path|current>] [--json]
verde live surfaces [--json]
verde live processes [--json]
verde live inspect --pane <pane-id> [--project <id|index|path|current>] [--json]
verde live inspect --focused [--json]
verde live browser status [--json]
verde live workspace select --project <id|index|path|current> [--json]
verde live workspace create --path /path/to/project [--json]
verde live workspace rename --project <id|index|path|current> --label "New name" [--json]
verde live workspace close --project <id|index|path|current> [--json]
verde live workspace reopen [--project <id|index|path>] [--json]

capabilities prints the live method list without requiring the app to be running.
status returns protocol version, app pid, selected project, focused pane, current pane graph, terminal/process summary, and browser runtime state.
active returns the current project and focused pane.
surfaces lists in-memory terminal surface status and attention metadata.
workspace close removes a workspace from the active sidebar without deleting its saved threads or layout. archive is an alias for close.
workspace reopen restores the specified closed workspace, or the most recently closed one when --project is omitted.

Browser control

bash

verde live browser status [--json]
verde live browser open --url https://example.com [--project <id|index|path|current|self>] [--json]
verde live browser navigate --url https://example.com [--json]
verde live browser close [--json]
verde live browser toggle [--json]
verde live browser back [--json]
verde live browser forward [--json]
verde live browser reload [--json]
verde live browser focus [--json]
verde live browser blur [--json]
verde live browser select-all [--json]
verde live browser copy [--json]
verde live browser cut [--json]
verde live browser paste-text --text "hello" [--json]
verde live browser eval --script "document.title" [--json]
verde live browser post-json --json-payload '{"type":"ping"}' [--json]
verde live browser inspector-enable [--json]
verde live browser inspector-disable [--json]
verde live browser inspector-toggle [--json]
verde live browser inspector-mode --mode point|draw-box|draw-freeform [--json]

The browser pane uses the host platform's native webview (WPE WebKit, WKWebView, or WebView2). browser open opens a URL in the workspace's browser pane, creating one if needed. browser eval runs JavaScript in the loaded page and returns the result as JSON. The inspector commands control Design Mode for browser-to-agent visual feedback. select-all and copy operate on the focused page element or selection; cut and paste-text target the focused editable element.

Chat control

Chat commands resolve the target workspace pane to a chat thread and drive it through the same composer / send path as the UI.

bash

verde live chat status --pane <pane-id> [--json]
verde live chat transcript --pane <pane-id> [--json]
verde live chat draft set --pane <pane-id> --text "Reply with exactly: ok" [--json]
verde live chat draft append --pane <pane-id> --text " and more" [--json]
verde live chat send --pane <pane-id> [--prompt "fix the tests"] [--json]
verde live chat followup --pane <pane-id> --prompt "now run the linter" [--json]
verde live chat stop --pane <pane-id> [--json]
verde live chat approve --pane <pane-id> --decision approve|deny [--call <id>] [--json]

status returns the current draft, send state, and pending approval status.
transcript returns persisted messages for the pane's thread.
draft set replaces the current draft; draft append appends to it.
send sends --prompt, --text, or a trailing prompt argument. If no prompt is supplied, it sends the current draft.
followup queues or steers a prompt while a send is active.
stop aborts the current send for that chat thread.
approve resolves the current pending approval. --decision accepts approve or deny.

Terminal and process control

Terminal commands resolve the target workspace pane to its terminal dock and write through the same active PTY input path as the UI.

bash

verde live terminal write --pane <pane-id> --text $'cargo test\r' [--json]
verde live terminal write --focused --text $'printf "ok\\n"\r' [--json]
verde live terminal tail --pane <pane-id> [--lines <count>] [--json]
verde live terminal screen --pane <pane-id> [--lines <count>] [--json]
verde live process list [--project <id|index|path|current>] [--json]
verde live process start --name <name> [--project <id|index|path|current>] [--json]
verde live process stop --name <name> [--project <id|index|path|current>] [--json]
verde live process restart --name <name> [--project <id|index|path|current>] [--json]
verde live process inspect --name <name> [--project <id|index|path|current>] [--json]
verde live process logs --name <name> [--project <id|index|path|current>] [--json]
verde live agent open --provider codex [--project <id|index|path|current>] [--json]
verde live stack start [--project <id|index|path|current>] [--json]
verde live stack stop [--project <id|index|path|current>] [--json]
verde live stack restart [--project <id|index|path|current>] [--json]
verde live stack status [--project <id|index|path|current>] [--json]

terminal write sends text to the active terminal tab/pane. Include \r when you want to submit a shell command.
terminal tail returns recent terminal output; screen returns the current visible terminal screen.
process start, stop, and restart control entries loaded from verde.yml.
agent open --provider codex opens a first-class Codex TUI in the selected workspace without requiring a verde.yml entry.
stack start, stop, and restart apply the same action to every configured process and agent in the selected workspace.

Pane management

bash

verde live pane split --pane <pane-id> --kind chat|terminal --axis horizontal|vertical [--json]
verde live pane focus --pane <pane-id> [--json]
verde live pane resize --first <pane-id> --second <pane-id> --axis horizontal|vertical --ratio <0..1> [--json]
verde live pane move --pane <pane-id> --direction left|right|up|down [--json]
verde live pane minimize --pane <pane-id> [--json]
verde live pane maximize --pane <pane-id> [--json]
verde live pane restore --pane <pane-id> [--json]
verde live pane close --pane <pane-id> [--json]
verde live palette list [--json]
verde live palette run --command pane.split_terminal_down [--json]

Persistent terminal sessions

The session daemon keeps terminal processes addressable independently of a particular visible pane. List and inspect sessions even when the desktop app is not running; persisted metadata remains available if the daemon is offline.

bash

verde session list [--json]
verde session inspect --id <session-id> [--json]
verde session new [--workspace <id>] [--cwd <path>] [--name <name>] -- <command...>
verde session attach --id <session-id>
verde session write --id <session-id> --text $'cargo test\r' [--json]
verde session tail --id <session-id> [--lines <count>] [--json]
verde session screen --id <session-id> [--lines <count>] [--json]
verde session kill --id <session-id> [--json]
verde session cleanup [--json]

attach is interactive. For automation, prefer write, tail, and screen with an explicit session id.

MCP bridge

verde mcp starts a JSONL stdio MCP server that exposes Verde's local live controls to compatible agents. It is primarily used by agent integrations; most users do not invoke it directly. The bridge handles MCP initialization, tool discovery, and tool calls, and requires the relevant live Verde target for operations that control the app.

Provider integrations

Provider hooks are optional add-ons that let agent CLIs drive Verde's sidebar status pips. They never overwrite provider config or change provider login/auth behavior.

bash

verde integrations list [--json]
verde integrations doctor [--json]
verde integrations install <claude|codex|amp|opencode|cursor> [--global]
verde integrations remove <claude|codex|amp|opencode|cursor> [--global]
verde integrations disable <claude|codex|amp|opencode|cursor>

Claude / Codex hooks are project-local (.claude/settings.local.json / .codex/hooks.json); --global installs them in ~/.claude/settings.json / ~/.codex/hooks.json instead.
Amp uses a global lifecycle plugin at ~/.config/amp/plugins/verde-notify.ts (install with --global). The plugin is a no-op outside Verde panes.
OpenCode / Cursor have no stable hook installer yet; list and doctor report them as unsupported.

Remote workspaces (Herdr)

Herdr opens or attaches Verde workspaces on a remote host over SSH and syncs pane state, with handoff to move a local workspace to a remote (and unlink to bring it back) and reusable connection profiles. handoff and unlink require the app to be running.

bash

verde herdr status [--json]
verde herdr open --herdr-workspace <id> --session <name> [--profile <name>|--remote <ssh-alias>] [--remote-cwd <path>] [--local-dir <path>] [--json]
verde herdr handoff [--workspace <id|index|path|current>] [--all] [--session <name>] [--profile <name>|--remote <ssh-alias>] [--remote-cwd <path>] [--dry-run] [--json]
verde herdr unlink [--workspace <id|index|path|current>] [--all] [--json]
verde herdr profiles list [--json]
verde herdr profiles add --name <name> --ssh-target <alias> [--session <name>] [--remote-cwd <path>] [--local-dir <path>] [--json]
verde herdr profiles remove <name> [--json]
verde herdr profiles test <name> [--json]

Terminal surface notifications

Verde terminal children receive identity variables such as VERDE=1, VERDE_SESSION_ID, VERDE_WORKSPACE_ID, VERDE_WORKSPACE_PATH, VERDE_DOCK_ID, VERDE_PANE_ID, VERDE_SOCKET, VERDE_LIVE_SOCKET, VERDE_SESSIONIZER_SOCKET, and VERDE_CLI. Terminal tools can use those variables to update their pane surface:

bash

verde notify --title "Codex needs input" --body "Approve command?" --status waiting
verde notify --status working --progress 0.4 --label "Running tests"
verde notify --status done --title "Agent finished"
verde notify --clear

--status accepts idle, working, waiting, done, or error. Combined with --progress (0..1), it drives the surface's progress bar.

Selectors and exit codes

Use --pane <id> for deterministic automation.
Use --focused for interactive smoke tests.
Use --project current for the selected project, or pass a project index, id, or path.
Chat commands require a chat pane. Terminal commands require a terminal pane.

Exit	Meaning
`0`	CLI command parsed and, for live commands, received a live response.
`1`	Command failure before a structured live response.
`2`	Invalid CLI arguments.
`3`	Live server is not running or not ready.
`4`	Offline state target not found.

Live IPC request failures return JSON error codes such as not_found, invalid_request, invalid_target, rejected, unsupported, or method_not_found. Scripts must check the JSON envelope's ok field, not only the process exit code.

Shell completion

verde completion prints static completion scripts for bash, zsh, fish, and PowerShell. The generated completions cover command names, nested live-control commands, flags, and fixed flag values such as --kind chat|terminal, --axis horizontal|vertical, and --decision approve|deny.

bash

verde completion bash
verde completion zsh
verde completion fish
verde completion powershell

Common install patterns:

bash

# bash
verde completion bash > ~/.local/share/bash-completion/completions/verde

# zsh
mkdir -p ~/.zfunc
verde completion zsh > ~/.zfunc/_verde
# Ensure ~/.zfunc is in fpath before compinit, for example:
# fpath=(~/.zfunc $fpath)

# fish
verde completion fish > ~/.config/fish/completions/verde.fish

The first completion slice is intentionally static so tab completion stays fast and never depends on the desktop app being open. Dynamic project, pane, process, and thread completions can be layered on top of this later.