Files

T

Frank 047f264fcf docs(ghostty): the index stops carrying a second copy of the reference

`tools/ghostty/index.md` had its own Custom Shaders section and its own eight-row default
keybinding table. `configuration.md` owns both, in more detail, and the copies had already
drifted: the index claimed `ctrl+` raises the font size where the reference's appendix lists
`ctrl+=` / `ctrl++`. An index exists to route a reader to the page that owns the fact; a second
summary of the same facts just guarantees two versions that age differently.

What the index keeps is the routing plus the one fact worth having at hand (`ctrl+shift+,`
reloads the config), and the config-syntax "Key Points" — repeatable options, `option = ""`
resets, `?` optional includes — which the reference never states as a set, only per option.

Refs #64

2026-10-21 02:23:25 -07:00

3.3 KiB

Raw Permalink Blame History

Ghostty Terminal — Overview

Ghostty is a cross-platform, GPU-accelerated terminal emulator with an INI-style configuration system, Shadertoy-compatible custom shaders, and a rich CLI for introspection.

See Configuration Reference for the complete option catalog.

CLI Actions

Command	Description
`+version` / `--version`	Display Ghostty version
`+list-fonts`	List all available fonts
`+list-keybinds`	List all current/default keybinds
`+list-themes`	List all available themes
`+list-colors`	List all named RGB colors
`+list-actions`	List all available keybind actions
`+ssh-cache`	Manage SSH terminfo cache
`+edit-config`	Open config file in $EDITOR/$VISUAL
`+show-config`	Show current configuration
`+show-config --default --docs`	Show all options with docs
`+validate-config`	Validate a config file
`+crash-report`	List existing crash reports
`+new-window`	Open new window in running instance

Useful Flag Combinations

# Show all config options with their docs as comments
ghostty +show-config --default --docs

# List fonts with bold styles only
ghostty +list-fonts --bold

# Validate your config without starting Ghostty
ghostty +validate-config

Configuration File Basics

Configuration uses INI-style syntax:

option = value
option = "quoted value with spaces"

Key Points

Repeatable options: font-family, font-feature, palette, env, config-file, command-palette-entry, custom-shader can all be repeated.
Empty string resets: Set option = "" to clear previously set values.
Config includes: Use config-file = "path" to include additional config files.
Optional includes: Prepend ? to suppress errors if file does not exist, for example config-file = "?optional.conf".
CLI overrides: CLI arguments automatically clear config file values for the same option.

Special Prefixes for Commands

direct: — Bypass shell expansion (no glob, tilde, or argument parsing)
shell: — Force shell wrapping

Quick Configuration Examples

# Font setup with fallback
font-family = "JetBrains Mono"
font-family = "Noto Sans Mono"   # fallback for symbols
font-size = 12

# Disable programming ligatures
font-feature = -calt,-liga

# Cursor
cursor-style = block
cursor-style-blink = false

# Window padding
window-padding-x = 2
window-padding-y = 2

# Palette
palette-generate = true

Details that live in the reference

Custom Shaders — custom-shader (repeatable) and custom-shader-animation, plus the uniform list (iChannel0, resolution, time, cursor, palette, focus).
Default Keybindings — the full table. The one you will want first: ctrl+shift+, runs reload_config.

An earlier copy of this index carried its own eight-row keybinding table and its own shader example. Both were subsets of the reference and neither was kept in step with it, which is the usual fate of a second copy.

Cross-References

See Configuration Reference for every option, organized by category.
The AGENTS.md Format governs how agent behavior contracts reference this configuration.

3.3 KiB Raw Permalink Blame History