Frank
047f264fcf
`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
107 lines
3.3 KiB
Markdown
107 lines
3.3 KiB
Markdown
# Ghostty Terminal — Overview
|
|
|
|
[Ghostty](https://ghostty.org) 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](configuration.md) 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
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```ini
|
|
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
|
|
|
|
```ini
|
|
# 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](configuration.md#custom-shaders) — `custom-shader` (repeatable) and
|
|
`custom-shader-animation`, plus the uniform list (`iChannel0`, resolution, time, cursor,
|
|
palette, focus).
|
|
* [Default Keybindings](configuration.md#appendix-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](configuration.md) for every option, organized by category.
|
|
- The [AGENTS.md Format](../../core/agents-md-format.md) governs how agent behavior contracts reference this configuration.
|