Ghostty

https://ghostty.org/docs
Admin
Ghostty is a fast, feature-rich, and cross-platform terminal emulator that uses platform-native UI...
Tokens:94,891
Snippets:771
Trust Score:9.6
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Install dependencies on Solus with eopkg

Source: https://ghostty.org/docs/install/build

Installs required development headers and tooling on Solus.

```shell
sudo eopkg install \
  libgtk-4-devel \
  libadwaita-devel \
  pkgconf \
  zig \
  gettext

```

--------------------------------

### Build and install Ghostty system-wide to /usr

Source: https://ghostty.org/docs/install/build

Installs Ghostty system-wide to the /usr prefix.

```shell
zig build -p /usr -Doptimize=ReleaseFast

```

--------------------------------

### Install Ghostty on Solus via eopkg

Source: https://ghostty.org/docs/install/binary

Installs Ghostty from the official Solus package repository.

```shell
eopkg install ghostty

```

--------------------------------

### Install dependencies on Void Linux with xbps-install

Source: https://ghostty.org/docs/install/build

Installs required dependencies on Void Linux.

```shell
sudo xbps-install \
  gtk4-devel \
  gtk4-layer-shell-devel \
  libadwaita-devel \
  pkg-config \
  zig \
  gettext

```

--------------------------------

### Install Ghostty on Gentoo with emerge

Source: https://ghostty.org/docs/install/binary

Installs Ghostty from the official Gentoo repository.

```shell
emerge -av ghostty

```

--------------------------------

### Install Ghostty on Ubuntu via apt

Source: https://ghostty.org/docs/install/binary

Installs Ghostty using the official Ubuntu package repository available starting from Ubuntu 26.04.

```shell
apt install ghostty

```

--------------------------------

### Install Ghostty on openSUSE with zypper

Source: https://ghostty.org/docs/install/binary

Installs Ghostty from openSUSE's official repo-oss repository.

```shell
sudo zypper in ghostty

```

--------------------------------

### Install Ghostty via Snap

Source: https://ghostty.org/docs/install/binary

Installs the Ghostty snap package from the Snap Store using classic confinement.

```shell
snap install ghostty --classic

```

--------------------------------

### Install dependencies on Gentoo with emerge

Source: https://ghostty.org/docs/install/build

Installs required packages to prepare the build environment on Gentoo.

```shell
emerge -av \
  libadwaita \
  gtk \
  blueprint-compiler \
  gettext

```

--------------------------------

### Install Ghostty on Debian and Ubuntu via Community Script

Source: https://ghostty.org/docs/install/binary

Downloads and executes the ghostty-ubuntu community installer script to set up prebuilt .deb packages.

```shell
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/mkasberg/ghostty-ubuntu/HEAD/install.sh)"

```

--------------------------------

### Install Ghostty on Void Linux via xbps-install

Source: https://ghostty.org/docs/install/binary

Installs Ghostty from the official Void Linux package repository.

```shell
xbps-install ghostty

```

--------------------------------

### Build and install Ghostty locally to $HOME/.local

Source: https://ghostty.org/docs/install/build

Performs an unprivileged build and sets up proper FHS directory structure under $HOME/.local.

```shell
zig build -p $HOME/.local -Doptimize=ReleaseFast

```

--------------------------------

### Install dependencies on Alpine Linux with apk

Source: https://ghostty.org/docs/install/build

Installs header packages required to build Ghostty on Alpine Linux.

```shell
doas apk add \
  gtk4.0-dev \
  libadwaita-dev \
  pkgconf \
  ncurses \
  gettext

```

--------------------------------

### Install dependencies on Arch Linux with pacman

Source: https://ghostty.org/docs/install/build

Installs required header packages and tools on Arch Linux.

```shell
sudo pacman -S \
  gtk4 \
  gtk4-layer-shell \
  pkgconf \
  libadwaita \
  gettext

```

--------------------------------

### Install dependencies on Fedora with dnf

Source: https://ghostty.org/docs/install/build

Installs required libraries and Zig build tool on standard Fedora variants.

```shell
sudo dnf install \
  gtk4-devel \
  gtk4-layer-shell-devel \
  zig \
  libadwaita-devel \
  gettext

```

--------------------------------

### Install dependencies on openSUSE Tumbleweed with zypper

Source: https://ghostty.org/docs/install/build

Installs build dependencies including gtk4-layer-shell-devel on openSUSE Tumbleweed.

```shell
sudo zypper install \
  gtk4-devel \
  libadwaita-devel \
  pkgconf \
  ncurses-devel \
  zig \
  gettext \
  gtk4-layer-shell-devel

```

--------------------------------

### Install Ghostty on Fedora via COPR

Source: https://ghostty.org/docs/install/binary

Enables the scottames/ghostty COPR repository and installs Ghostty with DNF.

```shell
dnf copr enable scottames/ghostty
dnf install ghostty

```

--------------------------------

### Run Ghostty Tip Version with Nix Flake

Source: https://ghostty.org/docs/install/pre

Build and execute the development version of Ghostty directly from the GitHub repository without permanently installing it.

```bash
# Build and run the latest tip version of Ghostty without installing
nix run github:ghostty-org/ghostty

```

--------------------------------

### File paths for user installations

Source: https://ghostty.org/docs/linux/systemd

Lists desktop entry, D-Bus service, and systemd unit file paths created when Ghostty is installed as a user.

```plaintext
$PREFIX/share/applications/com.mitchellh.ghostty.desktop
$PREFIX/share/dbus-1/services/com.mitchellh.ghostty.service
$PREFIX/share/systemd/user/app-com.mitchellh.ghostty.service

```

--------------------------------

