Vadym/obsidian
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
obsidian/wiki/dotfiles/wezterm-cli-subcommands.md
Vadym Samoilenko 0d313f1cd5 vault backup: 2026-04-17 13:25:03
2026-04-17 13:25:03 +01:00

4.5 KiB
Raw Blame History

title aliases tags sources created updated
WezTerm CLI Subcommands
wezterm-cli
wezterm-cli-panes
wezterm-cli-tabs
wezterm
cli
terminal
multiplexer
panes
tabs
scripting
raw/wezterm cli - Wez's Terminal Emulator.md
2026-04-17 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 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

# 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

Sources

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