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.

View as Markdown

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.target by v42 term new.
  • <session>: A tmux session name (supported by v42 term attach and v42 attach to attach to the whole session).

Listing and inspecting terminals

sh
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 under computers with their status. When you name a Computer (or a Workspace), an offline or unreachable Computer is an error (computer_offline and 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 is unknown.
  • term status <computer> <target>: Show one terminal window, its agent status, and its idle state; a window with several panes also lists each pane under panes.

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:

  1. Every pane's foreground is idle, and
  2. Its agent status, if any, is idle or done (no agent is working, blocked, or in error).

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

sh
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.layout reports placed: false with the error. When --tab, --beside, or --float is 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

sh
v42 term attach <computer> <target> [--stdio]
v42 attach <computer> <target> [--stdio]
v42 ws enter <workspace> [--stdio]
  • term attach (and its top-level shorthand attach) 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+D is sent to the remote terminal, which ends a shell running there; use v42 term send for one-off input instead.
  • If stdin is a TTY, raw mode is enabled so Ctrl+C is 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=1 and HERDR_PANE_ID), attach tags the Herdr pane with v42_computer and v42_pane and streams the pane's agent status to Herdr until detach (for a window or pane target; a whole-session target only gets v42_computer and reports no status).

Sending input and reading the screen

sh
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 example ctrl+c, alt+x, shift+tab) or tmux style C-, 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 (--enter appends a carriage return; --key cannot 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

sh
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:

  1. One ready line per watched Computer (or unavailable if a Computer cannot be watched)
  2. Change events: terminal_added, terminal_removed, renamed, workspace_changed, agent_status, and foreground
  3. A final stopped line 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

sh
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 @N or pane %N, or pass --reset to restore its automatic title.
  • term move: Move a window @N to --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 with terminal_busy (exit 2) unless --force is 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-run with --idle to list what would be closed without closing anything.
    • Pass --no-balance to leave remaining split ratios unchanged after removing the closed terminals' blocks.

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:

sh
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 reset
  • agents 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 ID custom-<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.