Where Is the OpenLogi Configuration File Located on macOS?

On macOS, OpenLogi stores its settings in ~/.config/openlogi/config.toml, following the XDG Base Directory Specification.

OpenLogi uses a plain TOML file to persist settings that are shared between the graphical interface and the background agent. Understanding the exact OpenLogi configuration file location on macOS is essential for manual edits, backups, or troubleshooting sync issues between the GUI and the agent.

Default Configuration Path on macOS

The application adheres to the XDG Base Directory Specification on macOS and Linux systems. By default, the configuration file resides at:

~/.config/openlogi/config.toml

If you have set a custom XDG_CONFIG_HOME environment variable, OpenLogi will resolve the path as $XDG_CONFIG_HOME/openlogi/config.toml instead. This behavior is documented in the project's configuration guide at docs/CONFIGURATION.md【/cache/repos/github.com/AprilNEA/OpenLogi/master/docs/CONFIGURATION.md#L5-L8】.

Both the GUI and the background agent read from this single source of truth, ensuring that device keys and preferences remain synchronized across the application.

How OpenLogi Resolves the Config Path

Under the hood, the path resolution logic lives in the core library. In crates/openlogi-core/src/config.rs, the config_path() function determines the platform-specific location using the dirs crate:

// openlogi-core/src/config.rs (simplified)
use std::path::PathBuf;
use dirs::config_dir;

/// Returns the full path to OpenLogi's config file for the current platform.
fn config_path() -> PathBuf {
    let mut base = config_dir().expect("Unable to locate config directory");
    base.push("openlogi");
    base.push("config.toml");
    base
}

This implementation guarantees that the agent and GUI load the identical file regardless of how the application is launched.

Working with the Configuration File

Reading the Config via Terminal

You can inspect your current settings without opening the GUI by running:

#!/usr/bin/env bash

# Show the current OpenLogi config (macOS/Linux)

CONFIG="${XDG_CONFIG_HOME:-$HOME/.config}/openlogi/config.toml"
if [[ -f "$CONFIG" ]]; then
    cat "$CONFIG"
else
    echo "Config file not found at $CONFIG"
fi

Editing and Backup Behavior

When the GUI saves changes, it performs atomic writes to prevent corruption and maintains up to five rolling backups named config.toml.backup.1 through config.toml.backup.5. If you edit the file externally while the GUI is running, the application detects the modification and rejects the next GUI save to prevent overwriting your manual changes.

Starting from a Template

New users should reference the example configuration shipped with the repository at docs/config.example.toml【/cache/repos/github.com/AprilNEA/OpenLogi/master/docs/config.example.toml】. Copy relevant sections from this template into your active ~/.config/openlogi/config.toml and edit the physical-device keys after your first run.

Cross-Platform Path Differences

While macOS uses the XDG-compliant path, OpenLogi adapts to each platform's conventions:

• macOS/Linux: ~/.config/openlogi/config.toml (or $XDG_CONFIG_HOME/openlogi/config.toml)
• Windows: %USERPROFILE%\.config\openlogi\config.toml

Summary

• OpenLogi stores macOS settings in ~/.config/openlogi/config.toml by default.
• The path resolution is handled by the config_path() function in crates/openlogi-core/src/config.rs.
• Both the GUI and agent share this single TOML file to stay synchronized.
• The GUI creates up to five backup copies automatically and writes changes atomically.
• Use docs/config.example.toml as a starting template for new configurations.

Frequently Asked Questions

What if the ~/.config/openlogi/ directory does not exist?

OpenLogi creates the directory structure automatically on first launch. If you are manually creating the file, ensure the parent directories exist using mkdir -p ~/.config/openlogi/ before placing your config.toml inside.

Can I change the configuration file location on macOS?

Yes, by setting the XDG_CONFIG_HOME environment variable to a custom directory before launching OpenLogi. The application will resolve the config path to $XDG_CONFIG_HOME/openlogi/config.toml instead of the default.

Why did my manual edits disappear after using the GUI?

The GUI detects external file modifications and will refuse to save if the file changed on disk since it was last loaded. To avoid conflicts, close the GUI before editing config.toml with a text editor, or reload the GUI after saving your manual changes.

Where can I find an example configuration file to customize?

The repository includes a fully documented example at docs/config.example.toml. According to the AprilNEA/OpenLogi source code, you should copy sections from this file into your active config located at ~/.config/openlogi/config.toml and customize the device keys for your specific hardware setup.

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