# Ghostty User Guide

Ghostty is a fast, feature-rich, and cross-platform terminal emulator that uses
platform-native UI and GPU acceleration. It runs on macOS (native AppKit/SwiftUI
app) and Linux (native GTK4 + libadwaita app), reads a single plain-text
configuration file, and ships with a huge set of built-in themes, full keyboard
customization, splits, tabs, a drop-down "quick terminal," a command palette,
GPU-rendered custom shaders, and modern terminal protocols (Kitty graphics,
Kitty keyboard, OSC 8 hyperlinks, and more).

This guide is for people who **use** Ghostty: installing it, configuring it, and
getting the most out of its features. For architecture, build instructions,
packaging, and internals, see the companion **Admin Guide**.

> [!NOTE]
> Ghostty's application identifier is `com.mitchellh.ghostty` and it advertises
> itself to programs as `TERM=xterm-ghostty`. You will see both values referenced
> throughout this guide.

---

## 1. Quick Start

After [installing](#3-installation) Ghostty, launch it like any other
application. Ghostty works out of the box with sensible defaults — no
configuration is required.

To start customizing, create a configuration file and reload:

=== "macOS"

    ```bash
    mkdir -p ~/.config/ghostty
    $EDITOR ~/.config/ghostty/config
    ```

=== "Linux"

    ```bash
    mkdir -p ~/.config/ghostty
    $EDITOR ~/.config/ghostty/config
    ```

Add a few options:

```ini
# ~/.config/ghostty/config
theme = catppuccin-mocha
font-family = JetBrains Mono
font-size = 14
background-opacity = 0.95
keybind = ctrl+shift+enter=new_split:right
```

Reload the configuration without restarting:

- **macOS:** `Cmd+Shift+,`
- **Linux:** `Ctrl+Shift+,`

> [!TIP]
> Run `ghostty +show-config --default --docs` to print every configuration
> option together with its documentation, or open the config in your editor
> directly with `ghostty +edit-config`.

A minimal first-week checklist:

- [ ] Pick a theme: `ghostty +list-themes`
- [ ] Set your font: `ghostty +list-fonts`
- [ ] Learn the default split/tab keybinds: `ghostty +list-keybinds`
- [ ] Bind a quick terminal: `keybind = global:cmd+grave_accent=toggle_quick_terminal`
- [ ] Confirm shell integration is active (cursor turns to a bar at the prompt)

---

## 2. Requirements

| Platform | Requirement |
|----------|-------------|
| **macOS** | macOS 13 (Ventura) or later recommended. Some features (native glass blur, secure input automation, certain icon styles) require newer macOS versions. Apple Silicon and Intel are both supported. |
| **Linux** | A GTK4 + libadwaita desktop. Some features require **libadwaita 1.4+** (tab overview) or **1.5+** (command palette). Wayland or X11. The quick terminal on Linux requires Wayland with the `wlr-layer-shell-v1` protocol. |
| **GPU** | A working GPU/driver: Metal on macOS, OpenGL on Linux. |
| **Shell** | Bash, Zsh, Fish, Elvish, or Nushell for automatic shell integration (others work, just without integration features). |

> [!IMPORTANT]
> Many configuration options are platform-specific. Throughout this guide,
> options are tagged with **macOS only**, **GTK/Linux only**, or **Linux Wayland
> only** where relevant. Setting a platform-specific option on the wrong platform
> is harmless — it is silently ignored.

---

## 3. Installation

### 3.1 macOS

The recommended way to install Ghostty on macOS is to download the official
application from [ghostty.org](https://ghostty.org) or via Homebrew:

=== "Homebrew"

    ```bash
    brew install --cask ghostty
    ```

=== "Manual"

    ```text
    1. Download Ghostty.dmg from ghostty.org
    2. Open the DMG and drag Ghostty.app into /Applications
    3. Launch Ghostty from Spotlight or Finder
    ```

Ghostty on macOS includes a built-in auto-updater (powered by Sparkle). See
[Auto-Update](#1115-auto-update-macos) to control its behavior.

### 3.2 Linux

Ghostty is distributed through Linux package managers and as Flatpak/Snap
packages. Use your distribution's package manager where available:

=== "Flatpak"

    ```bash
    flatpak install flathub com.mitchellh.ghostty
    ```

=== "Snap"

    ```bash
    snap install ghostty --classic
    ```

=== "Distro packages"

    ```text
    Ghostty is packaged for many distributions (Arch, Fedora, NixOS, and others).
    Search your package manager for "ghostty".
    ```

> [!NOTE]
> Ghostty on Linux is distributed via package managers rather than a built-in
> auto-updater, so the `auto-update` options have no effect on Linux.

### 3.3 Build from source

Ghostty is written in [Zig](https://ziglang.org) and uses the Zig build system.
Building from source is covered in detail in the **Admin Guide**, but the short
version is:

```bash
git clone https://github.com/ghostty-org/ghostty
cd ghostty
zig build -Doptimize=ReleaseFast
```

```text
The resulting binary is placed in zig-out/bin/ghostty along with the
"share" resources directory (themes, terminfo, shell integration).
```

> [!WARNING]
> Building requires the exact Zig version declared in `build.zig.zon`
> (`minimum_zig_version`). Using a different Zig version will fail the build.
> See the Admin Guide for the full toolchain and dependency list.

### 3.4 Verify your installation

```bash
ghostty +version
```

```text
Ghostty 1.x.x
Version: ...
Build Config: ...
```

---

## 4. The `ghostty` Command Line

Ghostty is both a GUI application and a CLI. When you run `ghostty` with no
arguments it opens a terminal window. It also exposes a set of utility
**actions**, all invoked with a leading `+`:

```bash
ghostty +<action> [options]
```

You can pass at most one action per invocation. The full reference is in
[Section 12](#12-command-line-actions-reference). The most useful day-to-day
actions are:

| Action | Purpose |
|--------|---------|
| `ghostty +list-themes` | Browse and preview all built-in themes |
| `ghostty +list-fonts` | List font families Ghostty can use |
| `ghostty +list-keybinds` | Show all active keybindings |
| `ghostty +list-actions` | Show all keybind actions you can bind |
| `ghostty +show-config` | Print your current effective configuration |
| `ghostty +edit-config` | Open your config file in your editor |
| `ghostty +validate-config` | Check a config file for errors |

### 4.1 Running a command instead of a shell

Use `-e` to run a specific command instead of your shell:

```bash
ghostty -e nvim ~/.config/ghostty/config
```

```text
Opens a new Ghostty window running the given command directly.
```

> [!NOTE]
> The `-e` flag automatically forces several behaviors: shell expansion is
> disabled (the command is assumed to be pre-expanded), `gtk-single-instance` is
> disabled so a fresh instance is launched, `quit-after-last-window-closed` is
> enabled so Ghostty exits when the command exits, and forced shell-integration
> injection is disabled.

---

## 5. Configuration Basics

### 5.1 File location

Ghostty reads its configuration from the XDG config directory:

```text
$XDG_CONFIG_HOME/ghostty/config
~/.config/ghostty/config          (if XDG_CONFIG_HOME is unset)
```

The file `config.ghostty` is also recognized. The file is plain text and does
not exist by default — create it yourself.

### 5.2 Syntax

The configuration syntax is a simple `key = value` format, one option per line:

```ini
# Comments start with a hash
font-family = JetBrains Mono
font-size = 13
background = 1e1e2e
keybind = ctrl+shift+t=new_tab
```

Rules of the format:

- One `key = value` per line. Whitespace around `=` is ignored.
- Lines beginning with `#` are comments.
- **Repeatable options** (like `font-family`, `keybind`, `palette`, `link`,
  `config-file`) may appear multiple times; each line adds an entry rather than
  overwriting.
- To **reset** a repeatable list, set it to an empty value (e.g. `font-family =`)
  and then add new values.
- Boolean options accept `true`/`false`.

> [!TIP]
> Every configuration key is identical to its command-line flag. Anything you can
> put in the config file you can also pass as `--key=value` on the command line,
> e.g. `ghostty --font-size=16 --theme="Rose Pine"`.

### 5.3 Including other files

Split your configuration across files with `config-file`:

```ini
config-file = themes-and-colors
config-file = keybinds
config-file = ?optional-machine-local
```

- Paths are relative to the file that contains the `config-file` line.
- Prefix a path with `?` to silently ignore it if it does not exist.
- Cycles are detected and rejected.

> [!IMPORTANT]
> Included files are applied **after** the configuration that references them.
> If `base` contains `config-file = override` and both set `font-size`, the value
> in `override` wins because it is loaded last.

### 5.4 Reloading

| Platform | Default keybind |
|----------|-----------------|
| macOS | `Cmd+Shift+,` |
| Linux | `Ctrl+Shift+,` |

You can also bind the `reload_config` action to any key. Note that **not all
options can be applied at runtime** — many only affect newly created terminals,
and a few (e.g. `language`, `async-backend`, `auto-update-channel`) require a
full restart. Such options are noted in the reference below.

### 5.5 Inspecting and validating

```bash
ghostty +show-config              # effective config (only non-defaults)
ghostty +show-config --default    # include defaults
ghostty +show-config --docs       # include documentation comments
ghostty +validate-config          # validate the default config file
ghostty +validate-config --config-file=path/to/config
ghostty +explain-config font-size # explain one option
```

---

## 6. Fonts

Fonts are one of the most-configured aspects of a terminal. Ghostty has rich font
support: fallback chains, per-style families, font features (ligatures), variable
fonts, codepoint mapping, and metric adjustments.

### 6.1 Choosing a font

```ini
font-family = JetBrains Mono
font-size = 13
```

List the fonts Ghostty can find:

```bash
ghostty +list-fonts
```

The `font-size` is in points and may be fractional (e.g. `13.5`). On macOS the
default is `13`; elsewhere it is `12`.

### 6.2 Fallback fonts and per-style families

`font-family` is repeatable. Each additional entry is a **fallback** used when
the primary font lacks a glyph (great for mixing a coding font with a CJK or
symbol font):

```ini
font-family = JetBrains Mono
font-family = Noto Sans CJK SC
```

You can set distinct families per style:

```ini
font-family-bold = JetBrains Mono Bold
font-family-italic = Victor Mono Italic
font-family-bold-italic = Victor Mono Bold Italic
```

> [!NOTE]
> On macOS, emoji default to Apple Color Emoji; on Linux, Noto Emoji. Override by
> adding a font family that contains emoji glyphs.

### 6.3 Disabling and synthesizing styles

`font-style*` options select a named style or disable a style entirely. Set a
style to `false` to disable it (the regular style is used instead):

```ini
font-style = Medium
font-style-italic = false   # never use italics
```

Ghostty can **synthesize** bold/italic/bold-italic when a font lacks them.
Control this with `font-synthetic-style`:

```ini
font-synthetic-style = no-bold-italic   # don't fake bold-italic
```

> [!WARNING]
> Disabling only `bold` or `italic` does **not** disable `bold-italic`. To
> disable faux bold-italic you must list it explicitly.

### 6.4 Ligatures and font features

Apply OpenType features with `font-feature` (repeatable or comma-separated):

```ini
# Disable programming ligatures
font-feature = -calt
# Disable most ligatures
font-feature = -calt, -liga, -dlig
# Enable a stylistic set
font-feature = ss01
```

Feature syntax: `feat`/`+feat`/`feat=1` to enable, `-feat`/`feat=0` to disable,
`feat=2` to set a value.

> [!TIP]
> Use [fontdrop.info](https://fontdrop.info) to discover which features your
> font supports. The default ligature feature in most coding fonts is `calt`.

You can also control where shaping runs are broken with `font-shaping-break`. By
default Ghostty breaks runs under the cursor (`cursor`) so editing sees
individual characters instead of a ligature.

### 6.5 Variable fonts

For variable fonts, set axis values with `font-variation` (and per-style
variants):

```ini
font-family = Recursive
font-variation = wght=500
font-variation = slnt=-8
font-variation-bold = wght=800
```

Axis IDs are 4-character tags such as `wght`, `slnt`, `ital`, `opsz`, `wdth`.

### 6.6 Codepoint mapping

Force specific Unicode ranges to a particular font:

```ini
font-codepoint-map = U+E0A0-U+E0D4=Symbols Nerd Font
font-codepoint-map = U+4E00-U+9FFF=Noto Sans CJK SC
```

### 6.7 Metric adjustments

Fine-tune the cell box and glyph metrics. Values are absolute pixels (`1`, `-2`)
or percentages (`20%`, `-15%`) **relative to the original**:

| Option | Adjusts |
|--------|---------|
| `adjust-cell-width`, `adjust-cell-height` | Cell box size |
| `adjust-font-baseline` | Text baseline |
| `adjust-underline-position`, `adjust-underline-thickness` | Underline |
| `adjust-strikethrough-position`, `adjust-strikethrough-thickness` | Strikethrough |
| `adjust-overline-position`, `adjust-overline-thickness` | Overline |
| `adjust-cursor-thickness`, `adjust-cursor-height` | Cursor |
| `adjust-box-thickness` | Box-drawing characters |
| `adjust-icon-height` | Nerd Font icon max height |

```ini
adjust-cell-height = 10%
adjust-cursor-thickness = 2
```

> [!CAUTION]
> There is little validation on metric adjustments. Extreme values (e.g.
> `-100%`) can make the terminal unusable. Adjust in small steps.

### 6.8 Other font options

| Option | Default | Notes |
|--------|---------|-------|
| `font-thicken` | `false` | Thicker strokes. **macOS only.** |
| `font-thicken-strength` | `255` | 0–255, only when `font-thicken` on. macOS only. |
| `freetype-load-flags` | (hinting, autohint, light on) | FreeType hinting flags. **Linux/FreeType builds only.** |
| `grapheme-width-method` | `unicode` | `unicode` or `legacy` (wcswidth-like). |
| `alpha-blending` | `native` (macOS) / `linear-corrected` (other) | Text/image alpha blend color space: `native`, `linear`, `linear-corrected`. |

Check which font face renders a specific character:

```bash
ghostty +show-face --string="→"
```

---

## 7. Colors and Themes

### 7.1 Using a built-in theme

Ghostty ships with a large collection of themes (the iTerm2 color schemes
collection). Browse them interactively:

```bash
ghostty +list-themes
```

Set one with the `theme` option:

```ini
theme = catppuccin-mocha
```

The theme value can be a built-in name, a custom theme name, or an absolute path
to a theme file. A theme file is simply another Ghostty config file containing
color options.

### 7.2 Light and dark themes

Specify different themes for light and dark mode; Ghostty follows the desktop
appearance:

```ini
theme = light:rose-pine-dawn,dark:rose-pine
```

Both `light:` and `dark:` must be specified.

> [!CAUTION]
> A theme file can set **any** configuration option, not just colors. Do not use
> theme files from untrusted sources. The built-in themes are audited to only set
> safe options. A theme file cannot set `theme` or `config-file`.

### 7.3 Manual colors

Override individual colors. Any of these take precedence over the theme. Colors
are hex (`#RRGGBB` or `RRGGBB`) or a named X11 color (see `ghostty +list-colors`).

```ini
background = 1e1e2e
foreground = cdd6f4
cursor-color = f5e0dc
cursor-text = 1e1e2e
selection-background = 585b70
selection-foreground = cdd6f4
```

| Option | Purpose |
|--------|---------|
| `background`, `foreground` | Window base colors |
| `cursor-color`, `cursor-text` | Cursor and the text under it |
| `selection-background`, `selection-foreground` | Text selection |
| `bold-color` | Color for bold text (a color, or `bright`) |
| `faint-opacity` | Opacity of faint/dim text (default `0.5`) |
| `minimum-contrast` | Force a minimum WCAG contrast ratio (1–21) |
| `split-divider-color` | Color of the divider between splits |
| `unfocused-split-fill` | Dim color for unfocused splits |

> [!TIP]
> `cursor-color`, `cursor-text`, and the selection colors accept the special
> values `cell-foreground` and `cell-background` to match the cell under the
> cursor/selection rather than a fixed color.

### 7.4 The 256-color palette

```ini
palette = 0=#1e1e2e
palette = 1=#f38ba8
# ... indices 0-255, with hex or named colors
```

Indices may be decimal, or prefixed `0b`/`0o`/`0x`. If you only set the first 16
colors, enable `palette-generate = true` to derive the rest (the 6×6×6 cube and
grayscale ramp) automatically. `palette-harmonious = true` reverses the generated
ordering for better light/dark behavior.

### 7.5 Transparency and blur

```ini
background-opacity = 0.92
background-blur = true        # or an integer intensity, default 20
```

- `background-opacity` — 0 (transparent) to 1 (opaque).
- `background-opacity-cells = true` — apply opacity even to cells with explicit
  background colors (useful with Neovim/Tmux).
- `background-blur` — `true`, `false`, or an integer intensity. On macOS 26+ you
  can use `macos-glass-regular` or `macos-glass-clear` for native glass effects.

> [!NOTE]
> Background blur is supported on macOS and some Linux desktops (notably KDE
> Plasma). Under KDE the exact intensity is ignored — KWin has a single global
> blur setting. On macOS, changing `background-opacity` requires a full restart.

### 7.6 Background images

```ini
background-image = ~/Pictures/wallpaper.png
background-image-opacity = 0.5
background-image-position = center
background-image-fit = cover     # contain | cover | stretch | none
background-image-repeat = false
```

PNG and JPEG are supported.

> [!WARNING]
> Background images are currently stored in VRAM per-terminal and repeated across
> splits. Very large images can significantly increase memory (VRAM) usage.

---

## 8. The Cursor

```ini
cursor-style = block          # block | bar | underline | block_hollow
cursor-style-blink = true     # blank = follow program, true, false
cursor-color = f5e0dc
cursor-opacity = 1.0
cursor-click-to-move = true
```

| Option | Default | Notes |
|--------|---------|-------|
| `cursor-style` | `block` | Default style; programs can still override via `DECSCUSR`. |
| `cursor-style-blink` | (unset) | If unset, respects DEC Mode 12; set explicitly to override. |
| `cursor-opacity` | `1.0` | 0–1. Small values can make the cursor invisible. |
| `cursor-click-to-move` | `true` | Click in the prompt to move the cursor (needs shell integration / OSC 133). |

> [!NOTE]
> Shell integration sets the cursor to a bar at the prompt regardless of
> `cursor-style`. Disable that with `shell-integration-features = no-cursor`.

---

## 9. Mouse and Selection

### 9.1 Selection behavior

```ini
copy-on-select = true                 # true | false | clipboard
selection-clear-on-typing = true
selection-clear-on-copy = false
selection-word-chars = "\t '\"│`|:;,()[]{}<>$"
```

- `copy-on-select` — automatically copy selected text. `clipboard` copies to both
  the selection and system clipboards. Default `true` on Linux and macOS.
- `selection-word-chars` — characters that act as word boundaries for
  double-click word selection.

### 9.2 Mouse actions

```ini
right-click-action = context-menu     # context-menu | paste | copy | copy-or-paste | ignore
middle-click-action = primary-paste   # primary-paste | ignore
focus-follows-mouse = false
mouse-hide-while-typing = false
click-repeat-interval = 0             # ms; 0 = platform default
```

### 9.3 Scrolling and mouse reporting

```ini
mouse-scroll-multiplier = 3                   # or precision:0.1,discrete:3
scroll-to-bottom = keystroke,no-output
mouse-reporting = true
mouse-shift-capture = false                   # false | true | always | never
```

- `mouse-reporting` — when `false`, mouse events are never sent to programs, so
  you can always select with the mouse. Toggle at runtime with the
  `toggle_mouse_reporting` action.
- `mouse-shift-capture` — whether holding Shift while clicking sends the mouse
  event to the program or extends the selection.

---

## 10. Windows, Tabs, and Splits

Ghostty organizes terminals into **surfaces** arranged as splits within tabs
within windows.

### 10.1 Splits

Splits divide a tab into multiple terminals. The default binds vary by platform;
see `ghostty +list-keybinds`. Common actions to bind:

```ini
keybind = ctrl+shift+right=new_split:right
keybind = ctrl+shift+down=new_split:down
keybind = ctrl+shift+l=goto_split:right
keybind = ctrl+shift+z=toggle_split_zoom
keybind = ctrl+shift+e=equalize_splits
```

| Action | Effect |
|--------|--------|
| `new_split:right\|down\|left\|up\|auto` | Create a split (`auto` = along the larger axis) |
| `goto_split:left\|right\|up\|down\|previous\|next` | Focus another split |
| `resize_split:up,10` | Resize the focused split by N pixels |
| `equalize_splits` | Make all splits equal size |
| `toggle_split_zoom` | Temporarily maximize the focused split |

Appearance and behavior:

```ini
unfocused-split-opacity = 0.7
split-divider-color = 585b70
split-preserve-zoom = navigation
split-inherit-working-directory = true
```

### 10.2 Tabs

```ini
keybind = ctrl+shift+t=new_tab
keybind = ctrl+shift+page_up=previous_tab
keybind = ctrl+shift+page_down=next_tab
window-new-tab-position = current      # current | end
window-show-tab-bar = auto             # always | auto | never (GTK)
gtk-tabs-location = top                # top | bottom | hidden (GTK)
gtk-wide-tabs = true                   # GTK
```

| Action | Effect |
|--------|--------|
| `new_tab` | Open a new tab |
| `next_tab`, `previous_tab`, `last_tab` | Navigate tabs |
| `goto_tab:N` | Jump to tab N (1-based) |
| `move_tab:N` | Move the current tab by a relative offset (wraps) |
| `toggle_tab_overview` | Tab overview (**Linux, libadwaita 1.4+**) |
| `prompt_tab_title`, `set_tab_title:...` | Rename the tab |

### 10.3 Windows

```ini
keybind = ctrl+shift+n=new_window
window-height = 40        # initial size, in grid cells
window-width = 120
window-padding-x = 4
window-padding-y = 4
window-padding-balance = true
maximize = false
fullscreen = false        # false | true | non-native (macOS) | ...
window-save-state = default   # macOS: default | never | always
window-inherit-working-directory = true
window-inherit-font-size = true
```

| Action | Effect |
|--------|--------|
| `new_window` | Open a new window |
| `close_surface` / `close_tab` / `close_window` | Close (may confirm) |
| `toggle_fullscreen` | Fullscreen/unfullscreen |
| `toggle_maximize` | Maximize (**Linux**; macOS has no maximize concept) |
| `goto_window:previous\|next` | Switch windows |
| `toggle_window_float_on_top` | Always-on-top (**macOS**) |
| `reset_window_size` | Reset to default size (**macOS**) |

> [!NOTE]
> On macOS, native tabs and native fullscreen require the titlebar. **Tabs do not
> work with non-native fullscreen modes.** If you use tabs, use native
> fullscreen (`fullscreen = true`).

---

## 11. Configuration Reference

This section is the exhaustive option reference, grouped by area. Defaults shown
are the cross-platform defaults unless noted. Platform tags: **[mac]** macOS
only, **[gtk]** GTK/Linux only, **[wl]** Linux Wayland only.

### 11.1 Fonts

| Option | Default | Description |
|--------|---------|-------------|
| `font-family` (+ `-bold`/`-italic`/`-bold-italic`) | system | Font families; repeatable for fallback. |
| `font-style` (+ variants) | default | Named style or `false` to disable. |
| `font-synthetic-style` | all on | Synthesize missing styles; `no-bold`, `no-italic`, `no-bold-italic`. |
| `font-feature` | — | OpenType features (e.g. `-calt`). Repeatable. |
| `font-size` | `13`/`12` | Point size, fractional allowed. |
| `font-variation` (+ variants) | — | Variable-font axis values (`wght=500`). |
| `font-codepoint-map` | — | Map codepoint ranges to a font. |
| `font-thicken` / `font-thicken-strength` | `false` / `255` | **[mac]** Thicker strokes. |
| `font-shaping-break` | `cursor` | Where to break shaping runs. |
| `alpha-blending` | platform | `native`, `linear`, `linear-corrected`. |
| `adjust-*` (cell/underline/cursor/box/etc.) | — | Metric tweaks (px or %). |
| `grapheme-width-method` | `unicode` | `unicode` or `legacy`. |
| `freetype-load-flags` | hinting on | **[gtk]** FreeType hinting. |

### 11.2 Colors and appearance

| Option | Default | Description |
|--------|---------|-------------|
| `theme` | — | Theme name/path, or `light:…,dark:…`. |
| `background` / `foreground` | `#282C34` / `#FFFFFF` | Base colors. |
| `palette` | xterm | 256-color palette entries `N=COLOR`. |
| `palette-generate` / `palette-harmonious` | `false` | Auto-generate 16→255. |
| `cursor-color` / `cursor-text` | auto | Cursor colors (or `cell-*`). |
| `selection-foreground` / `selection-background` | inverted | Selection colors (or `cell-*`). |
| `bold-color` | — | Color or `bright` for bold text. |
| `faint-opacity` | `0.5` | Faint/dim text opacity. |
| `minimum-contrast` | `1` | WCAG min contrast (1–21). |
| `background-opacity` | `1.0` | Window opacity. |
| `background-opacity-cells` | `false` | Apply opacity to colored cells too. |
| `background-blur` | `false` | Blur behind transparent bg. |
| `background-image` (+ `-opacity`/`-position`/`-fit`/`-repeat`) | — | Background image. |
| `unfocused-split-opacity` / `unfocused-split-fill` | `0.7` / bg | Unfocused split dimming. |
| `split-divider-color` | auto | Split divider. |
| `window-colorspace` | `srgb` | **[mac]** `srgb` or `display-p3`. |

### 11.3 Cursor and mouse

| Option | Default | Description |
|--------|---------|-------------|
| `cursor-style` | `block` | `block`, `bar`, `underline`, `block_hollow`. |
| `cursor-style-blink` | unset | Blink override. |
| `cursor-opacity` | `1.0` | Cursor opacity. |
| `cursor-click-to-move` | `true` | Click to move cursor at prompt. |
| `mouse-hide-while-typing` | `false` | Hide cursor while typing. |
| `mouse-shift-capture` | `false` | Shift+click → program or selection. |
| `mouse-reporting` | `true` | Allow programs to capture the mouse. |
| `mouse-scroll-multiplier` | `3`/`1` | Scroll speed. |
| `scroll-to-bottom` | `keystroke,no-output` | Auto-scroll triggers. |
| `copy-on-select` | `true` | Auto-copy selection. |
| `right-click-action` | `context-menu` | Right-click behavior. |
| `middle-click-action` | `primary-paste` | Middle-click behavior. |
| `focus-follows-mouse` | `false` | Mouse over a split focuses it. |
| `click-repeat-interval` | `0` | Multi-click interval (ms). |
| `selection-clear-on-typing` | `true` | Clear selection on keypress. |
| `selection-clear-on-copy` | `false` | Clear selection after copy. |
| `selection-word-chars` | (punctuation) | Word boundaries for selection. |

### 11.4 Window and layout

| Option | Default | Description |
|--------|---------|-------------|
| `window-height` / `window-width` | `0` | Initial size in cells. |
| `window-position-x` / `-y` | unset | **[mac]** Initial position (px). |
| `window-padding-x` / `-y` | `2,2` | Padding (px @ DPI). |
| `window-padding-balance` | `false` | Balance leftover padding. |
| `window-padding-color` | `background` | `background`, `extend`, `extend-always`. |
| `window-decoration` | `auto` | `none`, `auto`, `client`, `server`. |
| `window-theme` | `auto` | `auto`, `system`, `light`, `dark`, `ghostty`. |
| `window-title-font-family` | system | Titlebar font. |
| `window-subtitle` | `false` | **[gtk]** `working-directory`. |
| `window-vsync` | `true` | **[mac]** VSync. |
| `window-save-state` | `default` | **[mac]** Save/restore window state. |
| `window-step-resize` | `false` | **[mac]** Resize in cell steps. |
| `window-new-tab-position` | `current` | `current` or `end`. |
| `window-show-tab-bar` | `auto` | **[gtk]** `always`/`auto`/`never`. |
| `window-titlebar-background` / `-foreground` | — | **[gtk]** Titlebar colors (needs `window-theme=ghostty`). |
| `window-inherit-working-directory` | `true` | Inherit cwd for new windows. |
| `window-inherit-font-size` | `true` | Inherit font size. |
| `tab-inherit-working-directory` | `true` | Inherit cwd for new tabs. |
| `split-inherit-working-directory` | `true` | Inherit cwd for new splits. |
| `maximize` | `false` | Start maximized. |
| `fullscreen` | `false` | Start fullscreen. |
| `title` | — | Force a fixed window title. |
| `class` | `com.mitchellh.ghostty` | **[gtk]** WM_CLASS / app ID. |
| `x11-instance-name` | `ghostty` | **[gtk]** X11 instance name. |
| `working-directory` | `inherit` | Initial directory (`home`/`inherit`/path). |
| `resize-overlay` (+ `-position`/`-duration`) | `after-first` | Size overlay popup. |
| `split-preserve-zoom` | off | Keep zoom on navigation. |
| `focus-follows-mouse` | `false` | See mouse section. |

### 11.5 Scrollback and scrollbar

| Option | Default | Description |
|--------|---------|-------------|
| `scrollback-limit` | `10000000` (10 MB) | Per-surface scrollback (bytes, in memory). |
| `scrollbar` | `system` | `system` or `never`. |

### 11.6 Clipboard and selection safety

| Option | Default | Description |
|--------|---------|-------------|
| `clipboard-read` | `ask` | OSC 52 read: `ask`/`allow`/`deny`. |
| `clipboard-write` | `allow` | OSC 52 write: `ask`/`allow`/`deny`. |
| `clipboard-trim-trailing-spaces` | `true` | Trim trailing whitespace on copy. |
| `clipboard-paste-protection` | `true` | Confirm unsafe (multiline) pastes. |
| `clipboard-paste-bracketed-safe` | `true` | Treat bracketed pastes as safe. |
| `clipboard-codepoint-map` | — | Replace codepoints on copy. |

### 11.7 Command and process

| Option | Default | Description |
|--------|---------|-------------|
| `command` | `$SHELL`/passwd | Command for all surfaces. Prefix `direct:` or `shell:`. |
| `initial-command` | — | Command for the first surface only. |
| `env` | — | Extra env vars (`env = KEY=VALUE`, repeatable). |
| `input` | — | Data to send to the pty on startup (`raw:`/`path:`). |
| `wait-after-command` | `false` | Keep window open after command exits. |
| `abnormal-command-exit-runtime` | `250` | ms below which an exit is "abnormal." |
| `term` | `xterm-ghostty` | `TERM` value. |
| `enquiry-response` | `""` | Reply to ENQ (0x05). |
| `notify-on-command-finish` | `never` | `never`/`unfocused`/`always`. |
| `notify-on-command-finish-action` | `bell` | `bell`/`notify`. |
| `notify-on-command-finish-after` | `5s` | Min runtime before notifying. |

### 11.8 Shell integration

| Option | Default | Description |
|--------|---------|-------------|
| `shell-integration` | `detect` | `none`/`detect`/`bash`/`elvish`/`fish`/`nushell`/`zsh`. |
| `shell-integration-features` | cursor,title,… | `cursor`, `sudo`, `title`, `ssh-env`, `ssh-terminfo`, `path` (prefix `no-`). |

See [Section 14](#14-shell-integration) for details.

### 11.9 Keyboard

| Option | Default | Description |
|--------|---------|-------------|
| `keybind` | (many defaults) | `trigger=action`. See [Section 13](#13-keybindings). |
| `key-remap` | — | Remap modifiers (`ctrl=super`). Repeatable. |
| `macos-option-as-alt` | unset | **[mac]** Treat Option as Alt. `true`/`false`/`left`/`right`. |
| `vt-kam-allowed` | `false` | Allow ANSI mode 2 (KAM). |

### 11.10 Quick terminal

| Option | Default | Description |
|--------|---------|-------------|
| `quick-terminal-position` | `top` | `top`/`bottom`/`left`/`right`/`center`. |
| `quick-terminal-size` | auto | `%`/`px`, optionally `primary,secondary`. |
| `quick-terminal-screen` | `main` | `main`/`mouse`/`macos-menu-bar`. |
| `quick-terminal-animation-duration` | `0.2` | **[mac]** seconds. |
| `quick-terminal-autohide` | `true` (mac) / `false` (Linux) | Hide on focus loss. |
| `quick-terminal-space-behavior` | `move` | **[mac]** `move`/`remain`. |
| `quick-terminal-keyboard-interactivity` | `on-demand` | **[wl]** `none`/`on-demand`/`exclusive`. |
| `gtk-quick-terminal-layer` | `top` | **[wl]** `overlay`/`top`/`bottom`/`background`. |
| `gtk-quick-terminal-namespace` | `ghostty-quick-terminal` | **[wl]** Layer-shell namespace. |

### 11.11 Bell and notifications

| Option | Default | Description |
|--------|---------|-------------|
| `bell-features` | `attention,title` | `system`, `audio`, `attention`, `title`, `border`. |
| `bell-audio-path` | — | Audio file for `audio` bell. |
| `bell-audio-volume` | `0.5` | 0.0–1.0. |
| `app-notifications` | all on | **[gtk]** `clipboard-copy`, `config-reload`. |
| `desktop-notifications` | `true` | Allow OSC 9/777 notifications. |
| `progress-style` | `true` | Allow OSC 9;4 progress bars. |
| `title-report` | `false` | Allow CSI 21 t title query (security risk). |

### 11.12 Window decoration and titlebar (macOS)

| Option | Default | Description |
|--------|---------|-------------|
| `macos-titlebar-style` | `transparent` | `native`/`transparent`/`tabs`/`hidden`. |
| `macos-titlebar-proxy-icon` | `visible` | Folder proxy icon. |
| `macos-window-buttons` | `visible` | Traffic-light buttons. |
| `macos-non-native-fullscreen` | `false` | `true`/`visible-menu`/`padded-notch`. |
| `macos-window-shadow` | `true` | Window shadow. |
| `macos-hidden` | `never` | Hide from dock/switcher. |
| `macos-dock-drop-behavior` | `new-tab` | `new-tab`/`new-window`. |

### 11.13 GTK / Linux

| Option | Default | Description |
|--------|---------|-------------|
| `gtk-single-instance` | `detect` | Single-instance mode. |
| `gtk-titlebar` | `true` | Show GTK titlebar. |
| `gtk-titlebar-style` | `native` | `native`/`tabs`. |
| `gtk-titlebar-hide-when-maximized` | `false` | Hide titlebar when maximized. |
| `gtk-toolbar-style` | `raised` | `flat`/`raised`/`raised-border`. |
| `gtk-custom-css` | — | Custom CSS files. Repeatable. |
| `gtk-opengl-debug` | debug builds | OpenGL debug logs. |
| `linux-cgroup` | `single-instance` | Per-surface systemd scope. |
| `linux-cgroup-memory-limit` / `-processes-limit` | — | Per-surface limits. |
| `linux-cgroup-hard-fail` | `false` | Fail surface creation if cgroup setup fails. |
| `async-backend` | `auto` | `auto`/`epoll`/`io_uring`. Restart required. |

### 11.14 macOS-specific behavior

| Option | Default | Description |
|--------|---------|-------------|
| `macos-auto-secure-input` | `true` | Auto-enable Secure Input at password prompts. |
| `macos-secure-input-indication` | `true` | Show indicator when Secure Input is on. |
| `macos-applescript` | `true` | Enable the AppleScript dictionary. |
| `macos-shortcuts` | `ask` | Allow macOS Shortcuts control: `ask`/`allow`/`deny`. |
| `macos-icon` | `official` | Dock icon: official, variants, `custom`, `custom-style`. |
| `macos-custom-icon` | `~/.config/ghostty/Ghostty.icns` | Custom icon path. |
| `macos-icon-frame` | `aluminum` | `aluminum`/`beige`/`plastic`/`chrome`. |
| `macos-icon-ghost-color` / `macos-icon-screen-color` | — | Custom-style icon colors. |

### 11.15 Auto-update (macOS)

| Option | Default | Description |
|--------|---------|-------------|
| `auto-update` | unset | `off`/`check`/`download`. |
| `auto-update-channel` | matches build | `stable`/`tip`. Restart required. |

### 11.16 Advanced

| Option | Default | Description |
|--------|---------|-------------|
| `custom-shader` | — | GLSL shader file(s), Shadertoy-compatible. Repeatable. |
| `custom-shader-animation` | `true` | Animate shaders; `true`/`false`/`always`. |
| `link` / `link-url` / `link-previews` | URL on | Clickable link matching. |
| `image-storage-limit` | `320000000` (320 MB) | Kitty image memory per screen. |
| `osc-color-report-format` | `16-bit` | OSC 4/10/11 reply: `none`/`8-bit`/`16-bit`. |
| `command-palette-entry` | defaults | Custom command-palette entries. Repeatable. |
| `config-file` | — | Include other config files. Repeatable. |
| `config-default-files` | `true` | Load default config paths (CLI-only). |
| `confirm-close-surface` | `true` | `true`/`false`/`always`. |
| `quit-after-last-window-closed` | `true` (Linux) | Quit on last window. |
| `quit-after-last-window-closed-delay` | unset | **[gtk]** Delay before quitting. |
| `initial-window` | `true` | Open a window on launch. |
| `undo-timeout` | `5s` | **[mac]** How long undo is available. |
| `language` | system | **[gtk]** Force GUI language (restart required). |

---

## 12. Command-Line Actions Reference

All actions are invoked as `ghostty +<action>`.

| Action | Description |
|--------|-------------|
| `+version` (or `--version`) | Print version and exit. |
| `+help` (or `--help`/`-h`) | Print CLI/config help. |
| `+list-fonts` | List available font families. |
| `+list-keybinds` | List active keybindings. |
| `+list-themes` | Browse/preview built-in themes. |
| `+list-colors` | List named X11 colors. |
| `+list-actions` | List all keybind actions. |
| `+show-config` | Dump the effective config (`--default`, `--docs` flags). |
| `+edit-config` | Open the config file in your editor. |
| `+explain-config <key>` | Explain a single config option. |
| `+validate-config` | Validate a config file (`--config-file=`). |
| `+show-face` | Show which font face renders a codepoint/string. |
| `+ssh` | Wrap `ssh` to set up Ghostty terminfo on remote hosts. |
| `+ssh-cache` | Manage the SSH terminfo install cache. |
| `+new-window` | IPC: tell the running Ghostty to open a new window. |
| `+toggle-quick-terminal` | IPC: toggle the quick terminal. |
| `+crash-report` | List crash reports. |
| `+boo` | An easter egg. 👻 |

```bash
# Examples
ghostty +list-themes
ghostty +show-config --default --docs | less
ghostty +validate-config --config-file=~/.config/ghostty/config
ghostty +explain-config background-opacity
```

> [!TIP]
> `+new-window` and `+toggle-quick-terminal` use inter-process communication to
> control an **already-running** Ghostty instance — useful for binding to global
> system shortcuts or scripts.

---

## 13. Keybindings

### 13.1 Syntax

```ini
keybind = <trigger>=<action>
```

A **trigger** is a `+`-separated list of modifiers and one key:

```ini
keybind = ctrl+shift+t=new_tab
keybind = cmd+c=copy_to_clipboard
keybind = up=scroll_page_up
```

- **Modifiers:** `shift`, `ctrl` (alias `control`), `alt` (aliases `opt`,
  `option`), `super` (aliases `cmd`, `command`).
- **Keys:** a Unicode character (`a`, layout-dependent), a physical key code
  (`KeyA`/`key_a`, layout-independent), or a named key (`up`, `f5`, `enter`,
  `insert`). Physical keys win over Unicode keys when both are bound.
- **`catch_all`** matches any otherwise-unbound key.

### 13.2 Key sequences (leader keys)

Chain triggers with `>` to require a sequence:

```ini
keybind = ctrl+a>n=new_window
keybind = ctrl+a>t=new_tab
```

Ghostty waits indefinitely for the next key in a sequence (no timeout). Quote
sequences on the command line because `>` is a shell metacharacter:
`ghostty --keybind='ctrl+a>n=new_window'`.

### 13.3 Trigger prefixes

Prefix a trigger to change behavior:

| Prefix | Effect |
|--------|--------|
| `all:` | Apply to all surfaces, not just the focused one. |
| `global:` | Work system-wide even when Ghostty is unfocused (implies `all:`). |
| `unconsumed:` | Also send the encoded key to the program. |
| `performable:` | Only consume the key if the action can actually be performed. |

```ini
keybind = global:cmd+grave_accent=toggle_quick_terminal
keybind = performable:cmd+c=copy_to_clipboard
keybind = unconsumed:ctrl+a=reload_config
```

> [!IMPORTANT]
> `global:` is only supported on macOS and certain Linux desktops. On macOS it
> requires **Accessibility** permission. On Linux it requires a compositor that
> implements the XDG **GlobalShortcuts** portal (KDE Plasma 5.27+, GNOME 48+,
> Hyprland with setup; not wlroots/Sway).

### 13.4 Chained actions and key tables

Run several actions from one keybind with `chain` (Ghostty 1.3+):

```ini
keybind = ctrl+a=new_window
keybind = chain=goto_split:left
keybind = chain=toggle_fullscreen
```

Define modal **key tables** (e.g. a "copy mode") with `table/binding` syntax and
activate them with `activate_key_table` (Ghostty 1.3+):

```ini
keybind = ctrl+a=activate_key_table:nav
keybind = nav/h=goto_split:left
keybind = nav/l=goto_split:right
keybind = nav/escape=deactivate_key_table
```

### 13.5 Special keybind values

```ini
keybind = clear                 # remove ALL keybinds (including defaults)
keybind = ctrl+x=unbind         # remove a single binding
keybind = ctrl+g=ignore         # black-hole a key
keybind = f1=csi:0m             # send a CSI sequence
keybind = f2=esc:d              # send an ESC sequence
keybind = f3=text:\x15          # send literal text (Zig string literal syntax)
```

### 13.6 Modifier remapping

```ini
key-remap = ctrl=super
key-remap = left_control=right_alt
```

Remaps are one-way and not transitive. Use sided names (`left_ctrl`) to remap a
single physical key.

### 13.7 Action reference

The full, build-accurate list is available via `ghostty +list-actions`. The
following actions can be bound to triggers (and used in `command-palette-entry`):

**Input / text**

| Action | Description |
|--------|-------------|
| `ignore` | Do nothing (don't forward to the program). |
| `unbind` | Remove a previously bound key. |
| `csi:<text>` | Send a CSI sequence (no `ESC [` header). |
| `esc:<text>` | Send an ESC sequence. |
| `text:<text>` | Send literal text (Zig escape syntax). |
| `cursor_key` | Send normal/application cursor-key data. |
| `reset` | Reset the terminal (like `reset`). |

**Clipboard**

| Action | Description |
|--------|-------------|
| `copy_to_clipboard[:plain\|vt\|html\|mixed]` | Copy selection (default `mixed`). |
| `paste_from_clipboard` | Paste the system clipboard. |
| `paste_from_selection` | Paste the selection clipboard. |
| `copy_url_to_clipboard` | Copy the URL under the cursor. |
| `copy_title_to_clipboard` | Copy the terminal title. |

**Font size**

| Action | Description |
|--------|-------------|
| `increase_font_size:<pt>` / `decrease_font_size:<pt>` | Change size by points. |
| `reset_font_size` | Reset to configured size. |
| `set_font_size:<pt>` | Set absolute size. |

**Search**

| Action | Description |
|--------|-------------|
| `search:<text>` | Start a search (empty cancels). |
| `search_selection` | Search the current selection. |
| `start_search` / `end_search` | Open/close the search UI. |
| `navigate_search:previous\|next` | Move between matches. |

**Scrolling**

| Action | Description |
|--------|-------------|
| `scroll_to_top` / `scroll_to_bottom` | Jump to ends. |
| `scroll_to_selection` | Scroll to the selection. |
| `scroll_to_row:<n>` | Scroll to an absolute row. |
| `scroll_page_up` / `scroll_page_down` | Page scroll. |
| `scroll_page_fractional:<f>` | Scroll by a fraction of a page. |
| `scroll_page_lines:<n>` | Scroll by N lines. |
| `jump_to_prompt:<n>` | Jump N prompts (needs shell integration). |

**Selection**

| Action | Description |
|--------|-------------|
| `select_all` | Select the whole screen. |
| `adjust_selection:<dir>` | Extend selection (`left`/`right`/`up`/`down`/`page_up`/`page_down`/`home`/`end`/`beginning_of_line`/`end_of_line`). |
| `clear_screen` | Clear screen and scrollback. |

**Dump screen to file**

| Action | Description |
|--------|-------------|
| `write_scrollback_file:copy\|paste\|open` | Write scrollback to a temp file. |
| `write_screen_file:…` | Write the visible screen. |
| `write_selection_file:…` | Write the selection. |

**Tabs**

`new_tab`, `previous_tab`, `next_tab`, `last_tab`, `goto_tab:<n>`,
`move_tab:<n>`, `toggle_tab_overview`, `prompt_tab_title`, `set_tab_title:<s>`.

**Splits**

`new_split:<dir>`, `goto_split:<dir>`, `toggle_split_zoom`, `resize_split:<dir>,<n>`,
`equalize_splits`, `toggle_readonly`.

**Windows**

`new_window`, `close_surface`, `close_tab:this|other|right`, `close_window`,
`toggle_maximize`, `toggle_fullscreen`, `toggle_window_decorations` (Linux),
`toggle_window_float_on_top` (macOS), `reset_window_size` (macOS),
`goto_window:previous|next`, `prompt_surface_title`, `set_surface_title:<s>`.

**Application & UI**

| Action | Description |
|--------|-------------|
| `open_config` / `reload_config` | Edit / reload config. |
| `toggle_command_palette` | Command palette (**Linux: libadwaita 1.5+**). |
| `toggle_quick_terminal` | Drop-down terminal. |
| `inspector:toggle\|show\|hide` | Terminal inspector. |
| `show_gtk_inspector` | GTK inspector (**Linux**). |
| `show_on_screen_keyboard` | On-screen keyboard (**Linux/GTK**). |
| `toggle_secure_input` | Secure input (**macOS**). |
| `toggle_mouse_reporting` | Toggle mouse capture. |
| `toggle_visibility` | Show/hide all windows (**macOS**). |
| `toggle_background_opacity` | Toggle transparency (**macOS**). |
| `check_for_updates` | Check for updates (**macOS**). |
| `undo` / `redo` | Undo/redo surface actions (**macOS**). |
| `quit` | Quit Ghostty. |

**Key tables**

`activate_key_table:<name>`, `activate_key_table_once:<name>`,
`deactivate_key_table`, `deactivate_all_key_tables`, `end_key_sequence`.

> [!NOTE]
> Many actions are platform-specific and report as "not performable" where
> unsupported. Use `performable:` triggers to let unsupported keys fall through
> to the program.

---

## 14. Shell Integration

Shell integration unlocks several quality-of-life features:

- New tabs/splits inherit the **working directory** of the previous terminal.
- **Prompt marking** (OSC 133) enables `jump_to_prompt` and click-to-move.
- Closing a terminal sitting at a prompt skips the confirmation dialog.
- Better repainting when resizing with complex prompts.

### 14.1 Enabling

Automatic injection is on by default:

```ini
shell-integration = detect       # none | detect | bash | elvish | fish | nushell | zsh
```

`detect` chooses the integration based on your shell binary name. Set a specific
shell to force it, or `none` to disable auto-injection (you can still source the
scripts manually).

### 14.2 Features

Toggle individual features:

```ini
shell-integration-features = cursor,no-sudo,title,ssh-env,ssh-terminfo
```

| Feature | Default | Effect |
|---------|---------|--------|
| `cursor` | on | Bar cursor at the prompt. |
| `sudo` | off | Preserve terminfo through `sudo`. |
| `title` | on | Set the window title from the shell. |
| `ssh-env` | off | Convert `TERM` to `xterm-256color` and propagate `COLORTERM`/`TERM_PROGRAM*` over SSH. |
| `ssh-terminfo` | off | Install Ghostty's terminfo on remote hosts (needs `infocmp` locally, `tic` remotely). |
| `path` | on | Add Ghostty's bin directory to `PATH`. |

> [!TIP]
> For the smoothest SSH experience, enable both `ssh-env` and `ssh-terminfo`.
> Ghostty installs its terminfo remotely and uses `xterm-ghostty`, falling back
> to `xterm-256color` if installation fails. Manage the install cache with
> `ghostty +ssh-cache`.

### 14.3 Remote hosts and terminfo

If a remote host doesn't recognize `xterm-ghostty`, programs may misbehave. The
options above handle this automatically; alternatively, install the terminfo
manually or set `term = xterm-256color`.

---

## 15. Notable Features

### 15.1 The quick terminal

A drop-down ("Quake-style") terminal that slides in from a screen edge on demand.
There is **no default keybind** — bind one (ideally global):

```ini
keybind = global:cmd+grave_accent=toggle_quick_terminal
quick-terminal-position = top
quick-terminal-size = 40%
quick-terminal-autohide = true
```

Limitations: only one instance exists at a time; it is not restored on restart;
on Linux it requires Wayland with `wlr-layer-shell-v1` (so not GNOME), and
slide-in animation requires KDE's "Sliding Popups" KWin plugin. Quick-terminal
tabs are Linux-only.

### 15.2 The command palette

A searchable popup listing actions and their shortcuts:

```ini
keybind = cmd+shift+p=toggle_command_palette
```

Add custom entries:

```ini
command-palette-entry = title:Reset Font Style, action:csi:0m
command-palette-entry = title:Focus Right Split, action:goto_split:right
```

On Linux this requires libadwaita 1.5+.

### 15.3 Search

```ini
keybind = cmd+f=start_search
keybind = cmd+g=navigate_search:next
keybind = cmd+shift+g=navigate_search:previous
```

Search match colors are configurable (`search-foreground`, `search-background`,
`search-selected-foreground`, `search-selected-background`).

### 15.4 Clickable links

URLs are matched on hover with **Ctrl** (Linux) or **Cmd** (macOS) and open in
your default application. OSC 8 hyperlinks are supported. Configure link previews
with `link-previews` (`true`/`false`/`osc8`). Disable automatic URL matching
with `link-url = false`.

### 15.5 Custom shaders

Apply GPU post-processing shaders (Shadertoy-compatible GLSL):

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

Shaders receive uniforms like `iResolution`, `iTime`, `iChannel0` (the terminal
screen), plus Ghostty extensions (`iCurrentCursor`, `iPalette`,
`iBackgroundColor`, etc.).

> [!CAUTION]
> An invalid or aggressive shader can render the window completely black. If that
> happens, remove the `custom-shader` line and reload. Shader compile errors only
> appear in the logs, not as config errors.

### 15.6 Kitty graphics and images

Ghostty implements the Kitty graphics protocol for inline images. Memory is
capped per screen by `image-storage-limit` (default 320 MB; set to `0` to disable
all image protocols).

### 15.7 The terminal inspector

A built-in debugging overlay showing keyboard events, terminal modes, screen
contents, and more:

```ini
keybind = cmd+alt+i=inspector:toggle
```

---

## 16. Troubleshooting

### Error: programs look broken / wrong colors over SSH

**Cause:** the remote host doesn't have the `xterm-ghostty` terminfo entry.
**Solution:** enable `shell-integration-features = ssh-terminfo` (and `ssh-env`),
or set `term = xterm-256color`, or install the terminfo on the remote host.
**Prevention:** keep `ssh-env`/`ssh-terminfo` enabled.

### Error: the window is completely black after adding a shader

**Cause:** an invalid `custom-shader`. **Solution:** remove the `custom-shader`
line and reload (`Cmd/Ctrl+Shift+,`). Check logs for the compile error.
**Prevention:** develop shaders on [shadertoy.com](https://shadertoy.com) first.

### Error: `global:` keybind does nothing

**Cause:** missing permission/portal support. **Solution (macOS):** grant
Accessibility permission in System Settings → Privacy & Security → Accessibility.
**Solution (Linux):** use a compositor with the GlobalShortcuts portal (KDE
5.27+, GNOME 48+); wlroots/Sway is unsupported.

### Error: Option key types special characters instead of acting as Alt (macOS)

**Cause:** macOS Option produces Unicode by default. **Solution:** set
`macos-option-as-alt = true` (or `left`/`right`). **Prevention:** keep this set
if you rely on Alt-based shortcuts in shells/editors.

### Error: tabs disappear in fullscreen (macOS)

**Cause:** non-native fullscreen removes the titlebar that native tabs require.
**Solution:** use native fullscreen (`fullscreen = true`,
`macos-non-native-fullscreen = false`).

### Error: ligatures appear where I don't want them

**Cause:** the font's `calt` feature. **Solution:** `font-feature = -calt` (and
`-liga, -dlig` for more). Ghostty also breaks shaping under the cursor by default.

### Error: background blur / transparency not working on Linux

**Cause:** limited compositor support. **Solution:** blur is only supported on
some desktops (notably KDE Plasma, where it uses KWin's global blur). Enable the
KWin "Blur" desktop effect. **Prevention:** verify your desktop supports it.

### Error: terminal uses too much memory

**Cause:** large `scrollback-limit`, large background images, or many images.
**Solution:** lower `scrollback-limit`, reduce `image-storage-limit`, avoid huge
background images (they live in VRAM per terminal).

### Error: config change didn't take effect

**Cause:** many options only apply to **new** terminals, and a few require a full
restart. **Solution:** open a new window/tab, or fully restart Ghostty. Check the
option's notes in [Section 11](#11-configuration-reference).

### Error: `+validate-config` reports errors

**Cause:** a malformed option or value. **Solution:** run `ghostty
+validate-config` to see the exact line and message; use `ghostty +explain-config
<key>` to confirm valid values.

### Error: closing a window unexpectedly prompts for confirmation

**Cause:** `confirm-close-surface` and an active process. **Solution:** set
`confirm-close-surface = false`, or enable shell integration so Ghostty knows
you're at a prompt.

### Error: Ghostty quits when I close the last window (or doesn't)

**Cause:** `quit-after-last-window-closed` differs by platform (default `true` on
Linux, `false` on macOS). **Solution:** set it explicitly to the behavior you
want; on Linux you can add `quit-after-last-window-closed-delay`.

### Error: unsafe-paste confirmation keeps appearing

**Cause:** `clipboard-paste-protection` flags multiline/control-char pastes.
**Solution:** keep it on for safety; it normally only triggers for risky content.
You can disable with `clipboard-paste-protection = false` (not recommended).

### Error: app icon won't change (macOS Finder)

**Cause:** the Finder icon is baked into the signed app bundle. **Solution:**
`macos-icon` only affects the dock/switcher icon, not Finder.

### Error: tab overview / command palette missing (Linux)

**Cause:** libadwaita too old. **Solution:** tab overview needs libadwaita 1.4+,
command palette needs 1.5+. Check with `ghostty +version`.

---

## 17. FAQ

**Q: Where is my configuration file?**
`~/.config/ghostty/config` (or `$XDG_CONFIG_HOME/ghostty/config`). It does not
exist by default — create it. `ghostty +edit-config` opens it.

**Q: How do I see every available option?**
`ghostty +show-config --default --docs`. For one option,
`ghostty +explain-config <key>`.

**Q: How do I list/preview themes?**
`ghostty +list-themes`. Set with `theme = <name>`.

**Q: How do I disable ligatures?**
`font-feature = -calt` (add `-liga, -dlig` to remove more).

**Q: How do I make the background transparent?**
`background-opacity = 0.9` (and optionally `background-blur = true`).

**Q: Can I have different light/dark themes?**
Yes: `theme = light:rose-pine-dawn,dark:rose-pine`.

**Q: How do I add a drop-down (Quake) terminal?**
Bind `toggle_quick_terminal`, ideally globally:
`keybind = global:cmd+grave_accent=toggle_quick_terminal`.

**Q: What is `TERM` set to, and why does it matter?**
`xterm-ghostty`. Remote hosts may not have this terminfo; use the SSH shell
integration features or fall back to `xterm-256color`.

**Q: Why does Option+letter type symbols on macOS instead of acting as Alt?**
That's macOS default behavior. Set `macos-option-as-alt = true`.

**Q: How do I run a single command instead of my shell?**
`ghostty -e <command>`.

**Q: How do I split the window?**
Bind `new_split:right`/`down` (and navigate with `goto_split:...`). Defaults vary;
see `ghostty +list-keybinds`.

**Q: Why aren't my keybinds working / how do I see the defaults?**
`ghostty +list-keybinds` shows all active bindings. Remember `keybind = clear`
removes defaults too.

**Q: Does Ghostty support inline images?**
Yes, via the Kitty graphics protocol (capped by `image-storage-limit`).

**Q: How do I update Ghostty?**
macOS has a built-in updater (`auto-update`, `check_for_updates`). Linux updates
through your package manager / Flatpak / Snap.

**Q: How do I reset a repeatable option like `font-family`?**
Set it to an empty value first (`font-family =`) then add new entries.

**Q: Can a theme change non-color settings?**
Yes — a theme file can set almost any option (but not `theme`/`config-file`).
Only use themes you trust.

**Q: How do I make a keybind work even when Ghostty isn't focused?**
Prefix it with `global:` (macOS Accessibility permission / Linux GlobalShortcuts
portal required).

**Q: How do I rename a tab or window?**
Bind `prompt_tab_title` / `prompt_surface_title`, or use `set_tab_title:<text>`.

**Q: How do I customize the dock icon on macOS?**
Use `macos-icon` (official variants), or `macos-icon = custom` with
`macos-custom-icon = /path/to/icon`.

---

## 18. Quick Reference

**Config file:** `~/.config/ghostty/config`

**Reload:** `Cmd+Shift+,` (macOS) / `Ctrl+Shift+,` (Linux)

**Essential CLI:**

```bash
ghostty +list-themes        # themes
ghostty +list-fonts         # fonts
ghostty +list-keybinds      # keybinds
ghostty +list-actions       # bindable actions
ghostty +show-config --default --docs   # all options + docs
ghostty +edit-config        # open config
ghostty +validate-config    # validate
ghostty -e <command>        # run a command
```

**Starter config:**

```ini
theme = light:rose-pine-dawn,dark:rose-pine
font-family = JetBrains Mono
font-size = 13
background-opacity = 0.95
cursor-style = bar
copy-on-select = clipboard
keybind = ctrl+shift+enter=new_split:right
keybind = ctrl+shift+t=new_tab
keybind = global:cmd+grave_accent=toggle_quick_terminal
shell-integration-features = cursor,title,ssh-env,ssh-terminfo
```

---

_Generated June 2026 from ghostty-org/ghostty at bfe633a. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._