# 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.

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](/docs/terminal/windows-and-panes)). 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.
