111 lines
3.2 KiB
Markdown
111 lines
3.2 KiB
Markdown
---
|
|
title: "WezTerm CLI Reference"
|
|
aliases: [wezterm-cli, wezterm-command-line]
|
|
tags: [wezterm, terminal, cli, dotfiles]
|
|
sources: [raw/CLI Reference - Wez's Terminal Emulator.md]
|
|
created: 2026-04-17
|
|
updated: 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
|
|
|
|
```bash
|
|
# 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 issues
|
|
- `cli` subcommand exposes the experimental multiplexer server API
|
|
- `set-working-directory` emits OSC 7 — useful for shell integrations that track cwd in tab titles
|
|
- `record` / `replay` use asciicast format — compatible with asciinema tooling
|
|
|
|
---
|
|
|
|
## Related Articles
|
|
|
|
- [[wiki/dotfiles/terminal-cheatsheet|Terminal Cheatsheet]] — daily stack reference including WezTerm usage patterns
|
|
- [[wiki/dotfiles/linux-terminal-ricing|Linux Terminal Ricing]] — full setup guide covering terminal emulator choices
|
|
|
|
---
|
|
|
|
## Sources
|
|
|
|
- [WezTerm CLI Reference](https://wezterm.org/cli/general.html) — official docs
|
|
- Raw file: `raw/CLI Reference - Wez's Terminal Emulator.md`
|