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

# Quick Start Guide

> Get up and running with Ghostty in under 5 minutes

# Quick Start Guide

Get Ghostty running on your system in minutes. This guide assumes you've already [installed Ghostty](/installation).

## First Launch

<Steps>
  <Step title="Launch Ghostty">
    Open Ghostty from your Applications folder (macOS) or application launcher (Linux).

    ```bash theme={null}
    # Or launch from terminal
    ghostty
    ```

    You'll see a new terminal window with Ghostty's default theme and settings.
  </Step>

  <Step title="Verify Installation">
    Check that Ghostty is working correctly:

    ```bash theme={null}
    # Check version
    ghostty --version

    # List available commands
    ghostty --help
    ```
  </Step>

  <Step title="Test Performance">
    Experience Ghostty's speed:

    ```bash theme={null}
    # Fast text rendering
    cat /usr/share/dict/words

    # Or generate some output
    for i in {1..1000}; do echo "Line $i: Ghostty is fast!"; done
    ```

    Notice how smoothly text renders even under heavy load.
  </Step>
</Steps>

## Basic Configuration

Ghostty's configuration file is located at:

* **macOS**: `~/.config/ghostty/config`
* **Linux**: `~/.config/ghostty/config` (or `$XDG_CONFIG_HOME/ghostty/config`)

<Note>
  If the config file doesn't exist, create it along with the directory:

  ```bash theme={null}
  mkdir -p ~/.config/ghostty
  touch ~/.config/ghostty/config
  ```
</Note>

### Essential Configuration

Add these settings to your `~/.config/ghostty/config` file:

<CodeGroup>
  ```bash Basic Setup theme={null}
  # Font configuration
  font-family = "JetBrains Mono"
  font-size = 13

  # Theme colors
  background = #1e1e2e
  foreground = #cdd6f4

  # Cursor settings
  cursor-style = block
  cursor-color = #f5e0dc
  ```

  ```bash Developer Setup theme={null}
  # Font with ligatures
  font-family = "Fira Code"
  font-size = 12
  font-feature = +liga
  font-feature = +calt

  # Catppuccin Mocha theme
  background = #1e1e2e
  foreground = #cdd6f4

  # Palette colors
  palette = 0=#45475a
  palette = 1=#f38ba8
  palette = 2=#a6e3a1
  palette = 3=#f9e2af
  palette = 4=#89b4fa
  palette = 5=#f5c2e7
  palette = 6=#94e2d5
  palette = 7=#bac2de

  # Window settings
  window-padding-x = 10
  window-padding-y = 10
  window-theme = dark
  ```

  ```bash Minimal Setup theme={null}
  # Just the essentials
  font-family = "SF Mono"
  font-size = 13
  theme = catppuccin-mocha
  ```
</CodeGroup>

<Tip>
  Ghostty comes with built-in themes! Use `ghostty +list-themes` to see all available themes, then set one with `theme = theme-name` in your config.
</Tip>

### Apply Configuration Changes

Ghostty automatically reloads configuration when you save changes. No restart required!

```bash theme={null}
# Edit your config
ghosstty +edit-config

# Or validate your config
ghosstty +validate-config

# View current config
ghosstty +show-config
```

## Essential Keybindings

Ghostty comes with sensible defaults. Here are the most important shortcuts:

### macOS

| Action           | Keybinding      |
| ---------------- | --------------- |
| New Window       | `⌘ + N`         |
| New Tab          | `⌘ + T`         |
| Close Tab/Window | `⌘ + W`         |
| Split Horizontal | `⌘ + D`         |
| Split Vertical   | `⌘ + Shift + D` |
| Next Tab         | `⌘ + Shift + ]` |
| Previous Tab     | `⌘ + Shift + [` |
| Settings         | `⌘ + ,`         |
| Clear Screen     | `⌘ + K`         |

### Linux

| Action           | Keybinding           |
| ---------------- | -------------------- |
| New Window       | `Ctrl + Shift + N`   |
| New Tab          | `Ctrl + Shift + T`   |
| Close Tab/Window | `Ctrl + Shift + W`   |
| Split Horizontal | `Ctrl + Shift + D`   |
| Next Tab         | `Ctrl + Tab`         |
| Previous Tab     | `Ctrl + Shift + Tab` |
| Clear Screen     | `Ctrl + Shift + K`   |

<Info>
  All keybindings are fully customizable. See [Keybindings Configuration](/config/keybindings) for details.