### Install Ghostty Prerelease via Homebrew Cask

Source: https://ghostty.org/docs/install/pre

Install the community-maintained prerelease build of Ghostty on macOS using Homebrew.

```bash
brew install --cask ghostty@tip

```

--------------------------------

### Install dependencies on openSUSE Leap with zypper

Source: https://ghostty.org/docs/install/build

Installs build dependencies on openSUSE Leap. Note that gtk4-layer-shell must be compiled from source using -fno-sys=gtk4-layer-shell.

```shell
sudo zypper install \
  gtk4-devel \
  libadwaita-devel \
  pkgconf \
  ncurses-devel \
  zig \
  gettext

```

--------------------------------

### Install dependencies on Fedora Atomic with rpm-ostree

Source: https://ghostty.org/docs/install/build

Installs build packages on Fedora Atomic variants via rpm-ostree.

```shell
rpm-ostree install \
  gtk4-devel \
  gtk4-layer-shell-devel \
  zig \
  libadwaita-devel \
  gettext

```

--------------------------------

### File paths for debug build user installations

Source: https://ghostty.org/docs/linux/systemd

Lists configuration and service file paths required to launch debug versions of Ghostty when installed per-user.

```plaintext
$PREFIX/share/applications/com.mitchellh.ghostty-debug.desktop
$PREFIX/share/dbus-1/services/com.mitchellh.ghostty-debug.service
$PREFIX/share/systemd/user/app-com.mitchellh.ghostty-debug.service

```

--------------------------------

### Install dependencies on Debian and Ubuntu with apt

Source: https://ghostty.org/docs/install/build

Installs necessary build dependencies on Debian and Ubuntu systems. Debian unstable/testing also requires the gcc-multilib package.

```shell
sudo apt install \
  libgtk-4-dev \
  libgtk4-layer-shell-dev \
  libadwaita-1-dev \
  gettext \
  libxml2-utils

```

--------------------------------

### Install Ghostty on Fedora via Terra

Source: https://ghostty.org/docs/install/binary

Configures the Terra repository release package and installs Ghostty with DNF.

```shell
dnf install --nogpgcheck --repofrompath 'terra,https://repos.fyralabs.com/terra$releasever' terra-release
dnf install ghostty

```

--------------------------------

### Install ghostty-bin via nix-darwin

Source: https://ghostty.org/docs/install/binary

Installs the Ghostty macOS binary package (ghostty-bin) systemwide or for a single user in nix-darwin configuration.

```nix
{
  pkgs,
}:
{
  # Systemwide install
  environment.systemPackages = [
    pkgs.ghostty-bin
  ];
  
  # Install for a specific user
  users.users.somebody.packages = [
    pkgs.ghostty-bin
  ];
}

```

--------------------------------

### Install Ghostty on Alpine Linux with apk

Source: https://ghostty.org/docs/install/binary

Installs Ghostty from Alpine Linux's official testing repository.

```shell
apk add ghostty

```

--------------------------------

### Install Ghostty on Arch Linux with pacman

Source: https://ghostty.org/docs/install/binary

Installs the latest tagged release of Ghostty from the Arch Linux [extra] repository.

```shell
pacman -S ghostty

```

--------------------------------

### File paths for system package installations

Source: https://ghostty.org/docs/linux/systemd

Lists desktop entry, D-Bus service, and systemd unit file paths created when Ghostty is installed as a system package.

```plaintext
$PREFIX/share/applications/com.mitchellh.ghostty.desktop
$PREFIX/share/dbus-1/services/com.mitchellh.ghostty.service
$PREFIX/lib/systemd/user/app-com.mitchellh.ghostty.service

```

--------------------------------

### Install Ghostty via conda-forge with pixi

Source: https://ghostty.org/docs/install/binary

Installs the Ghostty package globally using pixi from conda-forge.

```shell
pixi global install ghostty

```

--------------------------------

### Enable Ghostty systemd user service at login

Source: https://ghostty.org/docs/linux/systemd

Enables Ghostty to start in the background on login without opening any windows, allowing subsequent window requests to launch instantly.

```bash
systemctl enable --user app-com.mitchellh.ghostty.service

```

--------------------------------

### Configure NixOS System Package or Overlay for Ghostty

Source: https://ghostty.org/docs/install/pre

Install Ghostty in NixOS by either directly referencing the flake package or adding the overlay to nixpkgs.

```nix
{
  pkgs,
  inputs,
}:
{
  # Installing the package directly
  users.users.somebody.packages = [
    inputs.ghostty.packages.${pkgs.stdenv.hostPlatform.system}.default
  ];

  # Alternatively, using overlays:
  nixpkgs.overlays = [
    inputs.ghostty.overlays.default
  ];
  users.users.somebody.packages = [
    pkgs.ghostty
  ];
}

```

--------------------------------

### File paths for debug build system package installations

Source: https://ghostty.org/docs/linux/systemd

Lists configuration and service file paths for launching debug builds of Ghostty installed as a system package.

```plaintext
$PREFIX/share/applications/com.mitchellh.ghostty-debug.desktop
$PREFIX/share/dbus-1/services/com.mitchellh.ghostty-debug.service
$PREFIX/lib/systemd/user/app-com.mitchellh.ghostty-debug.service

```

--------------------------------

### Create a new window with ghostty +new-window

Source: https://ghostty.org/docs/linux/systemd

Uses D-Bus directly to open a new window much faster than executing plain ghostty. If Ghostty is not currently running, D-Bus activation will automatically start it.

```bash
ghostty +new-window

```

--------------------------------

### Install Ghostty on Fedora Silverblue via rpm-ostree

