Configuration API

Configuration management functions for libghostty

Configuration API

The libghostty configuration API provides functions for creating, loading, and managing terminal configuration.

Creating Configuration

ghostty_config_new

Creates a new configuration object with default values.

ghostty_config_t ghostty_config_new();

Returns: A new configuration object that must be freed with ghostty_config_free().

Example:

ghostty_config_t config = ghostty_config_new();
if (!config) {
    fprintf(stderr, "Failed to create config\n");
    return 1;
}

ghostty_config_free

Frees a configuration object.

void ghostty_config_free(ghostty_config_t config);

config · ghostty_config_t · required

The configuration object to free.

Example:

ghostty_config_free(config);

ghostty_config_clone

Creates a deep copy of a configuration object.

ghostty_config_t ghostty_config_clone(ghostty_config_t config);

config · ghostty_config_t · required

The configuration to clone.

Returns: A new configuration object with the same settings.

Example:

ghostty_config_t cloned = ghostty_config_clone(original_config);
// Modify cloned config without affecting original

Loading Configuration

ghostty_config_load_default_files

Loads configuration from default file locations.

void ghostty_config_load_default_files(ghostty_config_t config);

config · ghostty_config_t · required

The configuration object to load into.

Searches for configuration files in these locations (in order):

1. $XDG_CONFIG_HOME/ghostty/config (or ~/.config/ghostty/config if XDG_CONFIG_HOME is not set)
2. Platform-specific locations

Example:

ghostty_config_t config = ghostty_config_new();
ghostty_config_load_default_files(config);

ghostty_config_load_file

Loads configuration from a specific file.

void ghostty_config_load_file(ghostty_config_t config, const char* path);

config · ghostty_config_t · required

The configuration object to load into.

path · const char* · required

Path to the configuration file.

Example:

ghostty_config_t config = ghostty_config_new();
ghostty_config_load_file(config, "/path/to/custom/config");

ghostty_config_load_cli_args

Loads configuration from command-line arguments.

void ghostty_config_load_cli_args(ghostty_config_t config);

config · ghostty_config_t · required

The configuration object to load into.

Parses command-line arguments passed to ghostty_init() and applies them to the configuration.

Example:

// Command line: ./app --font-size=14 --theme=nord
ghostty_config_t config = ghostty_config_new();
ghostty_config_load_cli_args(config);

ghostty_config_load_recursive_files

Loads configuration from files recursively (e.g., imports).

void ghostty_config_load_recursive_files(ghostty_config_t config);

config · ghostty_config_t · required

The configuration object to load into.

Processes any import directives in the configuration files.

ghostty_config_finalize

Finalizes the configuration, applying defaults and validating settings.

void ghostty_config_finalize(ghostty_config_t config);

config · ghostty_config_t · required

The configuration object to finalize.

You must call this function after loading all configuration sources and before using the configuration.

Example:

ghostty_config_t config = ghostty_config_new();
ghostty_config_load_default_files(config);
ghostty_config_load_cli_args(config);
ghostty_config_finalize(config);  // Required!

Querying Configuration

ghostty_config_get

Retrieves a configuration value by key.

bool ghostty_config_get(
    ghostty_config_t config,
    void* result,
    const char* key,
    uintptr_t key_len
);

config · ghostty_config_t · required

The configuration object to query.

result · void* · required

Pointer to store the result. The type depends on the configuration key.

key · const char* · required

The configuration key name.

key_len · uintptr_t · required

Length of the key string.

Returns: true if the key exists and was retrieved successfully, false otherwise.

Example:

float font_size;
if (ghostty_config_get(config, &font_size, "font-size", 9)) {
    printf("Font size: %.1f\n", font_size);
}

ghostty_config_color_s bg_color;
if (ghostty_config_get(config, &bg_color, "background", 10)) {
    printf("Background: #%02x%02x%02x\n", bg_color.r, bg_color.g, bg_color.b);
}

ghostty_config_trigger

Retrieves the trigger (keybinding) for an action.

ghostty_input_trigger_s ghostty_config_trigger(
    ghostty_config_t config,
    const char* action,
    uintptr_t action_len
);

config · ghostty_config_t · required

The configuration object to query.

action · const char* · required

The action name.

action_len · uintptr_t · required

Length of the action string.

Returns: The input trigger for the action.

Example:

ghostty_input_trigger_s trigger = ghostty_config_trigger(
    config,
    "new_window",
    10
);

Diagnostics

ghostty_config_diagnostics_count

Returns the number of configuration diagnostics (errors/warnings).

uint32_t ghostty_config_diagnostics_count(ghostty_config_t config);