</Info>

## Working with Windows and Splits

<Steps>
  <Step title="Create a Split">
    Split your terminal horizontally or vertically:

    * **Horizontal**: `⌘ + D` (macOS) or `Ctrl + Shift + D` (Linux)
    * **Vertical**: `⌘ + Shift + D` (macOS)

    Navigate between splits using focus keybindings.
  </Step>

  <Step title="Open Multiple Tabs">
    Create tabs for different tasks:

    * **New Tab**: `⌘ + T` (macOS) or `Ctrl + Shift + T` (Linux)
    * **Switch Tabs**: `⌘ + Shift + ]` / `[` (macOS) or `Ctrl + Tab` (Linux)
  </Step>

  <Step title="Multiple Windows">
    Open multiple independent Ghostty windows:

    * **New Window**: `⌘ + N` (macOS) or `Ctrl + Shift + N` (Linux)
  </Step>
</Steps>

## Discovering Fonts and Themes

### List Available Fonts

```bash theme={null}
# See all fonts Ghostty can find
ghosstty +list-fonts

# Search for a specific font
ghosstty +list-fonts | grep -i "mono"
```

### Explore Built-in Themes

```bash theme={null}
# List all themes
ghosstty +list-themes

# Some popular themes:
# - catppuccin-mocha
# - dracula
# - nord
# - solarized-dark
# - tokyo-night
```

Add your chosen theme to config:

```bash theme={null}
theme = catppuccin-mocha
```

## Enable Shell Integration

Shell integration adds powerful features like:

* Jump between prompts
* Semantic understanding of shell output
* Better clipboard integration
* Command status indicators

<Tabs>
  <Tab title="Bash">
    Add to your `~/.bashrc`:

    ```bash theme={null}
    if [ -n "$GHOSTTY_RESOURCES_DIR" ]; then
        source "$GHOSTTY_RESOURCES_DIR/shell-integration/bash/ghostty.bash"
    fi
    ```
  </Tab>

  <Tab title="Zsh">
    Add to your `~/.zshrc`:

    ```zsh theme={null}
    if [ -n "$GHOSTTY_RESOURCES_DIR" ]; then
        source "$GHOSTTY_RESOURCES_DIR/shell-integration/zsh/ghostty.zsh"
    fi
    ```
  </Tab>

  <Tab title="Fish">
    Add to your `~/.config/fish/config.fish`:

    ```fish theme={null}
    if set -q GHOSTTY_RESOURCES_DIR
        source "$GHOSTTY_RESOURCES_DIR/shell-integration/fish/ghostty.fish"
    end
    ```
  </Tab>
</Tabs>

<Info>
  Learn more about shell integration features in the [Shell Integration guide](/features/shell-integration).
</Info>

## Useful CLI Commands

Ghostty provides helpful CLI tools:

```bash theme={null}
# Edit config in your default editor
ghosstty +edit-config

# Validate your configuration
ghosstty +validate-config

# Show effective configuration (including defaults)
ghosstty +show-config

# List all keybindings
ghosstty +list-keybinds

# List all available actions
ghosstty +list-actions

# Check for crash reports
ghosstty +crash-report
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Deep Dive into Configuration" icon="sliders" href="/config/overview">
    Explore all configuration options for fonts, colors, keybindings, and more
  </Card>

  <Card title="Customize Appearance" icon="palette" href="/config/appearance">
    Learn about themes, colors, and visual customization
  </Card>

  <Card title="Master Features" icon="graduation-cap" href="/features/themes">
    Discover advanced features like custom themes and performance tuning
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/guides/troubleshooting">
    Get help with common issues and configuration problems
  </Card>
</CardGroup>

## Getting Help

If you run into issues:

1. **Check logs**: Ghostty logs to stderr by default
   * **macOS**: `sudo log stream --level debug --predicate 'subsystem=="com.mitchellh.ghostty"'`
   * **Linux**: `journalctl --user --unit app-com.mitchellh.ghostty.service`

2. **Validate config**: Run `ghostty +validate-config` to catch syntax errors

3. **Review documentation**: Check the [Troubleshooting Guide](/guides/troubleshooting)

4. **Join the community**: Report issues on [GitHub](https://github.com/ghostty-org/ghostty)

<Tip>
  You're now ready to use Ghostty! Experiment with different themes, fonts, and configurations to make it your own.
</Tip>