Source: https://ghostty.org/docs/install/binary

Adds the COPR repository file to the system configuration and installs Ghostty on Fedora Atomic Desktops.

```shell
. /etc/os-release
curl -fsSL "https://copr.fedorainfracloud.org/coprs/scottames/ghostty/repo/fedora-${VERSION_ID}/scottames-ghostty-fedora-${VERSION_ID}.repo" | sudo tee /etc/yum.repos.d/_copr:copr.fedorainfracloud.org:scottames:ghostty.repo > /dev/null

```

```shell
rpm-ostree refresh-md && \
rpm-ostree install ghostty

```

--------------------------------

### Install Ghostty via Homebrew cask

Source: https://ghostty.org/docs/install/binary

Installs the community-maintained Ghostty Homebrew cask on macOS, which repackages the official binary.

```shell
brew install --cask ghostty

```

--------------------------------

### Install Ghostty Git Package on Arch Linux via AUR

Source: https://ghostty.org/docs/install/pre

Build and install the latest prerelease version of Ghostty on Arch Linux using an AUR helper such as yay.

```bash
# Install Ghostty git
yay -S ghostty-git

```

--------------------------------

### CBT V-2: Left Starting After Tab Stop

Source: https://ghostty.org/docs/vt/csi/cbt

Tests backward tabulation when starting after a tab stop. Moves cursor left to the preceding tabstop.

```sh
printf "\033[?5W" # reset tab stops
printf "\033[1;10H"
printf "X"
printf "\033[Z"
printf "A"

```

```text
|________AX|

```

--------------------------------

### Connect to a remote host using ghostty +ssh

Source: https://ghostty.org/docs/features/ssh

Invokes the +ssh wrapper to prepare the remote session and install terminfo files before delegating to the ssh binary.

```bash
ghostty +ssh -- user@example.com

```

--------------------------------

### CBT V-3: Left Starting on Tabstop

Source: https://ghostty.org/docs/vt/csi/cbt

Tests moving left with CBT when already positioned on a tabstop. Moves to the previous tabstop.

```sh
printf "\033[?5W" # reset tab stops
printf "\033[1;9H"
printf "X"
printf "\033[1;9H"
printf "\033[Z"
printf "A"

```

```text
|A_______X_|

```

--------------------------------

### Install macOS Build Dependencies via Homebrew

Source: https://ghostty.org/docs/install/build

Install required library dependencies such as gettext using Homebrew. These dependencies are automatically handled if using the Nix development environment.

```bash
brew install gettext

```

--------------------------------

### Run Ghostty without installing using nix run or nix-shell

Source: https://ghostty.org/docs/install/binary

Runs Ghostty directly from Nixpkgs without permanently adding it to the system packages.

```shell
nix run nixpkgs#ghostty
nix-shell -p ghostty --run ghostty

```

--------------------------------

### Configure Ghostty with key-value syntax

Source: https://ghostty.org/docs/config

Ghostty configuration syntax uses case-sensitive key = value pairs, line-only comments starting with #, and allows empty values to reset settings to default.

```ghostty
# The syntax is "key = value". The whitespace around the
# equals doesn't matter.
background = 282c34
foreground = ffffff

# Comments start with a `#` and are only valid on their own line.
# Blank lines are ignored!

keybind = ctrl+z=close_surface
keybind = ctrl+d=new_split:right

# Empty values reset the configuration to the default value
font-family =

```

--------------------------------

### CUB V-3: Reverse Wrap

Source: https://ghostty.org/docs/vt/csi/cub

Tests reverse wrap (?45h) when moving back past the start of a wrapped line.

```sh
cols=$(tput cols)
printf "\033[?7h" # enable wraparound
printf "\033[?45h" # enable reverse wrap
printf "\033[1;1H" # move to top-left
printf "\033[0J" # clear screen
printf "\033[${cols}G" # move to end of line
printf "AB" # write and wrap
printf "\033[D" # move back two
printf "X"

```

```text
|_________Xc
|B_________|

```

--------------------------------

### Enable SSH Shell Integration Features

Source: https://ghostty.org/docs/features/ssh

Add `ssh-env` and `ssh-terminfo` to `shell-integration-features` in Ghostty configuration to transparently wrap interactive `ssh` commands with environment forwarding and terminfo installation.

```ini
shell-integration-features = ssh-env,ssh-terminfo

```

--------------------------------

### Configure Xcode Developer Directory Path

Source: https://ghostty.org/docs/install/build

Check and switch the active developer directory to point to Xcode rather than CommandLineTools. This is required if CommandLineTools was installed after Xcode.

```bash
xcode-select --print-path
/Library/Developer/CommandLineTools        # <-- BAD

sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
xcode-select --print-path
/Applications/Xcode.app/Contents/Developer # <-- GOOD

```

--------------------------------

### Inspect Ghostty AppleScript dictionary using sdef

Source: https://ghostty.org/docs/features/applescript

Inspects the Ghostty scripting definition (.sdef) directly from an installed macOS application bundle.

```shell
sdef /Applications/Ghostty.app | less

```

--------------------------------

### Configure Ghostty in NixOS configuration

Source: https://ghostty.org/docs/install/binary

Declares Ghostty for either a systemwide installation or a single user package in a NixOS configuration module.

```nix
{
  pkgs,
}:
{
  # Systemwide install
  environment.systemPackages = [
    pkgs.ghostty
  ];
  
  # Install for a specific user
  users.users.somebody.packages = [
    pkgs.ghostty
  ];
}

