Configuration File Format

Configuration File Format & Directory Structure

Mastui stores all settings, credentials, timeline caches, keymaps, and custom themes under standard user configuration directories following the XDG Base Directory specification.

---

📁 Directory Structure

On Linux and macOS, the root configuration directory is ~/.config/mastui/. On Windows, it is %USERPROFILE%\.config\mastui\.

~/.config/mastui/
├── custom-themes.json              # Custom theme definitions available to all profiles
├── profiles/
│   ├── default/
│   │   ├── .env                    # Credentials and user preferences (permissions: 0600)
│   │   ├── keymap.json             # Keybinding overrides for this profile
│   │   ├── cache.db                # SQLite database caching timelines and accounts
│   │   └── image_cache/            # Cached media attachments and avatars
│   │       ├── 3a9f0...b12.jpg
│   │       └── c4d81...e59.png
│   └── work_account/
│       ├── .env
│       ├── keymap.json
│       ├── cache.db
│       └── image_cache/

---

⚙️ The Profile Configuration File (.env)

Each profile directory contains a .env file that stores instance credentials and UI preferences. Because this file contains OAuth secret tokens, Mastui automatically enforces POSIX file permission 0600 (read/write only by owner).

Complete .env Reference

# ==============================================================================
# MASTODON INSTANCE & OAUTH CREDENTIALS
# ==============================================================================
MASTODON_HOST=mastodon.social
MASTODON_CLIENT_ID=abc123clientidexample
MASTODON_CLIENT_SECRET=xyz789clientsecretexample
MASTODON_ACCESS_TOKEN=987654accesstokenexample

# ==============================================================================
# THEME & APPEARANCE
# ==============================================================================
# Active theme name (e.g. textual-dark, textual-light, tokyo-night, retro-green, dracula, nord)
THEME=tokyo-night

# Default themes used when toggling with 'd'
PREFERRED_DARK_THEME=tokyo-night
PREFERRED_LIGHT_THEME=textual-light

# ==============================================================================
# TIMELINE VISIBILITY
# ==============================================================================
HOME_TIMELINE_ENABLED=on
LOCAL_TIMELINE_ENABLED=off
NOTIFICATIONS_TIMELINE_ENABLED=on
FEDERATED_TIMELINE_ENABLED=on
DIRECT_TIMELINE_ENABLED=on
FORCE_SINGLE_COLUMN=off

# ==============================================================================
# AUTO-REFRESH SETTINGS (interval in minutes, supports decimals e.g. 0.5)
# ==============================================================================
HOME_AUTO_REFRESH=on
HOME_AUTO_REFRESH_INTERVAL=2.0

LOCAL_AUTO_REFRESH=on
LOCAL_AUTO_REFRESH_INTERVAL=2.0

NOTIFICATIONS_AUTO_REFRESH=on
NOTIFICATIONS_AUTO_REFRESH_INTERVAL=10.0

FEDERATED_AUTO_REFRESH=on
FEDERATED_AUTO_REFRESH_INTERVAL=2.0

# ==============================================================================
# IMAGE & MEDIA SETTINGS
# ==============================================================================
IMAGE_SUPPORT=on
# Renderer options: "ansi" (Halfcell), "tgp" (Kitty graphics), "sixel", or "auto"
IMAGE_RENDERER=ansi
# Automatically purge cached images when exiting Mastui
AUTO_PRUNE_CACHE=on

# ==============================================================================
# NOTIFICATION TOAST POPUPS
# ==============================================================================
NOTIFICATIONS_POPUPS_MENTIONS=off
NOTIFICATIONS_POPUPS_FOLLOWS=off
NOTIFICATIONS_POPUPS_REBLOGS=off
NOTIFICATIONS_POPUPS_FAVOURITES=off

# ==============================================================================
# COMPOSER LANGUAGE PREFERENCES
# Comma-separated list of ISO language codes in preferred order
# ==============================================================================
POST_LANGUAGES=en,da,fr,de,ja,ko,es,zh

---

🗄️ SQLite Cache Database (cache.db)

Mastui caches timeline items, author metadata, and relations inside a local SQLite database (cache.db) in each profile:

• Instant Launch: Feeds are rendered immediately on application launch from the local cache before network requests complete.
• Offline Reading: You can launch Mastui and browse your previously loaded feeds without an active internet connection.
• Bandwidth Efficiency: Minimizes duplicate API fetches and respects Mastodon rate limits.

---

🧹 Image Cache & Pruning

When IMAGE_SUPPORT=on is enabled, downloaded media attachments and avatars are stored in image_cache/ using SHA-256 hashed filenames.

• Auto-Prune: When AUTO_PRUNE_CACHE=on is configured, Mastui automatically clears downloaded media files upon normal exit to prevent unbounded disk usage.
• Manual Pruning: You can manually purge the cache at any time via Options (o) -> Image Settings -> Prune Cache Now.

---

✏️ Safe Manual Editing Guidelines

1. Quit Mastui before editing: Make sure Mastui is closed before modifying .env or keymap.json directly, as the application writes changes on exit.
2. Preserve exact boolean strings: Use lowercase "on" or "off" for toggle settings.
3. Keep numeric values valid: Intervals are specified in positive floats or integers representing minutes (e.g., 2 or 0.5).
4. File Permissions: Ensure file permissions remain 0600 on Linux/macOS:

   chmod 600 ~/.config/mastui/profiles/*/.env