Skip to main content
The validate-config command checks a Ghostty configuration file for syntax errors, invalid options, and configuration problems.

​
Usage

ghostty +validate-config [options]

​
Description

This command validates a Ghostty configuration file without launching the terminal. It reports any errors, warnings, or issues found in the configuration. When executed without arguments, it validates the configuration from the default location ($XDG_CONFIG_HOME/ghostty/config or equivalent for your platform). The command exits with code 0 if validation succeeds and code 1 if any problems are found.

​
Options

​
--config-file
string
Path to a specific configuration file to validate. If not specified, validates the default configuration file location.The path can be absolute or relative to the current directory.
​
-h, --help
flag
Display help information for this command.

​
Examples

​
Validate Default Configuration

ghostty +validate-config

(no output - exit code 0)

​
Validate Specific File

ghostty +validate-config --config-file=./test-config.txt
Validates a configuration file in the current directory.

​
Validate Absolute Path

ghostty +validate-config --config-file=/etc/ghostty/config
Validates a configuration file at an absolute path.

​
Check Exit Code

ghostty +validate-config
if [ $? -eq 0 ]; then
  echo "Configuration is valid"
else
  echo "Configuration has errors"
fi

#!/bin/bash

# Validate before using config
if ghostty +validate-config --config-file="$1"; then
    echo "✓ Configuration valid"
    cp "$1" ~/.config/ghostty/config
else
    echo "✗ Configuration invalid - not applying"
    exit 1
fi

​
Validate in CI/CD

GitHub Actions
name: Validate Ghostty Config

on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Install Ghostty
        run: |
          # Install ghostty...
      - name: Validate Config
        run: ghostty +validate-config --config-file=.ghostty

​
Common Validation Errors

​
Unknown Configuration Key

Error
config:5: unknown configuration key: "fond-family"
Cause: Typo in option name
Fix: Correct the option name (should be font-family)

​
Invalid Value Type

Error
config:12: invalid value for "font-size": must be a positive number
Cause: Wrong type for option value
Fix: Ensure the value matches the expected type

​
Invalid Enum Value

Error
config:20: invalid value for "cursor-style": must be one of: block, bar, underline
Cause: Invalid choice for enum option
Fix: Use one of the valid values listed

​
Syntax Error

Error
config:8: syntax error: expected '=' after key
Cause: Malformed configuration line
Fix: Ensure proper key = value format

​
Theme Not Found

Error
config:3: theme "my-theme" not found
Cause: Referenced theme doesn’t exist
Fix: Use ghostty +list-themes to find available themes

​
Font Not Found

Warning
config:6: font family "MyFont" not found on system
Cause: Specified font not available
Fix: Use ghostty +list-fonts to find available fonts

​
Validation Checks

The validator checks for:
  • Syntax errors: Malformed configuration lines
  • Unknown keys: Option names that don’t exist
  • Type errors: Values that don’t match the expected type
  • Range errors: Numeric values outside valid ranges
  • Enum errors: Invalid choices for option values
  • File references: Missing theme or font files
  • Keybind errors: Invalid keybinding syntax
  • Conditional errors: Malformed conditional configuration

​
Use Cases

​
Pre-Deployment Validation

ghostty +validate-config && \
  cp config ~/.config/ghostty/config && \
  echo "Config deployed successfully"

​
Editor Integration

Configure your editor to run validation on save:
.vimrc
autocmd BufWritePost *config.ghostty !ghostty +validate-config --config-file=%

​
Configuration Management

Script
#!/bin/bash
for config in configs/*.ghostty; do
    echo "Validating $config..."
    if ghostty +validate-config --config-file="$config"; then
        echo "  ✓ Valid"
    else
        echo "  ✗ Invalid"
        exit 1
    fi
done

​
Notes

Validation includes checking for recursive file inclusions and evaluating conditional configuration, so the validation represents the actual configuration that would be loaded.
Some warnings (like missing fonts) won’t prevent the configuration from loading, but will cause Ghostty to fall back to defaults. These still appear in validation output.
The validator resolves relative paths based on the configuration file’s location, just like Ghostty does when loading the config.

​
Exit Codes

  • 0 - Configuration is valid (no errors)
  • 1 - Configuration has errors or warnings

​
See Also