Configuration Reference

Tildr stores its user configuration in TOML format at ~/.config/tildr/config.toml.

The configuration file is created by tildr init and is never written automatically by any other command. If the file does not exist, all defaults are applied silently at runtime.

Configuration File Location

Tildr uses the XDG Base Directory specification when available. On systems where XDG is not configured, it falls back to $HOME/.config/tildr/config.toml.

Full Configuration Example

[core]
repo = "~/.dotfiles"
search_threshold = 15
color = true

[git]
available = true
# enable = true          # optional: explicitly enable/disable Git operations
auto_commit = true

[crypto]
mode = "symmetric"
# gpg_key = ""           # only used when mode = "asymmetric"

[core] Section

Core settings control the repository path, interactive behavior, and output formatting.

core.repo

The repository path must satisfy these constraints:

• Must be inside $HOME
• Cannot be $HOME itself
• Must be on the same filesystem as $HOME (no cross-disk layouts)

# Good
repo = "~/.dotfiles"
repo = "~/.config/dotfiles"
repo = "/home/user/.dotfiles"

# Bad — outside $HOME
repo = "/opt/dotfiles"

# Bad — is $HOME itself
repo = "~"

core.search_threshold

When the number of managed files exceeds this threshold, interactive pickers (used by tildr add, tildr cat, tildr edit, tildr unlink, tildr restore, tildr del, tildr mv) display a search input before the file list. Type a fragment to filter by fuzzy match, or press Enter with empty input to see the full list.

# Show search immediately for any number of files
search_threshold = 0

# Only show search for 50+ files
search_threshold = 50

core.color

Controls whether Tildr uses ANSI color codes in terminal output.

# Disable colors in output
color = false

Colors are also disabled when the NO_COLOR environment variable is set:

NO_COLOR=1 tildr status

[git] Section

Git settings control version control integration, automatic commits, and the ability to disable Git operations entirely.

git.available

This field is written automatically by tildr init based on whether Git was found in PATH at initialization time. You should not edit this field manually.

git.enable

This is an optional override that allows you to disable Git operations without uninstalling Git. When set to false:

• tildr sync will not work
• tildr git status will not work
• Auto-commit after add, restore, del, mv, and secret will be skipped

[git]
# Explicitly disable all Git operations
enable = false

When unset (the default), Git operations are enabled if git.available = true.

git.auto_commit

When true, Tildr automatically commits changes after these commands:

Commands that do not trigger auto-commit: tildr apply, tildr unlink, tildr status, tildr list, tildr git, tildr sync, tildr doctor.

[git]
# Disable automatic commits
auto_commit = false

Git Operations Logic

Tildr determines whether Git operations are enabled using this logic:

operations_enabled  = git.available AND git.enable != false
auto_commit_enabled = git.auto_commit AND operations_enabled

[crypto] Section

Encryption settings control how tildr secret encrypts and decrypts sensitive files.

crypto.mode

Tildr supports two GPG encryption modes:

Symmetric (default):

• No key pair required — only a passphrase
• GPG prompts for the passphrase via the system pinentry on first use
• The same passphrase must be used to decrypt on any machine
• Simpler setup, suitable for single-user environments

Asymmetric:

• Uses an existing GPG key pair — no separate passphrase to remember
• crypto.gpg_key must be set to the recipient key ID or email
• Decryption uses the private key silently (subject to GPG Agent caching)
• Preferred when you already manage GPG keys and want a seamless new-machine setup

[crypto]
# Symmetric mode (default)
mode = "symmetric"

# Asymmetric mode
mode = "asymmetric"
gpg_key = "[email protected]"

crypto.gpg_key

Only used when crypto.mode = "asymmetric". Specifies the GPG key ID or email address used for encryption.

If left empty, Tildr will:

1. List all available GPG secret keys
2. If only one key exists, use it automatically
3. If multiple keys exist, show an interactive selection prompt
4. Save the chosen key to config.toml for future use

[crypto]
# By key ID
gpg_key = "ABC123DEF456"

# By email
gpg_key = "[email protected]"

Configuration Loading Behavior

1. Tildr loads config.toml on startup
2. If the file does not exist, all defaults are applied silently
3. Missing fields within an existing file fall back to their defaults
4. The config is never written automatically except by tildr init
5. tildr secret may update crypto.gpg_key after interactive key selection

Environment Variables

Tildr respects the following environment variable:

Viewing Current Configuration

Use tildr cat config to display the current configuration file:

tildr cat config

This opens the config file in your configured editor, or prints it to stdout.