> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/ghostty-org/ghostty/llms.txt
> Use this file to discover all available pages before exploring further.

# Terminal Behavior Configuration

> Configure terminal behavior, PTY settings, scrollback, and shell integration

## Command Configuration

### Default Command

```ini theme={null}
# Set the command to run (usually a shell)
command = /bin/zsh
command = fish
command = nvim
```

If not set, Ghostty uses:

1. `$SHELL` environment variable
2. `passwd` entry (user information)

<Accordion title="How do I pass arguments to the command?">
  Include arguments in the command string:

  ```ini theme={null}
  command = fish --with --custom --args
  ```

  Ghostty executes this via `/bin/sh -c` for shell expansion.
</Accordion>

### Command Execution Modes

```ini theme={null}
# Shell expansion (default)
command = nvim foo  # Executed via /bin/sh -c

# Direct execution (no shell, faster)
command = direct:nvim foo  # Executed directly

# Explicit shell (force shell expansion)
command = shell:nvim foo  # Always wrap in shell
```

<Note>
  **direct** mode avoids the `/bin/sh` roundtrip but doesn't support shell features like:

  * Arguments with spaces
  * Tilde expansion (`~`)
  * Globs (`*.txt`)
  * Shell variables
</Note>

### Initial Command

```ini theme={null}
# Command for the FIRST terminal surface only
initial-command = tmux attach
```

Subsequent terminals use the `command` setting.

<Tip>
  Use the `-e` flag for a convenient shortcut:

  ```bash theme={null}
  ghostty -e nvim file.txt
  ```

  This automatically:

  * Disables shell expansion
  * Sets `gtk-single-instance=false`
  * Sets `quit-after-last-window-closed=true`
  * Sets `shell-integration=detect` (if not `none`)
</Tip>

## Environment Variables

```ini theme={null}
# Set environment variables
env = FOO=bar
env = PATH=/custom/path:$PATH

# Clear all environment variables
env =

# Remove a specific variable
env = FOO=
```

<Info>
  These variables override Ghostty's automatic variables (like `GHOSTTY_RESOURCES_DIR`).

  They do **not** affect commands run by Ghostty for other purposes (like `open` or `xdg-open` for URLs).

  Available since 1.2.0.
</Info>

## Command Input

Send data to command on startup:

```ini theme={null}
# Send raw text
input = raw:Hello, world!\n
# Read from file
input = path:/path/to/file.txt

# Without prefix (assumed to be raw)
input = "ls -la\n"
```

<Warning>
  Input is sent as-is. Be cautious with control characters - they can execute programs in a shell.

  Files are limited to 10MB. Don't use special files like `/dev/stdin` or `/dev/urandom` (they'll block startup).
</Warning>

<Note>
  Repeatable configuration. Data is concatenated directly with no separator.

  If any input source doesn't exist, **no input** is sent at all.

  Changes only affect new terminals.

  Available since 1.2.0.
</Note>

## Command Behavior

### Wait After Command

```ini theme={null}
# Keep terminal open after command exits
wait-after-command = true
```

Terminal stays open until any keypress. Useful for scripts and debugging.

### Abnormal Exit Detection

```ini theme={null}
# Runtime below which exit is considered abnormal (in milliseconds)
abnormal-command-exit-runtime = 250  # Default
```

Shows error message when process exits too quickly.

<Tabs>
  <Tab title="Linux">
    Requires non-zero exit code.
  </Tab>

  <Tab title="macOS">
    Allows any exit code (due to login command behavior).
  </Tab>
</Tabs>

### Confirm Close

```ini theme={null}
confirm-close-surface = true     # Confirm if process running (default)
confirm-close-surface = false    # Never confirm
confirm-close-surface = always   # Always confirm
```

<Note>
  When `true`, Ghostty uses shell integration to detect if a process is running. Without shell integration, always confirms.
</Note>

## Scrollback

### Scrollback Limit

```ini theme={null}
# Scrollback buffer size in bytes
scrollback-limit = 10000000  # 10MB (default)
scrollback-limit = 100000000 # 100MB
```

<Info>
  This is the **total** memory for scrollback + active screen. Enough memory is always allocated for the visible screen; leftover is scrollback.

  Scrollback is allocated lazily, so large values don't immediately consume memory.

  This is **per terminal surface**, not application-wide.

  Changes only affect new terminals.
</Info>

<Warning>
  Unlimited scrollback is not currently possible (planned for future).
</Warning>

### Scrollbar Visibility (macOS)

