---
title: "WezTerm CLI Subcommands"
aliases: [wezterm-cli, wezterm-cli-panes, wezterm-cli-tabs]
tags: [wezterm, cli, terminal, multiplexer, panes, tabs, scripting]
sources: [raw/wezterm cli - Wez's Terminal Emulator.md]
created: 2026-04-17
updated: 2026-04-17
---

## WezTerm CLI Subcommands

`wezterm cli` is a subcommand that interacts with a **running** WezTerm GUI or multiplexer instance. It enables scripting: spawn programs, move/resize/kill panes, rename tabs and workspaces, send text, and more — all from the shell.

---

## Targeting the Correct Instance

WezTerm resolves *which* running process to connect to with this priority:

1. `--prefer-mux` flag → reads `wezterm.lua` for the first **unix domain** defined in config
2. `$WEZTERM_UNIX_SOCKET` env var → uses that socket path directly
3. Auto-detect a running GUI instance (use `--class` to disambiguate if multiple windows exist)

> **Tip:** Inside a WezTerm pane, `$WEZTERM_UNIX_SOCKET` is already set — scripts just work.

---

## Targeting Panes

Most subcommands accept an optional `--pane-id` argument. Resolution order when omitted:

1. `$WEZTERM_PANE` env var (set automatically inside every WezTerm pane)
2. Most-recently-interacted session's focused pane

See [[wiki/dotfiles/wezterm-cli-reference|WezTerm CLI Reference]] for global flags and the `list` output format.

---

## Subcommand Reference

### Pane Management

| Subcommand | What it does |
|------------|-------------|
| `split-pane` | Split the current (or target) pane horizontally or vertically |
| `kill-pane` | Close a pane by ID |
| `zoom-pane` | Toggle zoom on a pane |
| `activate-pane` | Bring a specific pane into focus |
| `activate-pane-direction` | Focus the pane in a cardinal direction (Left/Right/Up/Down/Next/Prev) |
| `get-pane-direction` | Return the pane ID in a given direction |
| `adjust-pane-size` | Resize a pane by N cells in a direction |
| `move-pane-to-new-tab` | Detach a pane and place it in a new tab |

### Tab & Window Management

| Subcommand | What it does |
|------------|-------------|
| `activate-tab` | Switch to a tab by index or ID |
| `set-tab-title` | Rename a tab |
| `set-window-title` | Rename the OS window |
| `spawn` | Spawn a new tab or pane running a given program |

### Text & Data

| Subcommand | What it does |
|------------|-------------|
| `send-text` | Send text (as if typed) to a pane — useful for automation |
| `get-text` | Retrieve the visible text content of a pane |

### Workspace & Session

| Subcommand | What it does |
|------------|-------------|
| `rename-workspace` | Rename the current or a named workspace |

### Introspection

| Subcommand | What it does |
|------------|-------------|
| `list` | List all windows, tabs, and panes with their IDs |
| `list-clients` | List connected clients (GUI processes / mux sessions) |

---

## Common Scripting Patterns

```bash
# Split current pane vertically and run a command
wezterm cli split-pane -- fish -c "npm run dev"

# Send text to the current pane (useful from hooks or other panes)
wezterm cli send-text --no-paste "git status\n"

# Get text from a pane for capture/grep
wezterm cli get-text --pane-id 3

# Rename the active tab
wezterm cli set-tab-title "API Server"

# Move a pane to a new tab
wezterm cli move-pane-to-new-tab --pane-id $WEZTERM_PANE

# Zoom the current pane
wezterm cli zoom-pane --pane-id $WEZTERM_PANE
```

---

## Key Takeaways

- `wezterm cli` only works when a WezTerm GUI or mux server is already running
- `$WEZTERM_PANE` and `$WEZTERM_UNIX_SOCKET` are set inside every pane — scripts are self-targeting by default
- `split-pane`, `spawn`, and `send-text` are the most useful for shell automation and task runners
- `get-text` enables pane scraping — combine with `grep` for lightweight pane monitoring
- `list` gives you numeric IDs for all windows/tabs/panes; pipe through `jq` for scripting
- `move-pane-to-new-tab` is the CLI equivalent of dragging a pane out into its own tab

---

## Related Articles

- [[wiki/dotfiles/wezterm-cli-reference|WezTerm CLI Reference]] — global flags, `--prefer-mux`, `wezterm start` / `wezterm ssh`
- [[wiki/dotfiles/wezterm-workspaces|WezTerm Workspaces]] — `rename-workspace` and workspace switching
- [[wiki/dotfiles/wezterm-key-bindings|WezTerm Key Bindings]] — bind CLI subcommands to keys via `wezterm.action.SpawnCommandInNewTab`
- [[wiki/dotfiles/wezterm-pane-to-lua|Pane to Lua]] — passing data back from panes into WezTerm's Lua config

---

## Sources

- `raw/wezterm cli - Wez's Terminal Emulator.md` — clipped from wezterm.org/cli/cli/index.html