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

---

## Custom Shaders

Ghostty supports Shadertoy-compatible GLSL shaders:

```ini
custom-shader = ~/.config/ghostty/shaders/vignette.glsl
custom-shader-animation = true
```

Shaders receive uniforms for the terminal screen texture (`iChannel0`), cursor position, palette colors, and focus state.

---

## Default Keybindings

| Keybind | Action |
|---------|--------|
| `ctrl+shift+,` | `reload_config` |
| `ctrl+` / `ctrl+=` | `increase_font_size:1` |
| `ctrl+-` | `decrease_font_size:1` |
| `ctrl+0` | `reset_font_size` |
| `ctrl+shift+f` | `start_search` |
| `ctrl+shift+a` | `select_all` |
| `ctrl+Enter` | `toggle_fullscreen` |
| `ctrl+shift+P` | `toggle_command_palette` |

See [Configuration Reference](configuration.md#appendix-default-keybindings) for the full table.

---

## 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.