131 lines
4.5 KiB
Markdown
131 lines
4.5 KiB
Markdown
---
|
|
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
|