| title |
aliases |
tags |
sources |
created |
updated |
| WezTerm CLI Reference |
| wezterm-cli |
| wezterm-command-line |
|
| wezterm |
| terminal |
| cli |
| dotfiles |
|
| raw/CLI Reference - Wez's Terminal Emulator.md |
|
2026-04-17 |
2026-04-17 |
Overview
WezTerm ships two executables:
| Binary |
Use case |
wezterm / wezterm.exe |
Scripting, terminal interaction — use this by default |
wezterm-gui / wezterm-gui.exe |
Launching from a desktop/GUI environment (Windows launchers) |
Windows note: wezterm-gui.exe --help outputs nothing (GUI subsystem has no console). Use wezterm.exe --help instead — it delegates to wezterm-gui under the covers.
Global Options
-n, --skip-config Skip loading wezterm.lua
--config-file <PATH> Override config file path
--config <name=value> Override individual config values at runtime
-h, --help
-V, --version
Subcommands
| Command |
Description |
start / -e |
Start the GUI, optionally running an alternative program |
ssh |
Establish an SSH session |
serial |
Open a serial port |
connect |
Connect to wezterm multiplexer |
ls-fonts |
Display information about fonts |
show-keys |
Show current key assignments |
cli |
Interact with experimental mux server |
imgcat |
Output an image inline in the terminal |
set-working-directory |
Emit OSC 7 escape sequence to advise terminal of cwd |
record |
Record a terminal session as an asciicast |
replay |
Replay an asciicast terminal session |
shell-completion |
Generate shell completion scripts |
Common Usage Patterns
# Start wezterm running fish instead of default shell
wezterm start -- fish
# SSH into a host using wezterm's built-in client
wezterm ssh user@host
# Override a single config value without editing wezterm.lua
wezterm --config enable_tab_bar=false start
# Skip config entirely (useful for debugging)
wezterm -n start
# Generate fish completions
wezterm shell-completion --shell fish | source
# List available fonts
wezterm ls-fonts
# Show all key bindings
wezterm show-keys
# Display an image inline
wezterm imgcat path/to/image.png
# Record a session
wezterm record output.cast
# Replay a recorded session
wezterm replay output.cast
Key Takeaways
- Use
wezterm (not wezterm-gui) for scripting — it auto-delegates to the GUI binary when needed
--config name=value lets you override any wezterm.lua key at runtime without editing the file-n / --skip-config is invaluable for debugging config issuescli subcommand exposes the experimental multiplexer server APIset-working-directory emits OSC 7 — useful for shell integrations that track cwd in tab titlesrecord / replay use asciicast format — compatible with asciinema tooling
Related Articles
Sources
