---
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`