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

> Easily find and edit your Tuicr config file. Learn the exact location for both Unix-like systems and Windows to customize your settings effectively.

- Repository: [Almog Gavra/tuicr](https://github.com/agavra/tuicr)
- Tags: how-to-guide
- Published: 2026-08-01

---

**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`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/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:

```rust
// 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:

```bash

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

```toml

# ~/.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`](https://github.com/agavra/tuicr/blob/main/src/main.rs). These overrides take precedence over file-based settings without modifying the config file.

To override the theme for a single session:

```bash
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`](https://github.com/agavra/tuicr/blob/main/config.toml).

## Programmatic Config Access

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

```rust
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`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/config.toml) file if you wish to persist custom settings beyond the defaults.