```ini theme={null}
scrollbar = system  # Respect system settings (default)
scrollbar = never   # Never show scrollbar
```

<Note>
  **macOS only**. GTK doesn't yet support scrollbars.

  With `never`, you can still scroll via mouse, keybinds, etc.
</Note>

### Scroll to Bottom

```ini theme={null}
scroll-to-bottom = keystroke,no-output  # Default
scroll-to-bottom = keystroke,output
scroll-to-bottom = no-keystroke,output
```

**Options**:

* `keystroke`: Scroll to bottom on keypress that sends data to PTY
* `output`: Scroll to bottom on new output (currently unimplemented)

<Note>
  Prefix with `no-` to disable an option.
</Note>

## Mouse Behavior

### Mouse Reporting

```ini theme={null}
mouse-reporting = true   # Allow apps to capture mouse (default)
mouse-reporting = false  # Always use mouse for selection
```

Toggle at runtime with `toggle_mouse_reporting` keybind.

### Mouse Shift Capture

```ini theme={null}
mouse-shift-capture = false   # Shift extends selection (default)
mouse-shift-capture = true    # Shift is sent to app (if app requests)
mouse-shift-capture = never   # Shift always extends selection
mouse-shift-capture = always  # Shift always sent to app
```

<Accordion title="What's the difference between values?">
  * `false`/`never`: Apps can request shift with `XTSHIFTESCAPE` (or not with `never`)
  * `true`/`always`: Shift sent by default, apps can toggle with `XTSHIFTESCAPE` (or not with `always`)

  Use `never` if you always want shift to extend selection.
</Accordion>

### Mouse Scroll Multiplier

```ini theme={null}
# Universal multiplier
mouse-scroll-multiplier = 3      # Discrete devices (default)
mouse-scroll-multiplier = 1      # Precision devices (default)

# Device-specific multipliers (since 1.2.1)
mouse-scroll-multiplier = precision:0.1,discrete:3
mouse-scroll-multiplier = precision:1
mouse-scroll-multiplier = discrete:5
```

<Warning>
  Value is clamped to \[0.01, 10,000]. Both extremes provide a bad experience.
</Warning>

### Hide Mouse While Typing

```ini theme={null}
mouse-hide-while-typing = true
```

Mouse reappears on movement, button press, etc.

<Note>
  Platform behavior may show mouse in other scenarios (e.g., macOS shows mouse when creating new windows/tabs/splits).
</Note>

### Click to Move Cursor

```ini theme={null}
# Alt/Option+click to move cursor at prompt
cursor-click-to-move = true  # Default
```

<Info>
  Requires **shell integration** (specifically prompt marking via OSC 133). Only works in primary screen mode.

  Works by synthesizing arrow key movements. Some edge cases may behave unexpectedly.
</Info>

### Click Repeat Interval

```ini theme={null}
# Time between clicks for double/triple-click (milliseconds)
click-repeat-interval = 0     # Platform default
click-repeat-interval = 500   # 500ms
```

<Tabs>
  <Tab title="macOS">
    Default determined by OS settings.
  </Tab>

  <Tab title="Other">
    Default is 500ms.
  </Tab>
</Tabs>

### Right-Click Action

```ini theme={null}
right-click-action = context-menu   # Show menu (default)
right-click-action = paste          # Paste clipboard
right-click-action = copy           # Copy selection
right-click-action = copy-or-paste  # Copy if selection, else paste
right-click-action = ignore         # Do nothing
```

### Focus Follows Mouse

```ini theme={null}
focus-follows-mouse = false  # Default
focus-follows-mouse = true   # Focus split on hover
```

<Note>
  Only applies to the currently focused window. Hovering over unfocused windows doesn't change focus.
</Note>

## Selection

### Selection Colors