```

--------------------------------

### Create a custom theme configuration file

Source: https://ghostty.org/docs/features/theme

Define custom palette colors, background, foreground, cursor, and selection styles in a theme file. Themes are loaded before user configuration.

```ini
palette = 0=#51576d
palette = 1=#e78284
palette = 2=#a6d189
palette = 3=#e5c890
palette = 4=#8caaee
palette = 5=#f4b8e4
palette = 6=#81c8be
palette = 7=#a5adce
palette = 8=#626880
palette = 9=#e67172
palette = 10=#8ec772
palette = 11=#d9ba73
palette = 12=#7b9ef0
palette = 13=#f2a4db
palette = 14=#5abfb5
palette = 15=#b5bfe2
background = #303446
foreground = #c6d0f5
cursor-color = #f2d5cf
cursor-text = #c6d0f5
selection-background = #626880
selection-foreground = #c6d0f5

```

--------------------------------

### Validate CUF when cursor starts right of margin (CUF V-4)

Source: https://ghostty.org/docs/vt/csi/cuf

Demonstrates that when cursor movement starts right of the active right margin, the boundary is expanded to the rightmost column of the screen.

```bash
printf "\033[1;1H" # move to top-left
printf "\033[0J" # clear screen
printf "\033[?69h" # enable left/right margins
printf "\033[3;5s" # scroll region left/right
printf "\033[6G" # move to right of margin
printf "\033[500C" # forward larger than screen width
printf "X"

```

```text
|_________X|

```

--------------------------------

### List available themes using the CLI

Source: https://ghostty.org/docs/features/theme

Run the +list-themes CLI command to view all available themes.

```bash
ghostty +list-themes

```

--------------------------------

### CBT V-1: Left Beyond First Column

Source: https://ghostty.org/docs/vt/csi/cbt

Tests moving the cursor back 10 tabstops when at the start of the line. The cursor remains at the leftmost column without moving past it.

```sh
printf "\033[?5W" # reset tab stops
printf "\033[10Z"
printf "A"

```

```text
|Ac________|

```

--------------------------------

### Configure and Create a Window with Surface Configuration Record

Source: https://ghostty.org/docs/features/applescript

Create a reusable surface configuration record with custom working directory, font size, and environment variables, then pass it to open a new window.

```applescript
tell application "Ghostty"
    set cfg to new surface configuration
    set initial working directory of cfg to POSIX path of (path to home folder) & "src/ghostty"
    set font size of cfg to 13
    set environment variables of cfg to {"EDITOR=nvim", "FZF_DEFAULT_OPTS=--height 40%"}

    set win to new window with configuration cfg
end tell

```

--------------------------------

### Validate Cursor Up Clamping to Top Margin (CUU V-2)

Source: https://ghostty.org/docs/vt/csi/cuu

Tests cursor movement when initiated inside a scrolling region. If the cursor starts at or below the top margin, it cannot move above the top margin boundary.

```bash
printf "\033[1;1H" # move to top-left
printf "\033[0J" # clear screen
printf "\n\n\n\n" # screen is 4 high
printf "\033[2;4r" # set scrolling region
printf "\033[3;1H"
printf "A"
printf "\033[5A" # cursor up
printf "X"

```

```text
|__________|
|_Xc_______|
|A_________|
|__________|

```

--------------------------------

### Validate CUF clamping left of right margin (CUF V-3)

Source: https://ghostty.org/docs/vt/csi/cuf

Demonstrates that forward movement starting to the left of an active right margin clamps to the margin boundary.

```bash
printf "\033[1;1H" # move to top-left
printf "\033[0J" # clear screen
printf "\033[?69h" # enable left/right margins
printf "\033[3;5s" # scroll region left/right
printf "\033[1G" # move to left
printf "\033[500C" # forward larger than screen width
printf "X"

```

```text
|____X_____|

```

--------------------------------

### CUD V-2: Cursor Down Above Bottom Margin

Source: https://ghostty.org/docs/vt/csi/cud

Tests moving the cursor down when starting at or above the bottom margin, clamping movement to the bottom margin without scrolling.

```sh
printf "\033[1;1H" # move to top-left
printf "\033[0J" # clear screen
printf "\n\n\n\n" # screen is 4 high
printf "\033[1;3r" # set scrolling region
printf "A"
printf "\033[5B" # cursor down
printf "X"

```

```text
|A_________|
|__________|
|_Xc_______|
|__________|

```

--------------------------------

### CUD V-3: Cursor Down Below Bottom Margin

Source: https://ghostty.org/docs/vt/csi/cud

Tests moving the cursor down when starting below the bottom margin, clamping cursor movement to the screen's final row.

```sh
printf "\033[1;1H" # move to top-left
printf "\033[0J" # clear screen
printf "\n\n\n\n\n" # screen is 5 high
printf "\033[1;3r" # set scrolling region
printf "A"
printf "\033[4;1H" # move below region
printf "\033[5B" # cursor down
printf "X"

```

```text
|A_________|
|__________|
|__________|
|__________|
|_Xc_______|

```

--------------------------------

### Validate Cursor Up Movement Above Top Margin (CUU V-3)

Source: https://ghostty.org/docs/vt/csi/cuu

Tests cursor movement when positioned above the configured scrolling region. If the starting position is already above the top margin, movement is bounded only by the first row of the screen.

```bash
printf "\033[1;1H" # move to top-left
printf "\033[0J" # clear screen
printf "\n\n\n\n\n" # screen is 5 high
printf "\033[3;5r" # set scrolling region
printf "\033[3;1H"
printf "A"
printf "\033[2;1H" # move above region
printf "\033[5A" # cursor up
printf "X"

```

```text
|Xc________|
|__________|
|A_________|
|__________|
|__________|

