Skip to main content

​
Synopsis

wezterm cli [OPTIONS] <SUBCOMMAND>

​
Description

The wezterm cli command provides programmatic control over WezTerm’s multiplexer. It allows you to script window, tab, and pane management, send text to panes, and query the state of your terminal sessions.
This is an experimental interface that may change in future releases.

​
Global Options

​
--no-auto-start
flag
Don’t automatically start the server if it’s not running.
​
--prefer-mux
flag
Prefer connecting to a background mux server rather than a GUI instance.
​
--class
string
When connecting to a GUI instance started with --class SOMETHING, specify the same class name here.

​
Subcommands

The wezterm cli command has numerous subcommands for controlling the multiplexer:

​
list

List windows, tabs, and panes: 
wezterm cli list
wezterm cli list --format json

​
list-clients

List connected clients: 
wezterm cli list-clients

​
split-pane

Split the current pane: 
wezterm cli split-pane
wezterm cli split-pane --horizontal
wezterm cli split-pane -- bash -c "htop"

​
spawn-command

Spawn a new command in a new tab or pane: 
wezterm cli spawn -- bash
wezterm cli spawn --new-window -- vim

​
send-text

Send text to a pane: 
wezterm cli send-text "echo hello"
wezterm cli send-text --pane-id 0 "ls -la"

​
get-text

Get text from a pane’s scrollback: 
wezterm cli get-text
wezterm cli get-text --pane-id 0

​
activate-pane

Activate a specific pane: 
wezterm cli activate-pane --pane-id 0

​
activate-pane-direction

Activate a pane in a direction: 
wezterm cli activate-pane-direction Left
wezterm cli activate-pane-direction Right

​
activate-tab

Activate a specific tab: 
wezterm cli activate-tab --tab-id 0
wezterm cli activate-tab --tab-index 2

​
kill-pane

Kill a pane: 
wezterm cli kill-pane
wezterm cli kill-pane --pane-id 0

​
adjust-pane-size

Adjust pane size: 
wezterm cli adjust-pane-size --amount 5 Left
wezterm cli adjust-pane-size --amount 10 Down

​
zoom-pane

Toggle pane zoom: 
wezterm cli zoom-pane
wezterm cli zoom-pane --pane-id 0

​
move-pane-to-new-tab

Move a pane to a new tab: 
wezterm cli move-pane-to-new-tab --pane-id 0

​
set-tab-title

Set a tab’s title: 
wezterm cli set-tab-title --tab-id 0 "My Tab"

​
set-window-title

Set a window’s title: 
wezterm cli set-window-title "My Window"

​
rename-workspace

Rename a workspace: 
wezterm cli rename-workspace "new-name"

​
Output Formats

Many subcommands support --format to control output:
  • table (default): Human-readable table format
  • json: Machine-readable JSON format
wezterm cli list --format json
wezterm cli list-clients --format table

​
Examples

​
Script Window Layout

#!/bin/bash
# Create a development layout

# Split horizontally for editor and terminal
wezterm cli split-pane -- nvim

# Split the bottom pane vertically
wezterm cli activate-pane-direction Down
wezterm cli split-pane --horizontal -- htop

​
Send Commands to Panes

# Get the pane ID
PANE_ID=$(wezterm cli list --format json | jq -r '.[0].pane_id')

# Send a command
wezterm cli send-text --pane-id $PANE_ID "npm test\n"

​
Monitor Pane Output

# Get text from a pane
wezterm cli get-text --pane-id 0 | grep ERROR

​
Use Cases

  • Automation: Script complex window layouts
  • Testing: Send commands and capture output programmatically
  • Monitoring: Query pane state and content
  • Integration: Connect WezTerm to external tools and workflows

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us