See [Appearance Configuration](/config/appearance#selection-colors) for selection color options.

### Selection Behavior

```ini theme={null}
# Clear selection when typing
selection-clear-on-typing = true  # Default

# Clear selection after copying
selection-clear-on-copy = false   # Default
```

<Info>
  `selection-clear-on-typing` is triggered by:

  * Any non-modifier keypress that sends data to PTY
  * Preedit/composition start (e.g., Japanese input)

  Selection can still be cleared by clicking once or pressing Escape.
</Info>

<Note>
  `selection-clear-on-copy` only applies to `copy_to_clipboard` keybind action, **not** `copy-on-select`.
</Note>

### Copy on Select

```ini theme={null}
copy-on-select = true         # Copy to selection clipboard (default Linux/macOS)
copy-on-select = false        # Disabled (default other)
copy-on-select = clipboard    # Copy to both selection and system clipboard
```

<Info>
  Middle-click paste always uses the selection clipboard, even when `copy-on-select = false`.
</Info>

### Selection Word Characters

```ini theme={null}
# Characters that mark word boundaries (default: space, tab, quotes, etc.)
selection-word-chars = " \t'\"│`|:;,()[]{}<>$"
```

Used for double-click word selection. Null character (U+0000) is always a boundary.

<Accordion title="How do I make semicolons part of words?">
  Remove `;` from the default value:

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

<Note>
  Only single codepoints supported. Multi-codepoint sequences (emoji) not supported.

  Available since 1.3.0.
</Note>

## Clipboard

### Clipboard Access

```ini theme={null}
clipboard-read = ask     # Prompt user (default)
clipboard-write = allow  # Allow without prompt (default)

# Valid values: ask, allow, deny
```

Controls program access to clipboard via OSC 52.

### Clipboard Paste Protection

```ini theme={null}
# Confirm before pasting unsafe text
clipboard-paste-protection = true  # Default

# Bracketed pastes are safe
clipboard-paste-bracketed-safe = true  # Default
```

Prevents copy/paste attacks where pasted text contains newlines that execute commands.

### Clipboard Trimming

```ini theme={null}
# Trim trailing whitespace when copying
clipboard-trim-trailing-spaces = true  # Default
```

Only trims trailing whitespace on lines with other characters. Blank lines always trimmed.

### Clipboard Codepoint Mapping

```ini theme={null}
# Replace characters when copying to clipboard
clipboard-codepoint-map = U+2500=U+002D  # Box horizontal → hyphen
clipboard-codepoint-map = U+2502=U+007C  # Box vertical → pipe
clipboard-codepoint-map = U+03A3=SUM     # Greek sigma → "SUM"
```

<Note>
  Does **not** apply to URL copying (only text copying).

  Later entries override earlier ones for overlapping ranges.
</Note>

## Shell Integration

### Auto-Injection

```ini theme={null}
shell-integration = detect   # Auto-detect shell (default)
shell-integration = none     # Disable auto-injection
shell-integration = bash     # Force bash injection
shell-integration = fish     # Force fish injection
shell-integration = zsh      # Force zsh injection
shell-integration = elvish   # Force elvish injection
shell-integration = nushell  # Force nushell injection
```

<Info>
  Shell integration enables:

  * Working directory reporting (for directory inheritance)
  * Prompt marking (for `jump_to_prompt` keybind)
  * No confirmation when closing at a prompt
  * Better prompt repainting on resize
</Info>

<Tip>
  You can manually source the integration script even with `shell-integration = none`.
</Tip>

### Shell Integration Features

```ini theme={null}
# Enable/disable specific features
shell-integration-features = cursor,sudo,title,ssh-env,ssh-terminfo,path
shell-integration-features = no-cursor,ssh-env

# Or enable/disable all
shell-integration-features = true
shell-integration-features = false
```

**Available features**:

<Accordion title="cursor">
  Set cursor to a bar at the prompt.
</Accordion>

<Accordion title="sudo">
  Set sudo wrapper to preserve terminfo.
</Accordion>

<Accordion title="title">
  Set window title via shell integration.
</Accordion>

<Accordion title="ssh-env">
  SSH environment variable compatibility:

  * Converts `TERM` from `xterm-ghostty` to `xterm-256color` on remote hosts
  * Propagates `COLORTERM`, `TERM_PROGRAM`, `TERM_PROGRAM_VERSION`

  Requires remote `sshd_config` to accept these variables.

  (Available since 1.2.0)
</Accordion>

<Accordion title="ssh-terminfo">
  Automatic terminfo installation on remote hosts:

  * Installs Ghostty's terminfo entry using `infocmp` and `tic`
  * Requires `infocmp` locally, `tic` on remote hosts
  * Automatically cached to avoid repeat installations

  Manage cache with `ghostty +ssh-cache` CLI action.

  (Available since 1.2.0)
</Accordion>

<Accordion title="path">
  Add Ghostty's binary directory to `PATH`. Ensures `ghostty` command is available even if shell init scripts reset PATH.

  Particularly useful on macOS where PATH is often overridden. Only added if not already present.
</Accordion>

<Info>
  **SSH features** work independently and can be combined:

  * Both `ssh-env` + `ssh-terminfo`: Use `xterm-ghostty` with terminfo installation, fallback to `xterm-256color` with env vars if installation fails
  * Just `ssh-env`: Always use `xterm-256color` with env vars
  * Just `ssh-terminfo`: Install terminfo and use `xterm-ghostty`
</Info>

## Command Notifications (GTK)

### When to Notify

```ini theme={null}
notify-on-command-finish = never      # Never notify (default)
notify-on-command-finish = unfocused  # Notify if surface unfocused
notify-on-command-finish = always     # Always notify
```

<Note>
  **GTK only**. Requires shell integration or OSC 133 sequences.

  GTK context menu has an option to enable notifications for a single command.

  Available since 1.3.0.
</Note>

### Notification Action

```ini theme={null}
# How to notify
notify-on-command-finish-action = bell,notify
notify-on-command-finish-action = notify
notify-on-command-finish-action = bell,no-notify
```

**Options**:

* `bell`: Terminal bell (enabled by default)
* `notify`: System notification (disabled by default)

<Note>
  **GTK only**. Available since 1.3.0.
</Note>

### Notification Threshold

```ini theme={null}
# Minimum command runtime before notifying (default: 5 seconds)
notify-on-command-finish-after = 5s
notify-on-command-finish-after = 1m30s
notify-on-command-finish-after = 500ms
```

<Note>
  **GTK only**. Available since 1.3.0.
</Note>

## Terminal Features

### Image Storage

```ini theme={null}
# Maximum image data per screen (in bytes)
image-storage-limit = 320000000  # 320MB (default)
image-storage-limit = 0          # Disable images
```

<Info>
  Limit is **per screen** (primary and alternate), so effective limit per surface is double.

  Maximum value: 4,294,967,295 (4GiB).
</Info>

### Title Reporting

```ini theme={null}
# Allow terminal title queries (CSI 21 t)
title-report = false  # Disabled (default)
```

<Warning>
  **Security risk**: Can expose sensitive information or enable code execution with crafted titles. Only enable if you trust all running programs.

  Available since 1.0.1.
</Warning>

### KAM Mode

```ini theme={null}
# Allow keyboard lock mode (ANSI mode 2)
vt-kam-allowed = false  # Default
```

<Warning>
  Rare feature. If you don't know you need KAM, you don't need it.
</Warning>

### OSC Color Reporting

```ini theme={null}
osc-color-report-format = 16-bit  # Default
osc-color-report-format = 8-bit   # Legacy 8-bit
osc-color-report-format = none    # Disable reporting
```

Controls format for OSC 4/10/11 color queries.

## Working Directory

```ini theme={null}
working-directory = inherit  # Use launching process CWD (default)
working-directory = home     # Use home directory
working-directory = /path    # Use specific path
```

<Info>
  This is **secondary** to `window-inherit-working-directory`. Inheritance takes precedence if a previous terminal exists.

  Typically only used for the first window.
</Info>

<Note>
  **Platform defaults**:

  * **macOS**: `home` if launched from launchd or `open`
  * **Linux/GTK**: `home` if launched from desktop launcher
  * Otherwise: `inherit`
</Note>

## Quit Behavior

### Quit After Last Window

```ini theme={null}
quit-after-last-window-closed = false  # macOS default
quit-after-last-window-closed = true   # Linux default
```

<Tabs>
  <Tab title="macOS">
    Default `false` matches standard macOS app behavior (app stays running).
  </Tab>

  <Tab title="Linux">
    Default `true` matches expected Linux behavior.

    Can delay quitting with `quit-after-last-window-closed-delay`.
  </Tab>
</Tabs>

### Quit Delay (Linux)

```ini theme={null}
# Delay before quitting (minimum: 1s)
quit-after-last-window-closed-delay = 5s
quit-after-last-window-closed-delay = 1m
```

<Note>
  **Linux only**. Only has effect if `quit-after-last-window-closed = true`.

  Minimum value: 1s.
</Note>

## Resources

<CardGroup cols={2}>
  <Card title="Shell Integration" icon="terminal" href="/guides/shell-integration">
    Detailed shell integration guide
  </Card>

  <Card title="SSH Configuration" icon="network-wired" href="/guides/ssh">
    Using Ghostty with SSH
  </Card>

  <Card title="Keybindings" icon="keyboard" href="/config/keybindings">
    Terminal-related keybind actions
  </Card>

  <Card title="Window Settings" icon="window-maximize" href="/config/window">
    Window and tab configuration
  </Card>
</CardGroup>