v42 CLI
Terminals and agents
Create, list, inspect, attach to, send keys or text to, read, wait on, watch, rename, move, and close terminals with v42 term, attach, ws enter, and agents.
The term, attach, ws enter, and agents commands let scripts and coding agents create and control terminals on any online Computer in your Team. Every terminal is a real persistent window on that Computer, shared live with the Vibe42 apps.
Target syntax
Commands that act on an existing terminal take <computer> (ID or name) and <target>:
@N: A window ID (such as@12). Commands that act on a single pane (term send,term read,term wait) use the window's active pane when given@N.%N: A pane ID (such as%5).<session>:@N: The qualified window target returned in.data.targetbyv42 term new.<session>: A tmux session name (supported byv42 term attachandv42 attachto attach to the whole session).
Listing and inspecting terminals
v42 term list [<computer>] [--workspace <workspace>] [--idle] [--busy]
v42 term status <computer> <target>term list: List terminals across all Computers of the Team, or on one<computer>. Without a Computer, offline or unreachable Computers are reported undercomputerswith their status. When you name a Computer (or a Workspace), an offline or unreachable Computer is an error (computer_offlineand so on) instead of an empty list.--workspace <workspace>: Only terminals belonging to this Workspace (ID or name).--idle: Only idle terminals.--busy: Only terminals that are not idle, including those whose state isunknown.
term status <computer> <target>: Show one terminal window, its agent status, and its idle state; a window with several panes also lists each pane underpanes.
The idle rule
Each pane reports foreground as idle (the shell is at its prompt with no foreground program running), busy (a program is running), or unknown (the Computer runs Windows or an older Vibe42, or the terminal was created before Vibe42 was updated).
A terminal is idle only when:
- Every pane's
foregroundisidle, and - Its agent status, if any, is
idleordone(no agent isworking,blocked, or inerror).
When a Computer cannot tell (unknown), the terminal counts as busy. term close, block close, and tab close never close a busy or unknown terminal unless you pass --force.
Creating terminals
v42 term new <computer> [options]Creates a terminal on <computer>, optionally starts an agent or command in it, and places it into the layout of its Workspace (--workspace) or else of the Computer.
| Option | Description |
|---|---|
--workspace <workspace> |
Workspace (ID or name) the terminal belongs to; its directory is the working directory (or a fresh copy when terminal isolation is enabled). Cannot be combined with --cwd. |
--cwd <cwd> |
Working directory on the Computer (when --workspace is not used). |
--name <name> |
Terminal window title. |
--launcher <launcher> |
Agent launcher ID from v42 agents list to start; its display name names the terminal unless --name is given. terminal opens a plain terminal. |
--agent <agent> |
Agent catalog ID (claude-code, codex, omp, pi, opencode, grok-build, devin, antigravity, cursor, …); without --command, its default command runs. |
--command <command> |
Command started in the new terminal (single line, run inside an interactive login shell). |
--tab <tab> |
Open the terminal in this tab (ID, 1-based position, or title), after its last block unless --beside or --float is given. |
--beside <beside> |
Open the terminal next to this block (block ID, %N / @N, or 1-based position in --tab). |
--side <side> |
Side of the --beside block to open on: left, right, up, down, or auto (auto defaults to right). |
--float |
Open the terminal as a floating block in --tab, or in the first tab. |
--no-layout |
Do not place the terminal in any layout (an app showing the layout later gives it a tab of its own). |
--no-balance |
Do not rebalance the split the terminal is placed in. |
--attach |
Attach to the new terminal right after creating it. |
--stdio |
With --attach, relay raw bytes for a program instead of drawing a local terminal. |
Layout effects of term new, term close, and term move
term new: Without placement flags, the new terminal opens as a new tab at the top of the Workspace's (or Computer's) layout; if updating the layout fails, the terminal still exists and.data.layoutreportsplaced: falsewith the error. When--tab,--beside, or--floatis passed, the target placement is validated first so a bad target creates nothing. If an app already opened a block for the new terminal, that block is moved to the requested spot instead of duplicating it.term close: Waits until the Computer confirms the terminals are gone, then removes every block showing them from their Workspace or Computer layout.term move: Moves a window to another Workspace (or out of every Workspace with--none), removes its blocks from the old layout, and opens it as a new tab at the top of the destination layout unless it is already shown there.
Attaching to a terminal
v42 term attach <computer> <target> [--stdio]
v42 attach <computer> <target> [--stdio]
v42 ws enter <workspace> [--stdio]term attach(and its top-level shorthandattach) connects your terminal to<target>on<computer>.ws enter <workspace>creates a new terminal in<workspace>on its Computer and attaches to it immediately.
On Windows computers, term attach can only attach to a whole session, not to a single window or pane.
All three are streaming commands: stdout contains only raw remote PTY bytes, and the exit code comes from the attach client. Disconnecting leaves the remote window running.
Pass --stdio when another program or multiplexer drives stdin/stdout:
- If stdin is not a TTY, local terminal settings are untouched and no window size is sent. When that input ends (for example piped input),
Ctrl+Dis sent to the remote terminal, which ends a shell running there; usev42 term sendfor one-off input instead. - If stdin is a TTY, raw mode is enabled so
Ctrl+Cis sent to the remote terminal, and the local window size is pushed only after the process forwards its first input byte (and on subsequent resize events). - When run inside a Herdr pane on macOS or Linux (
HERDR_ENV=1andHERDR_PANE_ID),attachtags the Herdr pane withv42_computerandv42_paneand streams the pane's agent status to Herdr until detach (for a window or pane target; a whole-session target only getsv42_computerand reports no status).
Sending input and reading the screen
v42 term send <computer> <target> [<text>] [--stdin] [--enter] [--key <key>]... [--paste] [--raw]
v42 term read <computer> <target> [--history <lines> | --all] [--raw]term send
Types text or presses keys in <target> without changing what other viewers see. When several inputs are combined, <text> (or --stdin) is typed first, then each --key in order, then --enter.
--stdin: Read the text to send from standard input (up to 8 MiB).--enter: Press Enter after the text and keys.--key <key>: Repeatable. Key names:enter,tab,backtab,escape,backspace,insert,delete,home,end,pageup,pagedown,up,down,left,right,space,f1–f35, or one character. Modifiers:ctrl+,alt+,shift+,super+(for examplectrl+c,alt+x,shift+tab) or tmux styleC-,M-,S-(C-c,M-x,S-Tab).--paste: Wrap the text in bracketed-paste markers (ESC[200~…ESC[201~) so shells and agents treat multi-line input as a single paste.--raw: Send the bytes exactly as given, including non-UTF-8 input (--enterappends a carriage return;--keycannot be combined with--raw).
term read
Prints the visible screen of <target> in .data.lines (or as lines with --format text), with trailing blank lines dropped.
--history <lines>: Include up to<lines>of scrollback history before the visible screen.--all: Include the entire scrollback history before the visible screen.--raw: Keep ANSI escape sequences (history lines keep their colors, and the visible screen is the raw VT stream split at line feeds).
Waiting for states and watching events
v42 term wait --until <state> [--match <pattern>] [--timeout <seconds>] <computer> <target>
v42 term watch [<computer>] [--workspace <workspace>] [--timeout <seconds>] [--count <count>]term wait
Blocks until <target> reaches --until <state>, then returns the terminal state as JSON. If --timeout <seconds> (default 600; 0 waits without limit) elapses first, term wait fails with error code wait_timeout and exit code 8.
--until value |
When it returns |
|---|---|
idle |
The shell is back at its prompt and no agent is working, blocked, or in error: after a busy period, or once the screen has stayed unchanged for 1.5 s. Needs an up-to-date Vibe42 on the Computer; not available on Windows computers (idle_windows_unsupported). |
done |
The agent finished its turn: immediately after a state transition seen during the wait, or once it has stayed done for 1.5 s. |
blocked |
The agent is waiting for the user (permission, question, or sign-in). Returns immediately if already true. |
error |
The agent reported an error. Returns immediately if already true. |
working |
The agent is working. Returns immediately if already true. |
gone |
The window (or the pane, when a pane target was given) closed; returns immediately with already_gone if it does not exist when the wait starts. |
output |
The visible screen changed; with --match <pattern>, waits until a new screen line matches the regular expression <pattern>. |
term watch
Streams terminal changes as newline-delimited JSON (NDJSON) on stdout:
- One
readyline per watched Computer (orunavailableif a Computer cannot be watched) - Change events:
terminal_added,terminal_removed,renamed,workspace_changed,agent_status, andforeground - A final
stoppedline when--count <count>change events have been emitted or--timeout <seconds>has elapsed
Omit <computer> to watch all online Computers in the Team, or pass --workspace <workspace> to filter events to one Workspace.
Renaming, moving, and closing terminals
v42 term rename <computer> <target> [<name> | --reset]
v42 term move <computer> <window> <--workspace <workspace> | --none>
v42 term close <computer> [<targets>...] [--force] [--idle [--workspace <workspace>] [--dry-run]] [--no-balance]term rename: Set a custom title (up to 64 characters, trimmed) on a window@Nor pane%N, or pass--resetto restore its automatic title.term move: Move a window@Nto--workspace <workspace>on the same Computer, or out of every Workspace with--none, and update both layouts.term close: Close one or more windows or panes (<targets>...) or close every idle terminal on<computer>(--idle).- If any named target is not idle (or its state is
unknown), nothing is closed and the command fails withterminal_busy(exit2) unless--forceis given. - With
--idle, only idle terminals owned by Vibe42 on<computer>(optionally filtered by--workspace) are closed; busy terminals and windows mirrored from Herdr or external tmux sessions (external_source) are left untouched and listed under.data.skipped. Pass--dry-runwith--idleto list what would be closed without closing anything. - Pass
--no-balanceto leave remaining split ratios unchanged after removing the closed terminals' blocks.
- If any named target is not idle (or its state is
Managing agent launchers (v42 agents)
The agent launchers shown in the apps' new-terminal flow and used by v42 term new --launcher <id> are synced across your account and can be managed from the CLI:
v42 agents list
v42 agents add --command <command> [--name <name>] [--agent <agent>]
v42 agents edit <id> [--name <name>] [--command <command>]
v42 agents rm <id>
v42 agents move --index <index> <id>
v42 agents resetagents list: List your configured launchers (or the default list while uncustomized) alongside the built-in agent catalog.agents add --command <command>: Add a custom launcher at the end of the list (assigned IDcustom-<n>).<command>is one line of at most 1024 bytes, not starting with-.--name <name>sets the display name (up to 64 characters);--agent <agent>binds it to a catalog ID for status detection.agents edit <id>: Update a launcher's--name(pass--name ""to restore the default name) or--command.agents rm <id>: Remove a launcher from your list.agents move --index <index> <id>: Move a launcher to a 1-based position.agents reset: Restore the default agent launchers, dropping all customizations.