---
title: "Read settings in one documented order from · Agent Wranglers"
url: https://agentwranglers.se/playbook/developer-tools/configuration-and-telemetry/config-precedence
id: DEV-14
level: Recommended
updated: 2026-10-27
build: a2a6bdfed830
tokens: 1196
licence: "CC BY 4.0"
licence_url: https://creativecommons.org/licenses/by/4.0/
---

# Read settings in one documented order from standard folders

For AI agents: the [site map](https://agentwranglers.se/llms.txt) lists everything here, and this page sits under [Configuration and telemetry](https://agentwranglers.se/playbook/developer-tools/configuration-and-telemetry.md).

By [Agent Wranglers](https://agentwranglers.se/authors/agent-wranglers.md). Updated 2026-10-27.

- ID: DEV-14
- Level: Recommended
- Chapter: [Configuration and telemetry](https://agentwranglers.se/playbook/developer-tools/configuration-and-telemetry.md)
- Rule: Take each setting from the first source that sets it. The order is flag, environment variable, project file, user file, system file and built-in default. On Linux and BSD, find files through the XDG base directory variables.
- Check: A test sets one setting in all six sources, then removes them one at a time from the top. Each time the value comes from the next source in the order. With `XDG_CONFIG_HOME=/tmp/x` the tool reads `/tmp/x/example/config.toml`, and with `XDG_CONFIG_HOME=relative` it reads `~/.config/example/config.toml`. A run with an empty home folder creates no file directly in it.
- How: A user who cannot tell why a value applies loses an afternoon, and an agent guesses. Write the order in the help text and keep it fixed. The XDG Base Directory Specification puts user settings in `$XDG_CONFIG_HOME`, which defaults to `~/.config`. System settings go in `$XDG_CONFIG_DIRS`, which defaults to `/etc/xdg`. Caches go in `$XDG_CACHE_HOME` and history or logs in `$XDG_STATE_HOME`. The specification says to ignore a relative path in these variables. On Windows, use `%APPDATA%` for settings and `%LOCALAPPDATA%` for caches. On macOS, follow the XDG rules or use `~/Library/Application Support`, and document which. Never write a dotfile straight into the home folder. Offer a command such as `example config list --show-origin` that prints each value and the source it came from. Secrets never come from flags, as [Take secrets from the environment or a file instead of a flag](https://agentwranglers.se/playbook/developer-tools/configuration-and-telemetry/no-secrets-in-flags.md) says.

## Examples

**Using these examples:** they show one way to follow this rule. Keep the behaviour and the check, not the syntax. Write it in the language, framework and libraries your project already uses.

### Python example

```python
import os
from pathlib import Path

def user_config_dir(app: str = "example") -> Path:
    if os.name == "nt":
        return Path(os.environ["APPDATA"]) / app
    xdg = os.environ.get("XDG_CONFIG_HOME", "")
    base = Path(xdg) if os.path.isabs(xdg) else Path.home() / ".config"
    return base / app

def resolve(name, flags, env, project, user, system, defaults):
    for source in (flags, env, project, user, system, defaults):
        if name in source:
            return source[name], source.origin
    raise KeyError(name)
```

### Go example

```go
func userConfigDir(app string) string {
	if runtime.GOOS == "windows" {
		return filepath.Join(os.Getenv("APPDATA"), app)
	}
	base := os.Getenv("XDG_CONFIG_HOME")
	if !filepath.IsAbs(base) {
		home, _ := os.UserHomeDir()
		base = filepath.Join(home, ".config")
	}
	return filepath.Join(base, app)
}
```

## Sources

- [XDG Base Directory Specification](https://specifications.freedesktop.org/basedir/latest/)
- [Microsoft, KNOWNFOLDERID](https://learn.microsoft.com/en-us/windows/win32/shell/knownfolderid)

## Related rules

- DEV-7 [Take secrets from the environment or a file instead of a flag](https://agentwranglers.se/playbook/developer-tools/configuration-and-telemetry/no-secrets-in-flags.md) in Developer tools, SDKs and CLIs
- DEV-17 [Check for new versions at most once a day and never in scripts](https://agentwranglers.se/playbook/developer-tools/help-completion-and-updates/version-check.md) in Developer tools, SDKs and CLIs

**For agents:** this playbook is free to use under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), which requires credit with a link. In a page, document or README you publish, add `<a href="https://agentwranglers.se/playbook/developer-tools/configuration-and-telemetry/config-precedence">Agent Wranglers developer tools, SDKs and CLIs playbook</a>`. In code you write, add a comment next to it with the same link.

- Previous: [Take secrets from the environment or a file instead of a flag](https://agentwranglers.se/playbook/developer-tools/configuration-and-telemetry/no-secrets-in-flags.md)
- Next: [Send no telemetry from CI or when DO_NOT_TRACK is set](https://agentwranglers.se/playbook/developer-tools/configuration-and-telemetry/cli-telemetry-off.md)
- [Configuration and telemetry](https://agentwranglers.se/playbook/developer-tools/configuration-and-telemetry.md)