config · ghostty_config_t · required

The configuration object to check.

Returns: Number of diagnostics.

ghostty_config_get_diagnostic

Retrieves a diagnostic message by index.

ghostty_diagnostic_s ghostty_config_get_diagnostic(
    ghostty_config_t config,
    uint32_t index
);

config · ghostty_config_t · required

The configuration object to query.

index · uint32_t · required

Index of the diagnostic (0-based).

Returns: The diagnostic message.

Example:

uint32_t count = ghostty_config_diagnostics_count(config);
for (uint32_t i = 0; i < count; i++) {
    ghostty_diagnostic_s diag = ghostty_config_get_diagnostic(config, i);
    fprintf(stderr, "Config error: %s\n", diag.message);
}

Utilities

ghostty_config_open_path

Returns the path to the configuration file that would be opened.

ghostty_string_s ghostty_config_open_path(void);

Returns: A string containing the configuration file path. Must be freed with ghostty_string_free().

Example:

ghostty_string_s path = ghostty_config_open_path();
if (path.ptr) {
    printf("Config file: %.*s\n", (int)path.len, path.ptr);
    ghostty_string_free(path);
}

Configuration Types

ghostty_config_color_list_s

A list of colors.

typedef struct {
  const ghostty_config_color_s* colors;
  size_t len;
} ghostty_config_color_list_s;

colors · const ghostty_config_color_s*

Pointer to array of colors.

len · size_t

Number of colors in the array.

ghostty_config_palette_s

A 256-color palette.

typedef struct {
  ghostty_config_color_s colors[256];
} ghostty_config_palette_s;

colors · ghostty_config_color_s[256]

Array of 256 colors (standard terminal color palette).

ghostty_config_command_list_s

A list of commands.

typedef struct {
  const ghostty_command_s* commands;
  size_t len;
} ghostty_config_command_list_s;

ghostty_quick_terminal_size_tag_e

Quick terminal size specification type.

typedef enum {
  GHOSTTY_QUICK_TERMINAL_SIZE_NONE,
  GHOSTTY_QUICK_TERMINAL_SIZE_PERCENTAGE,
  GHOSTTY_QUICK_TERMINAL_SIZE_PIXELS,
} ghostty_quick_terminal_size_tag_e;

ghostty_quick_terminal_size_s

Quick terminal size specification.

typedef struct {
  ghostty_quick_terminal_size_tag_e tag;
  ghostty_quick_terminal_size_value_u value;
} ghostty_quick_terminal_size_s;

ghostty_config_quick_terminal_size_s

Quick terminal size configuration.

typedef struct {
  ghostty_quick_terminal_size_s primary;
  ghostty_quick_terminal_size_s secondary;
} ghostty_config_quick_terminal_size_s;

primary · ghostty_quick_terminal_size_s

Primary dimension (width for horizontal, height for vertical).

secondary · ghostty_quick_terminal_size_s

Secondary dimension (height for horizontal, width for vertical).

Complete Example

#include <ghostty.h>
#include <stdio.h>

int main(int argc, char** argv) {
    // Initialize
    if (ghostty_init(argc, (char**)argv) != GHOSTTY_SUCCESS) {
        return 1;
    }
    
    // Create config
    ghostty_config_t config = ghostty_config_new();
    
    // Load from default locations
    ghostty_config_load_default_files(config);
    
    // Load CLI args (can override file settings)
    ghostty_config_load_cli_args(config);
    
    // Process imports
    ghostty_config_load_recursive_files(config);
    
    // Finalize (required)
    ghostty_config_finalize(config);
    
    // Check for errors
    uint32_t diag_count = ghostty_config_diagnostics_count(config);
    if (diag_count > 0) {
        fprintf(stderr, "Configuration errors:\n");
        for (uint32_t i = 0; i < diag_count; i++) {
            ghostty_diagnostic_s diag = ghostty_config_get_diagnostic(config, i);
            fprintf(stderr, "  - %s\n", diag.message);
        }
    }
    
    // Query configuration values
    float font_size;
    if (ghostty_config_get(config, &font_size, "font-size", 9)) {
        printf("Font size: %.1f\n", font_size);
    }
    
    ghostty_config_color_s bg_color;
    if (ghostty_config_get(config, &bg_color, "background", 10)) {
        printf("Background color: #%02x%02x%02x\n",
               bg_color.r, bg_color.g, bg_color.b);
    }
    
    // Use config to create app...
    
    // Cleanup
    ghostty_config_free(config);
    
    return 0;
}

See Also

• Core Types - Configuration-related types
• Ghostty Configuration - Available configuration options