Ghostty Cheatsheet

CLI and Actions

Use this Ghostty reference while you build software engineering projects, review code, or refresh the syntax you reach for most.

The `+action` convention

Ghostty's CLI subcommands are prefixed with +. That is a deliberate design choice: everything without a + is treated as the program to run in a terminal, so ghostty vim opens a terminal running vim while ghostty +version runs the version action.

ghostty --help              # top-level usage
ghostty +help               # same thing
ghostty +list-actions       # every keybind action name

On macOS the binary lives inside the app bundle. Add it to your PATH or call it by full path:

/Applications/Ghostty.app/Contents/MacOS/ghostty +version

Actions in Ghostty 1.3.1

Action	What it does
`+version`	version, build config, and Zig version
`+help`	usage for Ghostty or for a specific action
`+show-config`	dump the current configuration
`+validate-config`	parse a config and report errors, exit non-zero on failure
`+edit-config`	open the config file in `$EDITOR`, creating it if absent
`+list-fonts`	every font face Ghostty can discover, grouped by family
`+show-face`	which face Ghostty picks for a given string and style
`+list-themes`	browse the ~450 bundled themes interactively
`+list-colors`	every named color Ghostty accepts in color options
`+list-keybinds`	current keybinds, or the defaults
`+list-actions`	every valid keybind action, with docs
`+ssh-cache`	list or clear the terminfo-installed host cache
`+crash-report`	list and inspect saved crash reports
`+new-window`	open a new window in the running instance
`+boo`	plays the Ghostty animation

+ssh, +explain-config, +new-tab, and +toggle-quick-terminal are not in 1.3.x. They arrive with 1.4.0.

Inspecting configuration

+show-config is the fastest way to answer "did that option take".

ghostty +show-config                        # non-default values only
ghostty +show-config --default              # every option at its default
ghostty +show-config --changes-only=false   # every option, current value
ghostty +show-config --docs                 # add doc comments

--changes-only defaults to true, which is why a bare +show-config prints a short list. Combine --default --docs to get the full annotated reference offline, which is the same content as the docs site for exactly your build.

+validate-config checks syntax without launching anything, so it belongs in a dotfiles CI job:

ghostty +validate-config
ghostty +validate-config --config-file=./ghostty.test

Inspecting keybinds and actions

ghostty +list-keybinds                # your current binds
ghostty +list-keybinds --default      # shipped defaults, ignoring your config
ghostty +list-keybinds --plain        # no colors, pipe-friendly
ghostty +list-keybinds --docs         # with the action documentation

--plain is implied when stdout is not a TTY. Pair the two lists to see exactly what you have overridden:

diff <(ghostty +list-keybinds --default --plain) \
     <(ghostty +list-keybinds --plain)

+list-actions prints the action names accepted on the right side of a keybind. Grep it before inventing a name:

ghostty +list-actions --docs | grep -A3 goto_split

Fonts from the command line

ghostty +list-fonts                        # all families and styles
ghostty +list-fonts --family="JetBrains Mono"
ghostty +show-face --string="=> x" --style=bold
ghostty +show-face --string="🙂" --cp=128512

+list-fonts shows what the font discovery layer actually sees, which settles "Ghostty cannot find my font" arguments quickly. +show-face goes further and tells you which face wins for a given string, including the fallback chain for emoji and symbols. --cp takes a decimal codepoint.

Launching and controlling instances

Any CLI flag mirrors a config key, so config can be overridden per launch:

ghostty --font-size=18 --theme=dracula
ghostty --config-file=/tmp/minimal.conf
ghostty --config-default-files=false --font-family="Menlo"
ghostty -e nvim ~/.config/ghostty/config.ghostty

--config-default-files=false skips your normal config entirely, which is the clean way to reproduce a bug without your settings. -e runs a command with arguments in a new terminal.

+new-window talks to an already running Ghostty rather than starting a second instance. On Linux it uses D-Bus, so the running instance must have gtk-single-instance behavior available.

ghostty +new-window
ghostty +new-window --class=com.mitchellh.ghostty

Crash reports

Ghostty writes crash reports locally and never uploads them.

ghostty +crash-report              # list saved reports

Reports live under $XDG_STATE_HOME/ghostty/crash on Linux and in ~/Library/Application Support/com.mitchellh.ghostty/crash on macOS. Attach the relevant .ghosttycrash file plus ghostty +version output to a bug report.