```

--------------------------------

### Bind key to open new window in Hyprland

Source: https://ghostty.org/docs/linux/systemd

Binds Super+Return to launch a new Ghostty window via D-Bus activation. Add this configuration to ~/.config/hypr/hyprland.conf.

```hyprlang
bind = SUPER, return, exec, ghostty +new-window

```

--------------------------------

### Configure selection-word-chars to modify word boundaries

Source: https://ghostty.org/docs/config/reference

Sets custom word boundary characters for double-click text selection operations. In this example, semicolons are omitted from boundary characters so they are treated as part of words.

```ini
selection-word-chars = " \t'\"│`|:,()[]{}<>$"

```

--------------------------------

### Run Ghostty Universal AppImage

Source: https://ghostty.org/docs/install/binary

Sets executable permissions on the downloaded Universal AppImage and launches Ghostty.

```shell
chmod a+x Ghostty-${VERSION}-${ARCH}.appimage
./Ghostty-${VERSION}-${ARCH}.appimage

```

--------------------------------

### Creation and Layout Commands

Source: https://ghostty.org/docs/features/applescript

AppleScript commands for instantiating windows, creating tabs, and splitting existing terminal panes with optional configuration records.

```APIDOC
## Creation and Layout

### Commands

#### `new window [with configuration <cfg>]`
Creates a new Ghostty window.
- **`with configuration`** (*surface configuration*, optional) - Configuration record applied to the new window.

#### `new tab [in <window>] [with configuration <cfg>]`
Creates a new tab within a target window.
- **`in`** (*window*, optional) - Target window for the new tab.
- **`with configuration`** (*surface configuration*, optional) - Configuration record applied to the new tab.

#### `split <terminal> [direction <right|down>] [with configuration <cfg>]`
Splits an existing terminal surface horizontally or vertically.
- **`<terminal>`** (*terminal*) - Target terminal surface to split.
- **`direction`** (*right | down*, optional) - Direction in which to split.
- **`with configuration`** (*surface configuration*, optional) - Configuration record applied to the new split pane.

### Example
```applescript
tell application "Ghostty"
    set cfg to new surface configuration
    set win to new window with configuration cfg
    set paneEditor to terminal 1 of selected tab of win
    set paneBuild to split paneEditor direction right with configuration cfg
    set paneGit to split paneEditor direction down with configuration cfg
end tell
```
```

--------------------------------

### Load Additional Configuration File with config-file

Source: https://ghostty.org/docs/config/reference

Demonstrates config-file load ordering where nested configuration files take effect after the entire enclosing file is loaded. If foo sets a = 2, the resulting value of a will be 2.

```ini
config-file = "foo"
a = 1

```

--------------------------------

### Creation and Layout Commands

Source: https://ghostty.org/docs/features/applescript

Commands for creating reusable surface configurations, opening new windows or tabs, and splitting existing terminal surfaces.

```APIDOC
### Creation and Layout Commands

#### `new surface configuration`
- **Purpose:** Create a reusable surface configuration record.
- **Syntax:** `set cfg to new surface configuration`

#### `new window`
- **Purpose:** Create a new window.
- **Syntax:** `set win to new window with configuration cfg`
- **Parameters:**
  - `with configuration` (optional) - Configuration record to apply.

#### `new tab`
- **Purpose:** Create a new tab in an optional target window.
- **Syntax:** `set t to new tab in win with configuration cfg`
- **Parameters:**
  - `in` (optional) - Target window reference.
  - `with configuration` (optional) - Configuration record to apply.

#### `split`
- **Purpose:** Split a terminal and return the new terminal.
- **Syntax:** `set t2 to split t1 direction right with configuration cfg`
- **Parameters:**
  - `direction` - Split direction: `right`, `left`, `down`, or `up`.
  - `with configuration` (optional) - Configuration record to apply.
```

--------------------------------

### Build Ghostty.app with Zig

Source: https://ghostty.org/docs/install/build

Compiles the macOS application and outputs Ghostty.app to zig-out/Ghostty.app. Uses the ReleaseLocal configuration intended for local testing without code signing.

```bash
zig build -Doptimize=ReleaseFast

```

--------------------------------

### Split configuration using config-file

Source: https://ghostty.org/docs/config

Loads external configuration files from relative paths, optional paths prefixed with ?, or absolute paths. All config-file directives are processed at the end of the file.

```ghostty
config-file = some/relative/sub/config
config-file = ?optional/config
config-file = /absolute/path/config

```

--------------------------------

### Validate simple ECH operation (ECH V-1)

Source: https://ghostty.org/docs/vt/csi/ech

Blanks specified character cells to the right starting at the cursor position.

```shell
printf "ABC"
printf "\033[1G"
printf "\033[2X"

```

```text
|c_C_____|

```

--------------------------------

### EL V-8: Simple Erase Left

Source: https://ghostty.org/docs/vt/csi/el

Erases characters from the cursor position to the start of the line using sequence \033[1K.

```shell
printf "ABCDE"
printf "\033[3G"
printf "\033[1K"

```

```text
|__cDE___|

```

--------------------------------

### List default keybindings CLI command

Source: https://ghostty.org/docs/config/keybind

Use the list-keybinds CLI command to inspect all default keybindings configured in Ghostty.

```shell
ghostty +list-keybinds --default
```

--------------------------------

### View Ghostty package details on openSUSE with zypper info

Source: https://ghostty.org/docs/install/binary

Checks the package information and metadata for Ghostty on openSUSE.

```shell
sudo zypper info ghostty

```

--------------------------------

### Configure separate light and dark themes

Source: https://ghostty.org/docs/features/theme

Set separate themes for light and dark modes to allow Ghostty to switch themes automatically based on system appearance.

```ini
theme = dark:Catppuccin Frappe,light:Catppuccin Latte

