Tuicr Config File Location: Where to Find and Edit Your Settings

Tuicr stores its configuration file at ~/.config/tuicr/config.toml on Unix-like systems and %APPDATA%\tuicr\config.toml on Windows, following the XDG Base Directory specification.

Tuicr is a terminal-based IRC client written in Rust. Understanding the Tuicr config file location is essential for customizing themes, keybindings, and connection settings. The application determines the correct path based on your operating system's environment variables and standard directory conventions.

Default Config File Paths by Platform

Tuicr implements platform-specific logic in src/config/mod.rs to resolve configuration directories. The implementation respects the XDG Base Directory specification on Unix-like systems and standard Windows conventions.

Linux and macOS

On Unix-like systems, Tuicr checks the XDG_CONFIG_HOME environment variable first. If this variable is unset, the application falls back to the standard ~/.config directory.

• Primary location: $XDG_CONFIG_HOME/tuicr/config.toml
• Fallback location: ~/.config/tuicr/config.toml

The resolution logic uses dirs::home_dir() as the final fallback mechanism when neither environment variable is available, ensuring the application always has a valid path to attempt loading.

Windows

On Windows, Tuicr relies on the %APPDATA% environment variable to locate the roaming application data folder.

• Environment-based path: %APPDATA%\tuicr\config.toml
• Typical resolved path: C:\Users\<Username>\AppData\Roaming\tuicr\config.toml

The application uses std::env::var("APPDATA") to retrieve this location during the startup sequence.

Configuration Loading Implementation

The configuration loading mechanism resides in src/config/mod.rs. This module handles path resolution, TOML parsing, and merging user settings with built-in defaults.

When Tuicr initializes, it executes the following platform detection logic:

// Inside src/config/mod.rs
let config_path = if cfg!(windows) {
    std::env::var("APPDATA")
        .map(|p| Path::new(&p).join("tuicr/config.toml"))
} else {
    std::env::var("XDG_CONFIG_HOME")
        .map(|p| Path::new(&p).join("tuicr/config.toml"))
        .unwrap_or_else(|_| dirs::home_dir().unwrap().join(".config/tuicr/config.toml"))
};

let config = Config::load_from_path(&config_path)?;

The Config::load_from_path function reads the TOML file, applies defaults for any missing fields, and returns a structured configuration object. If the file does not exist, the application continues using hardcoded default values without creating the file.

Creating and Editing the Config File

Tuicr does not automatically create the configuration directory or file. To customize settings, you must create the path manually:

# Create the config directory on Linux/macOS

mkdir -p ~/.config/tuicr

# Create the config file

touch ~/.config/tuicr/config.toml

Add valid TOML configuration options to customize the application behavior:

# ~/.config/tuicr/config.toml

theme = "tokyo-night"
wrap = true
show_file_list = false

Available settings include theme selection (color schemes), wrap (text wrapping in message buffers), and show_file_list (UI panel visibility).

Overriding Config via Command Line

Tuicr supports temporary configuration overrides through command-line arguments processed in src/main.rs. These overrides take precedence over file-based settings without modifying the config file.

To override the theme for a single session:

tuicr --theme tokyo-night

The CLI parser processes these flags before calling the configuration loader, ensuring command-line values replace any settings loaded from config.toml.

Programmatic Config Access

When extending Tuicr or building related tools, you can access the configuration resolution logic through the public API:

use tuicr::config::Config;

let cfg = Config::load()?;                // Loads from the default location
println!("Config loaded from: {}", cfg.path.display());

The Config::load() method automatically resolves the platform-specific path using the same environment variable checks implemented in the main application entry point.

Summary

• Tuicr config file location follows XDG standards: ~/.config/tuicr/config.toml on Unix and %APPDATA%\tuicr\config.toml on Windows.
• The loading logic in src/config/mod.rs checks XDG_CONFIG_HOME and APPDATA environment variables before falling back to default paths.
• Configuration uses TOML format with support for themes, text wrapping, and UI preferences.
• Command-line flags override file-based settings for temporary customization.
• The application uses compiled-in defaults if no config file exists; it does not create the file automatically.

Frequently Asked Questions

Where does Tuicr store its config on macOS?

Tuicr stores its configuration at ~/.config/tuicr/config.toml on macOS by default. If you have set a custom XDG_CONFIG_HOME environment variable, Tuicr will use $XDG_CONFIG_HOME/tuicr/config.toml instead. This follows the same XDG Base Directory convention used on Linux systems rather than macOS's native ~/Library/Preferences path.

Can I change the Tuicr config file location?

Tuicr does not support custom config paths via command-line arguments. The application strictly uses the XDG Base Directory specification on Unix or %APPDATA% on Windows as implemented in src/config/mod.rs. To use a different location, set the XDG_CONFIG_HOME environment variable before launching Tuicr, or create a symlink from the default location to your preferred directory.

What format does the Tuicr config file use?

Tuicr uses TOML (Tom's Obvious, Minimal Language) format for its configuration files. The file must contain valid TOML syntax with key-value pairs for settings such as theme, wrap, and show_file_list. Syntax errors in the config file will cause the application to fail during startup with a parsing error generated by the TOML deserializer in src/config/mod.rs.

Does Tuicr create the config file automatically?

No, Tuicr does not automatically create the configuration file or directory on first run. If the file is missing, the application uses compiled-in default values and continues normally. You must manually create the tuicr directory and config.toml file if you wish to persist custom settings beyond the defaults.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}