Frank
02883d3ed2
Copy of the legacy ~/.pi/agent/docs tree rebuilt as the command-center knowledge base: concept files promoted to path identity, index listings stripped of frontmatter, all wikilinks/relative links resolved, every checkable claim verified against the live fleet (Dankserver = Ryzen 7 7700X + RTX 3090; Strix Halo is Dankclaw), unverifiable claims tagged. kb-lint exits 0.
125 lines
3.5 KiB
Markdown
125 lines
3.5 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
|
|
```
|
|
|
|
---
|
|
|
|
## 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.
|