```

--------------------------------

### SU V-1: Simple Usage

Source: https://ghostty.org/docs/vt/csi/su

Demonstrates the default behavior of Scroll Up (SU) where lines shift upward and cursor position is preserved.

```bash
printf "\033[1;1H" # move to top-left
printf "\033[0J" # clear screen
printf "ABC\n"
printf "DEF\n"
printf "GHI\n"
printf "\033[2;2H"
printf "\033[S"

```

```text
|DEF_____|
|GHI_____|

```

--------------------------------

### Configure keybind trigger sequence

Source: https://ghostty.org/docs/config/keybind/sequence

Binds a multi-key trigger sequence where pressing ctrl+a followed by n executes the new_window action. Ghostty waits indefinitely for the next key in the sequence without a timeout.

```text
keybind = ctrl+a>n=new_window

```

--------------------------------

### Build Ghostty with Nix

Source: https://ghostty.org/docs/install/build

Builds Ghostty using Nix for higher reproducibility. The resulting executable is located at ./result/bin/ghostty.

```shell
nix build .#ghostty

```

--------------------------------

### Verify successful shell integration log output

Source: https://ghostty.org/docs/features/shell-integration

Displays expected log lines when Ghostty successfully locates resources and injects shell integration.

```text
info(io_exec): using Ghostty resources dir from env var: /Applications/Ghostty.app/Contents/Resources
info(io_exec): shell integration automatically injected shell=termio.shell_integration.Shell.fish

```

--------------------------------

### Input, Key, and Action Commands

Source: https://ghostty.org/docs/features/applescript

AppleScript commands to send text input, dispatch key presses, focus panes, and trigger Ghostty actions.

```APIDOC
## Input and Actions

### Commands

#### `input text <text> to <terminal>`
Sends raw text characters directly to a specified terminal surface.
- **`<text>`** (string) - Text to input into the terminal.
- **`to`** (*terminal*) - Destination terminal.

#### `send key <key> to <terminal>`
Sends key events (such as `"enter"`) to a specified terminal.
- **`<key>`** (string) - Key name or sequence to trigger.
- **`to`** (*terminal*) - Destination terminal.

#### `focus <terminal>`
Focuses the specified terminal pane or window.
- **`<terminal>`** (*terminal*) - Target terminal to bring into focus.

#### `perform action <action> on <terminal>`
Executes a Ghostty internal action on a terminal.
- **`<action>`** (string) - Action descriptor (e.g., `"set_tab_title:Editor"`).
- **`on`** (*terminal*) - Target terminal surface.

### Example
```applescript
tell application "Ghostty"
    set t to focused terminal of front window
    perform action "set_tab_title:Editor" on t
    input text "git status" to t
    send key "enter" to t
    focus t
end tell
```
```

--------------------------------

### Input and Action Commands

Source: https://ghostty.org/docs/features/applescript

Commands for sending text, key events, mouse events, and executing Ghostty keybind actions on target terminals.

```APIDOC
### Input and Actions Commands

#### `input text`
- **Purpose:** Send paste-style text input to a terminal.
- **Syntax:** `input text "echo hello" to t1`

#### `send key`
- **Purpose:** Send key press/release events with optional modifiers.
- **Syntax:** `send key "enter" to t1`
- **Parameters:**
  - `action` (optional) - `press` or `release`.
  - `modifiers` (optional) - Comma-separated string containing any of: `shift`, `control`, `option`, `command`.

#### `send mouse button`
- **Purpose:** Send mouse button events.
- **Syntax:** `send mouse button left button to t1`
- **Parameters:**
  - `action` (optional) - `press` or `release`.

#### `send mouse position`
- **Purpose:** Send pointer position updates.
- **Syntax:** `send mouse position x 240 y 120 to t1`

#### `send mouse scroll`
- **Purpose:** Send scroll events with precision/momentum options.
- **Syntax:** `send mouse scroll x 0 y -8 precision true to t1`

#### `perform action`
- **Purpose:** Execute a Ghostty action string on a terminal.
- **Syntax:** `perform action "toggle_fullscreen" on t1`
- **Notes:** Action strings match the action names used in keybind configuration.
```

--------------------------------

### Configure global keybind for toggle_quick_terminal

Source: https://ghostty.org/docs/config/keybind/reference

Binds a global shortcut to toggle the Quake-style quick terminal from anywhere in the system. Ghostty supports only one active quick terminal instance at a time, preserving its state between toggles.

```ini
keybind = global:cmd+backquote=toggle_quick_terminal

```

--------------------------------

### Validate CR unsets pending wrap state (CR V-1)

Source: https://ghostty.org/docs/vt/control/cr

Tests that sending a carriage return moves the cursor to the start of the line and clears the pending wrap state after printing at the last column.

```bash
cols=$(tput cols)
printf "\033[${cols}G" # move to last column
printf "A" # set pending wrap state
printf "\r"
printf "X"
echo

```

```text
|X________A|
|c_________|

```

--------------------------------

### new surface configuration

Source: https://ghostty.org/docs/features/applescript

Creates a reusable surface configuration record to customize properties before creating new windows, tabs, or splits.

```APIDOC
## Command: `new surface configuration`

### Description
Creates a reusable configuration record that can be passed to `new window`, `new tab`, and `split` commands.

### Record Fields
- **`font size`** (number) - Optional - Sets the terminal font size.
- **`initial working directory`** (string) - Optional - Path to the directory where the terminal opens.
- **`command`** (string) - Optional - Command to run upon initialization.
- **`initial input`** (string) - Optional - Input text sent to the terminal upon startup.
- **`wait after command`** (boolean) - Optional - Whether to wait after the command terminates.
- **`environment variables`** (list of strings) - Optional - List of environment variables in `KEY=VALUE` format.

