Operating Ghostty
Treat the installed binary and its help output as the source of truth because Ghostty behavior varies by version, build, and platform.
Establish Context
- Run
command -v ghostty, ghostty +version, and ghostty --help before relying on remembered syntax.
- Run
ghostty +<cli-action> --help before using a helper action whose flags or effects are uncertain.
- Use
ghostty +help to list CLI helper actions.
- Use
ghostty +list-actions --docs to list documented keybind and command-palette actions.
- Use
ghostty +list-keybinds --plain for active keybinds and add --default when inspecting built-in bindings.
Do not confuse the two action systems.
CLI helper actions have names such as +show-config and are invoked as commands.
Names from +list-actions, such as new_tab, reload_config, and toggle_fullscreen, are configuration actions and cannot generally be invoked as ghostty +<name>.
Keep Commands Non-Interactive
- Add
--plain to +list-themes, +list-keybinds, and other listing commands when available.
- Do not run
ghostty +edit-config because it opens an interactive editor.
- Do not launch an interactive child command with
ghostty -e from an agent shell.
- Do not invoke crash, quit, close, reset, clear, or other disruptive behavior unless the user explicitly requested that exact effect.
- Treat unsupported-action errors as platform or build evidence instead of retrying with guessed syntax.
Inspect and Troubleshoot
- Use
ghostty +show-config --changes-only to inspect effective non-default settings.
- Use
ghostty +show-config --default --docs only when full option documentation is needed because its output is large.
- Use
ghostty +list-fonts --family='<family>' to diagnose font discovery.
- Use
ghostty +show-face --string='<text>' or --cp=<codepoint> to identify the selected font face.
- Use
ghostty +list-themes --plain with --color=dark, --color=light, or --color=all to discover theme names without opening the preview TUI.
- Use
ghostty +list-colors --plain for named colors.
Report the Ghostty version, platform-relevant limitation, command evidence, and the smallest next action that resolves the request.
Change Configuration
- Inspect
ghostty +edit-config --help and existing platform-specific config paths without launching the editor.
- Prefer the existing non-empty config selected by Ghostty, and do not create competing config files in multiple locations.
- Read the current file and
ghostty +show-config --changes-only before editing it.
- For a keybind, confirm the action and argument with
ghostty +list-actions --docs, then inspect current and default bindings for trigger conflicts.
- Add the smallest requested setting in Ghostty configuration syntax, such as
keybind = super+t=new_tab.
- Run
ghostty +validate-config --config-file='<path>' after editing.
- Re-read the changed lines and relevant
+show-config or +list-keybinds --plain output.
- Explain that reloading is an in-app keybind or menu action rather than inventing a
ghostty +reload_config command.
Preserve comments and unrelated settings.
Do not overwrite an existing keybind unless the user requested that conflict resolution.
Check action documentation for platform restrictions before adding a binding.
Launch Ghostty
On macOS, direct CLI launching is unsupported, so use open -na Ghostty.app and pass configuration arguments only with open -na Ghostty.app --args ....
On supported non-macOS builds, use the launch syntax shown by the installed ghostty --help.
Do not claim that a window opened successfully without observable process, window, or command evidence.
1---
2name: operate-ghostty
3description: Inspect, launch, configure, validate, and troubleshoot an installed Ghostty terminal, including helper CLI actions, keybind actions, themes, fonts, configuration files, and platform-specific behavior.
4metadata:
5 source: https://skillmd.com/skills/narumiruna/operate-ghostty
6---
7
8# Operating Ghostty
9
10Treat the installed binary and its help output as the source of truth because Ghostty behavior varies by version, build, and platform.
11
12## Establish Context
13
141. Run `command -v ghostty`, `ghostty +version`, and `ghostty --help` before relying on remembered syntax.
152. Run `ghostty +<cli-action> --help` before using a helper action whose flags or effects are uncertain.
163. Use `ghostty +help` to list CLI helper actions.
174. Use `ghostty +list-actions --docs` to list documented keybind and command-palette actions.
185. Use `ghostty +list-keybinds --plain` for active keybinds and add `--default` when inspecting built-in bindings.
19
20Do not confuse the two action systems.
21CLI helper actions have names such as `+show-config` and are invoked as commands.
22Names from `+list-actions`, such as `new_tab`, `reload_config`, and `toggle_fullscreen`, are configuration actions and cannot generally be invoked as `ghostty +<name>`.
23
24## Keep Commands Non-Interactive
25
26- Add `--plain` to `+list-themes`, `+list-keybinds`, and other listing commands when available.
27- Do not run `ghostty +edit-config` because it opens an interactive editor.
28- Do not launch an interactive child command with `ghostty -e` from an agent shell.
29- Do not invoke crash, quit, close, reset, clear, or other disruptive behavior unless the user explicitly requested that exact effect.
30- Treat unsupported-action errors as platform or build evidence instead of retrying with guessed syntax.
31
32## Inspect and Troubleshoot
33
34- Use `ghostty +show-config --changes-only` to inspect effective non-default settings.
35- Use `ghostty +show-config --default --docs` only when full option documentation is needed because its output is large.
36- Use `ghostty +list-fonts --family='<family>'` to diagnose font discovery.
37- Use `ghostty +show-face --string='<text>'` or `--cp=<codepoint>` to identify the selected font face.
38- Use `ghostty +list-themes --plain` with `--color=dark`, `--color=light`, or `--color=all` to discover theme names without opening the preview TUI.
39- Use `ghostty +list-colors --plain` for named colors.
40
41Report the Ghostty version, platform-relevant limitation, command evidence, and the smallest next action that resolves the request.
42
43## Change Configuration
44
451. Inspect `ghostty +edit-config --help` and existing platform-specific config paths without launching the editor.
462. Prefer the existing non-empty config selected by Ghostty, and do not create competing config files in multiple locations.
473. Read the current file and `ghostty +show-config --changes-only` before editing it.
484. For a keybind, confirm the action and argument with `ghostty +list-actions --docs`, then inspect current and default bindings for trigger conflicts.
495. Add the smallest requested setting in Ghostty configuration syntax, such as `keybind = super+t=new_tab`.
506. Run `ghostty +validate-config --config-file='<path>'` after editing.
517. Re-read the changed lines and relevant `+show-config` or `+list-keybinds --plain` output.
528. Explain that reloading is an in-app keybind or menu action rather than inventing a `ghostty +reload_config` command.
53
54Preserve comments and unrelated settings.
55Do not overwrite an existing keybind unless the user requested that conflict resolution.
56Check action documentation for platform restrictions before adding a binding.
57
58## Launch Ghostty
59
60On macOS, direct CLI launching is unsupported, so use `open -na Ghostty.app` and pass configuration arguments only with `open -na Ghostty.app --args ...`.
61On supported non-macOS builds, use the launch syntax shown by the installed `ghostty --help`.
62Do not claim that a window opened successfully without observable process, window, or command evidence.