v42 CLI

Tabs, blocks, and layout

Inspect and arrange the tab and block layout of a Workspace or Computer from the CLI with v42 layout, v42 tab, and v42 block.

View as Markdown

Every Workspace and Computer has a per-user tab and block layout—the exact same layout shown in the Vibe42 desktop, web, and mobile apps (see Tabs, blocks and the terminal list). Changes you make with v42 layout, v42 tab, and v42 block appear in your open apps in real time.

Selecting the container (--workspace or --computer)

Every layout, tab, and block command acts on one container layout:

  • Pass --workspace <workspace> (ID or name) to work on a Workspace's layout.
  • Pass --computer <computer> (ID or name) to work on a Computer's layout (which holds terminals not assigned to any Workspace).

Selectors for tabs and blocks

  • <tab>: A tab ID, a 1-based tab position (as numbered in v42 layout show and v42 tab list), or a tab title.
  • <block>: A block ID, a 1-based block position inside --tab, or the terminal target (%N or @N) that the block displays.

Inspecting a layout (v42 layout show)

sh
v42 layout show --workspace <workspace>
v42 layout show --computer <computer>

Prints the tabs and blocks of the layout along with the live state of terminal blocks. Tabs are numbered starting from 1: your own tabs come first, followed by Herdr tabs (source: "herdr").

The layout's .data.state is one of:

  • ready: A saved layout exists on the server.
  • uninitialized: The Workspace or Computer has never been opened in an app or saved yet. The first CLI change that does not reference an existing tab or block ID (such as tab new, term new, or block new --new-tab) initializes the layout from the container's running terminals the same way a Vibe42 app does when opening it for the first time.
  • read_only: Stored layout data failed validation; it is shown with its validation errors and never modified.

Herdr tabs

When a Workspace is bound to Herdr (source: "herdr"), its tabs come from Herdr. Layout changes that Herdr supports (such as closing or moving a tab within its Herdr workspace, or splitting and closing terminal panes) are forwarded to Herdr; operations that Herdr does not support (such as floating blocks or adding non-terminal blocks) fail with error code source_tab_unsupported.

Automatic split balancing and --no-balance

By default, inserting, moving, floating, docking, or closing a block rebalances the split ratios in the affected container when your account's autobalance setting (Auto-balance sizes) is on. Pass --no-balance on term new, term close, block new, block close, block close-others, block move, block float, or block dock to keep existing split proportions untouched for that operation.

Managing tabs (v42 tab)

sh
v42 tab list <--workspace <ws> | --computer <c>>
v42 tab new <--workspace <ws> | --computer <c>> [--title <title>] [--index <index>]
v42 tab close <--workspace <ws> | --computer <c>> <tab> [--force]
v42 tab rename <--workspace <ws> | --computer <c>> <tab> [<title> | --reset]
v42 tab move <--workspace <ws> | --computer <c>> --index <index> <tab>
v42 tab arrange <--workspace <ws> | --computer <c>> <tab> <preset>
  • tab list: List the tabs of the layout with their 1-based positions, titles, sources, and block counts.
  • tab new: Create an empty tab. --title <title> sets a custom title; --index <index> places it at a 1-based position (appended at the end when omitted).
  • tab close <tab>: Close a tab and the terminals it shows, closing the terminals on the Computer first. If any terminal in the tab is busy or has unknown state, --force is required (otherwise the command fails with terminal_busy, exit 2). Closing a Herdr tab closes its Herdr panes and always needs --force (otherwise confirmation_required, exit 2); Vibe42 terminals attached in it keep running, as in the apps.
  • tab rename <tab> [<title>]: Set a custom title on a tab, or pass --reset to restore its automatic title (derived from its first block).
  • tab move --index <index> <tab>: Move a tab to a 1-based position (for a user tab, its position in the layout; for a Herdr tab, its position among the tabs of its Herdr workspace).
  • tab arrange <tab> <preset>: Rearrange all docked blocks in <tab> using one of five presets:
    • columns: Side-by-side vertical columns
    • rows: Stacked horizontal rows
    • grid: Even two-dimensional grid
    • main-side: Large main block on the left, remaining blocks stacked on the right
    • main-stack: Large main block on top, remaining blocks side by side below

Placing and managing blocks (v42 block)

Opening a block (v42 block new)

sh
v42 block new <kind> [<values>...] <--workspace <ws> | --computer <c>> [options]