### Example
```applescript
tell application "Ghostty"
    set cfg to new surface configuration
    set initial working directory of cfg to POSIX path of (path to home folder) & "src/ghostty"
    set font size of cfg to 13
    set environment variables of cfg to {"EDITOR=nvim", "FZF_DEFAULT_OPTS=--height 40%"}

    set win to new window with configuration cfg
end tell
```
```

--------------------------------

### Chain multiple actions to a keybind

Source: https://ghostty.org/docs/config/reference

Binds ctrl+a to open a new window and then move focus to the left split. Each chain entry appends an action to the most recently defined keybind.

```ghostty
keybind = ctrl+a=new_window
keybind = chain=goto_split:left

```

--------------------------------

### Focus, Selection, and Lifecycle Commands

Source: https://ghostty.org/docs/features/applescript

Commands to activate windows, switch tab selection, set focus to specific terminals, and close terminal instances, tabs, or windows.

```APIDOC
### Focus, Selection, and Lifecycle Commands

#### `focus`
- **Purpose:** Focus a terminal and bring its window to front.
- **Syntax:** `focus t1`

#### `activate window`
- **Purpose:** Bring a window to the front.
- **Syntax:** `activate window (window 1)`

#### `select tab`
- **Purpose:** Select a tab.
- **Syntax:** `select tab (tab 2 of window 1)`

#### `close`
- **Purpose:** Close a terminal.
- **Syntax:** `close (terminal 2 of selected tab of window 1)`

#### `close tab`
- **Purpose:** Close a tab.
- **Syntax:** `close tab (tab 2 of window 1)`

#### `close window`
- **Purpose:** Close a window.
- **Syntax:** `close window (window 1)`
```

--------------------------------

### Set built-in theme with the theme configuration option

Source: https://ghostty.org/docs/features/theme

Select a built-in theme such as Catppuccin Frappe in your configuration. Reload your Ghostty configuration after changing this setting.

```ini
theme = Catppuccin Frappe

```

--------------------------------

### Manage debug development builds

Source: https://ghostty.org/docs/linux/systemd

Commands for enabling, stopping, reloading, following logs, and opening new windows for Ghostty debug development builds.

```shell
systemctl enable --user app-com.mitchellh.ghostty-debug.service
systemctl stop --user app-com.mitchellh.ghostty-debug.service
systemctl reload --user app-com.mitchellh.ghostty-debug.service
journalctl -a -f --user -u app-com.mitchellh.ghostty-debug.service
ghostty +new-window --class=com.mitchellh.ghostty-debug.service

```

--------------------------------

### Manually source Ghostty shell integration in ~/.bashrc

Source: https://ghostty.org/docs/features/shell-integration

Place this snippet at the top of ~/.bashrc to enable Ghostty shell integration when GHOSTTY_RESOURCES_DIR is defined. Sourcing as early as possible prevents interference from other bash configurations.

```bash
# Ghostty shell integration for Bash. This should be at the top of your bashrc!
if [ -n "${GHOSTTY_RESOURCES_DIR}" ]; then
    builtin source "${GHOSTTY_RESOURCES_DIR}/shell-integration/bash/ghostty.bash"
fi

```

--------------------------------

### Define keybind syntax

Source: https://ghostty.org/docs/config/keybind

Specify custom keybindings using the basic keybind configuration option syntax mapping a trigger to an action.

```ini
keybind = trigger=action
```

--------------------------------

### Build a Tmux-Style Multi-Pane Layout

Source: https://ghostty.org/docs/features/applescript

Construct a multi-pane layout using split in multiple directions, send initial commands to each pane, and set focus to the primary editor terminal.

```applescript
set projectDir to POSIX path of (path to home folder) & "src/ghostty"

tell application "Ghostty"
    activate

    set cfg to new surface configuration
    set initial working directory of cfg to projectDir

    set win to new window with configuration cfg
    set paneEditor to terminal 1 of selected tab of win
    set paneBuild to split paneEditor direction right with configuration cfg
    set paneGit to split paneEditor direction down with configuration cfg
    set paneLogs to split paneBuild direction down with configuration cfg

    input text "nvim ." to paneEditor
    send key "enter" to paneEditor

    input text "zig build -Demit-macos-app=false" to paneBuild
    send key "enter" to paneBuild

    input text "git status -sb" to paneGit
    send key "enter" to paneGit

    input text "tail -f /tmp/dev.log" to paneLogs
    send key "enter" to paneLogs

    focus paneEditor
end tell

```

--------------------------------

### SU V-3: Left/Right Scroll Regions

Source: https://ghostty.org/docs/vt/csi/su

Tests Scroll Up (SU) execution with enabled left and right margin scroll regions.

```bash
printf "\033[1;1H" # move to top-left
printf "\033[0J" # clear screen
printf "ABC123\n"
printf "DEF456\n"
printf "GHI789\n"
printf "\033[?69h" # enable left/right margins
printf "\033[2;4s" # scroll region left/right
printf "\033[2;2H"
printf "\033[S"

```

```text
|AEF423__|
|DHI756__|
|G___89__|

```

--------------------------------

### List valid fonts with ghostty CLI

Source: https://ghostty.org/docs/config/reference

Runs the CLI command to display a list of valid font families available to configure in Ghostty.

```shell
ghostty +list-fonts

```

--------------------------------

### Reload Ghostty config using systemctl

Source: https://ghostty.org/docs/linux/systemd

Sends a SIGUSR2 signal to the main Ghostty process via systemd to reload its configuration. Use this instead of manual process tracking via ps.

```bash
systemctl reload --user app-com.mitchellh.ghostty.service

```

--------------------------------

### Configure performable keybind for copy_to_clipboard

Source: https://ghostty.org/docs/config/keybind

Binds `ctrl+c` to `copy_to_clipboard` conditionally so that input is only consumed when a selection is active. If no text is selected, Ghostty behaves as if the keybind is not set.

```config
keybind = performable:ctrl+c=copy_to_clipboard

```

--------------------------------

### Specify alternate ssh executable with --ssh

Source: https://ghostty.org/docs/features/ssh

Points +ssh to an explicit ssh binary path instead of finding the first executable in PATH. Fails if the provided path is not executable.

```bash
ghostty +ssh --ssh=/opt/homebrew/bin/ssh -- user@example.com

```

--------------------------------

### Configure auto-update-channel for macOS Prerelease Builds

Source: https://ghostty.org/docs/install/pre

Set the update channel to tip in the Ghostty configuration to receive prerelease builds on macOS. Restart Ghostty after modifying this setting for it to take effect.

```ini
auto-update-channel = tip

```

--------------------------------

### Configure AeroSpace window detection for Ghostty

Source: https://ghostty.org/docs/help/macos-tiling-wms

Sets the window layout to tiling upon detecting Ghostty in AeroSpace. If tabs still render as separate windows, replace layout tiling with layout floating, which floats the window on initial startup.

```toml
[[on-window-detected]]
if.app-id="com.mitchellh.ghostty"
run= [
  "layout tiling",
]

```

--------------------------------

### Fill screen with DECALN (DECALN V-1)

Source: https://ghostty.org/docs/vt/esc/decaln

Emits the DECALN sequence to reset margins, move the cursor to the top left, and fill the terminal display with unstyled 'E' characters.

```sh
printf "\033#8"

```

```text
|EEEEEEEE|
|EEEEEEEE|
|EEEEEEEE|

```

--------------------------------

### Chain arbitrary multiple actions

Source: https://ghostty.org/docs/config/reference

Appends multiple chained actions to execute in sequence on activation. Flags from the original keybind apply to the entire chain, and chained actions cannot use standalone prefixes.

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

```

--------------------------------

### Copy Ghostty terminfo entry to remote server with infocmp and tic

Source: https://ghostty.org/docs/help/terminfo

Exports Ghostty's terminfo entry from the local system and compiles it on the remote machine via SSH. macOS versions prior to Sonoma require infocmp from a newer Homebrew-installed ncurses package.

```shell
infocmp -x xterm-ghostty | ssh YOUR-SERVER -- tic -x -
```

--------------------------------

### Configure Yabai signals for Ghostty window events

Source: https://ghostty.org/docs/help/macos-tiling-wms

Registers Yabai signals to enforce BSP space layout whenever a Ghostty window is created or destroyed.

```shell
yabai -m signal --add app='^Ghostty$' event=window_created action='yabai -m space --layout bsp'
yabai -m signal --add app='^Ghostty$' event=window_destroyed action='yabai -m space --layout bsp'

```

--------------------------------

### Validate full screen scroll region with DECSTBM (V-1)

Source: https://ghostty.org/docs/vt/csi/decstbm

Tests setting a default full-screen scroll region using \033[r before scrolling down.

```sh
printf "\033[1;1H" # move to top-left
printf "\033[0J" # clear screen
printf "ABC\n"
printf "DEF\n"
printf "GHI\n"
printf "\033[r" # scroll region top/bottom
printf "\033[T"

```

```text
|c_______|
|ABC_____|
|DEF_____|
|GHI_____|

```

--------------------------------

### CUP V-2: Off the Screen

Source: https://ghostty.org/docs/vt/csi/cup

Demonstrates cursor positioning when coordinates exceed screen dimensions, clamping to the bottom-right corner.

```sh
printf "\033[1;1H" # move to top-left
printf "\033[0J" # clear screen
printf "\033[500;500H"
printf "A"

```

```text
|__________|
|__________|
|_________Ac

```

--------------------------------

### Verify Ghostty scripting with osascript

Source: https://ghostty.org/docs/features/applescript

Queries the Ghostty application version to verify that AppleScript scripting is functioning correctly.

```shell
osascript -e 'tell application "Ghostty" to get version'

```

--------------------------------

### Configure keybind with Unicode codepoint trigger

Source: https://ghostty.org/docs/config/keybind

Bind keys on non-US keyboard layouts by specifying Unicode codepoint characters along with modifiers.

```ini
keybind = ctrl+ö=action
```

--------------------------------

### Configure delayed shutdown after closing the last window

Source: https://ghostty.org/docs/linux/systemd

Quits the Ghostty process five minutes after the last window is closed to conserve system memory while retaining fast relaunch during active use.

```ini
quit-after-last-window-closed = true
quit-after-last-window-closed-delay = 5m

```

--------------------------------

### CUP V-1: Normal Usage

Source: https://ghostty.org/docs/vt/csi/cup

Moves the cursor to row 2, column 3 on a cleared screen and prints a character.

```sh
printf "\033[1;1H" # move to top-left
printf "\033[0J" # clear screen
printf "\033[2;3H"
printf "A"

```

```text
|__________|
|__Ac______|

```

--------------------------------

### Stop the service with systemctl stop

Source: https://ghostty.org/docs/linux/systemd

Gracefully stops the Ghostty systemd user service. Ghostty closes all open windows and terminates their running processes without asking for confirmation.

```shell
systemctl stop --user app-com.mitchellh.ghostty.service

```
Tokens:
Raw