Opens a block in a tab (--tab <tab>, or --new-tab to open it in a new tab at the top). If the requested resource is already open in the target tab (or anywhere in the layout when --new-tab is used), block new reports existing: true instead of opening a duplicate block.

<kind> <values>... What it opens
terminal [<%N|@N>] Shows an existing terminal on the container's Computer, or starts a new terminal (in the Workspace folder for a Workspace) when omitted
agent [<launcher-id>] Starts a new agent terminal using <launcher-id> from v42 agents list (defaults to the first launcher) and places it
folder <path> Folder tree block rooted at <path> on the Computer
file <path> File preview block for <path> on the Computer
memo [<memo-id>] Workspace memo block (--workspace layouts only)
port <port> Port browser block for <port> on the Computer
desktop (none) Remote Desktop block for the Computer (optionally pass --window <window-id> from v42 desktop windows or --display <display-id>)
folder-follow (none) Folder tree block that follows the focused terminal's working directory

Placement options for block new:

  • --tab <tab>: Tab (ID, 1-based position, or title) to open the block in.
  • --new-tab: Open the block in a new tab at the top of the layout.
  • --beside <beside>: Open next to this block of the tab.
  • --side <left|right|up|down|auto>: Side of --beside to place the block on (auto defaults to right).
  • --end: Place after the last block of the tab (the default when --beside and --float are omitted).
  • --float <x,y,width,height>: Open as a floating block using fractions (0 to 1) of the tab area.
  • --no-balance: Do not rebalance the split the block is placed in.

Moving, swapping, and resizing docked blocks

sh
v42 block move <--workspace <ws> | --computer <c>> <block> [--tab <tab>] [--to-tab <tab> | --new-tab] [--beside <block>] [--side <side>] [--end] [--no-balance]
v42 block swap <--workspace <ws> | --computer <c>> [--tab <tab>] <a> <b>
v42 block resize <--workspace <ws> | --computer <c>> [--tab <tab>] --side <left|right|up|down> --delta <delta> <block>
v42 block equalize <--workspace <ws> | --computer <c>> [--tab <tab>] <block>
v42 block rename <--workspace <ws> | --computer <c>> [--tab <tab>] <block> [<title> | --reset]
  • block move: Move <block> to another spot in the same tab, into --to-tab <tab>, or into --new-tab (placed right after the current tab).
  • block swap: Swap the positions of blocks <a> and <b>.
  • block resize: Move the border on --side <left|right|up|down> of <block> by --delta <delta> (a fraction of the enclosing split, such as 0.1 to grow or -0.1 to shrink).
  • block equalize: Give every block in <block>'s enclosing split equal size.
  • block rename: Set a custom title on <block>, or pass --reset to restore its automatic title.

Floating and docking blocks

sh
v42 block float <--workspace <ws> | --computer <c>> [--tab <tab>] [--rect <x,y,w,h>] [--no-balance] <block>
v42 block dock <--workspace <ws> | --computer <c>> [--tab <tab>] [--beside <block>] [--side <side>] [--end] [--no-balance] <block>
v42 block minimize <--workspace <ws> | --computer <c>> [--tab <tab>] [--restore] <block>
v42 block rect <--workspace <ws> | --computer <c>> [--tab <tab>] <block> <x,y,w,h>
  • block float: Lift <block> into a floating overlay (default rectangle 0.2,0.15,0.6,0.7).
  • block dock: Dock a floating block back into the tab's split tree (at --end or --beside <block> --side <side>).
  • block minimize: Collapse a floating block, or pass --restore to expand it again.
  • block rect: Move and resize a floating block to <x,y,width,height> (fractions 0 to 1 of the tab area).

Closing blocks

sh
v42 block close <--workspace <ws> | --computer <c>> [--tab <tab>] [--force] [--no-balance] <block>
v42 block close-others <--workspace <ws> | --computer <c>> [--tab <tab>] [--force] [--no-balance] <block>
  • block close: Close <block>. For a non-terminal block (file, folder, memo, port, desktop, folder-follow), this simply removes the block from the tab. For a terminal block, it closes the underlying terminal on the Computer first (just like v42 term close) and then removes every block in the layout showing that terminal; if the terminal is busy or unknown, the command fails with terminal_busy (exit 2) unless --force is passed.
  • block close-others: Close every block in <block>'s tab except <block> itself (closing their terminals too; requires --force if any of those terminals is busy). In a Herdr tab it closes the other Herdr panes and leaves attached Vibe42 terminals running, as in the apps; native Herdr panes count as unknown, so --force is required.