Configuration

Configure Pacsea's theme, layout, behavior, and keybindings through three separate configuration files. This page documents locations, precedence, live‑reload, diagnostics, keys, and examples.

For usage examples and workflows, see How to use Pacsea. For keyboard shortcuts, see Keyboard Shortcuts.

Locations and precedence

• Primary config directory: $XDG_CONFIG_HOME/pacsea/ (fallback: ~/.config/pacsea/)
• Three config files:
  • settings.conf — app behavior (layout, defaults, visibility, scans, news, mirrors, etc.)
  • theme.conf — colors and styling
  • keybinds.conf — keyboard shortcuts for all actions
• Development preference: repo config/ files are preferred while running with cargo run
• On first run, Pacsea creates all three config files and appends any missing known keys non‑destructively

Editing config files

When you open a config file from the TUI (Config menu → choose settings, theme, or keybinds to edit), Pacsea uses your VISUAL or EDITOR environment variable to open it in your preferred editor. If both are set, VISUAL takes precedence. This applies to settings.conf, theme.conf, and keybinds.conf.

Format

• Lines: key = value
• Comments: lines starting with # or //
• Colors: #RRGGBB or R,G,B (0‑255), e.g. text_primary = 205,214,244
• Modifiers for keybindings: SUPER, CTRL, SHIFT, ALT

Live reload

Configuration reload (Ctrl+R):

• Press Ctrl+R to explicitly reload configuration at runtime
• Reloads theme.conf (colors and styling are cached in memory)
• Reloads settings.conf (including locale, installed_packages_mode, etc.)
• A toast message confirms when the configuration is reloaded successfully
• If installed_packages_mode changed, the cache is automatically refreshed and results update without restart

Keybinds (keybinds.conf):

• Keybinds are not cached — they're read fresh from disk every time they're accessed
• Changes to keybinds.conf take effect automatically on the next access
• No explicit reload needed — they're always up-to-date

Validation and diagnostics

The loader reports precise issues with line numbers and suggestions:

• Unknown keys with did‑you‑mean hints
• Missing required theme keys (preferred names listed)
• Missing = or missing key before =
• Duplicate keys
• Invalid color values

Application settings (settings.conf)

Layout:

• layout_left_pct, layout_center_pct, layout_right_pct — middle row pane widths; must sum to 100

Behavior:

• app_dry_run_default — true/false; default dry‑run behavior at startup
• use_passwordless_sudo — true/false; when true, Pacsea uses passwordless sudo for install, update, and downgrade (no password prompt) if your system is configured for it (default: false). You must set this in settings for Pacsea to skip the password prompt; configuring sudoers alone is not enough. Remove operations always require a password for safety. See How to use Pacsea and Troubleshooting for sudoers setup.
• sort_mode — alphabetical | aur_popularity | best_matches
• show_recent_pane, show_install_pane, show_keybinds_footer — pane/footer visibility
• search_startup_mode — true/false; when true, starts in normal mode (default: false, starts in insert mode)
• fuzzy_search — true/false; enable fuzzy search mode by default on startup (default: false)
• updates_refresh_interval — refresh interval in seconds for checkupdates and AUR helper checks (default: 30)
• app_start_mode — package | news; choose startup mode (default: package). Set to news to start directly in News mode. Alias start_in_news is accepted for backward compatibility.

Preflight modal:

• skip_preflight — true/false; when true, bypasses the Preflight confirmation modal and executes install/remove/downgrade actions immediately (default: false)
• For detailed information about the Preflight modal and how to use it, see How to use Pacsea

Clipboard:

• clipboard_suffix — text appended when copying PKGBUILD from the viewer

Mirrors (for system updates):

• selected_countries — comma-separated list of countries (e.g., "Switzerland, Germany, Austria") or "Worldwide"
• mirror_count — number of HTTPS mirrors to consider when updating (default: 20)

Security scans (default scan configuration):

• scan_do_clamav — true/false; enable ClamAV scanning
• scan_do_trivy — true/false; enable Trivy scanning
• scan_do_semgrep — true/false; enable Semgrep scanning
• scan_do_shellcheck — true/false; enable ShellCheck scanning
• scan_do_virustotal — true/false; enable VirusTotal scanning
• scan_do_custom — true/false; enable custom pattern scanning
• scan_do_sleuth — true/false; enable aur-sleuth scanning

News:

• app_start_mode — package | news; choose startup mode (default: package). Set to news to start directly in News mode. Alias start_in_news is accepted for backward compatibility.
• news_read_symbol — symbol for read items (default: ✓)
• news_unread_symbol — symbol for unread items (default: ∘)
• news_filter_show_arch_news — true/false; show Arch news items in News mode (default: true)
• news_filter_show_advisories — true/false; show security advisories in News mode (default: true)
• news_filter_show_updates — true/false; show package updates in News mode (default: true)
• news_filter_show_aur_comments — true/false; show AUR comments in News mode (default: true)
• news_filter_installed_only — true/false; when true, advisories and updates are scoped to installed packages (default: true)
• news_max_age_days — maximum age in days for news items; set empty/omitted for no limit (default: unlimited). Previously defaulted to 30 days.

Announcements:

• get_announcement — true/false; enable fetching remote announcements from GitHub Gist at startup (default: true)
  • When true, Pacsea fetches remote announcements from the configured GitHub Gist URL
  • Version-specific announcements always show regardless of this setting
  • Remote announcements support version range filtering and expiration dates
  • See How to use Pacsea for details

VirusTotal:

• virustotal_api_key — API key for VirusTotal scans (optional, can also be configured via Optional Deps modal)

Terminal:

• preferred_terminal — preferred terminal emulator binary (optional, e.g., alacritty, kitty)
• For terminal requirements and installation, see Installation

Package selection marker:

• package_marker — visual marker style: full_line | front | end (default: front)

Language / Locale:

• locale — locale code for translations (e.g., en-US, de-DE). Leave empty to auto-detect from system locale. Available locales: en-US, de-DE, hu-HU (more coming soon)

Installed packages filter mode:

• installed_packages_mode — filter mode for installed packages display. Allowed values: leaf | all
  • leaf (default): Show only leaf packages (explicitly installed, nothing depends on them). This is safer for removal as it avoids breaking dependencies.
  • all: Show all explicitly installed packages (including those other packages depend on, e.g., git, python, wget).
  • Changing this setting and reloading config (Ctrl+R) automatically refreshes the cache and updates results without restart.

Sorting persistence

When you change sorting from the UI, Pacsea persists sort_mode back to settings.conf, preserving comments.

Pane visibility persistence

Toggling the Recent/Install panes or the Keybinds footer from the UI persists show_recent_pane, show_install_pane, show_keybinds_footer to settings.conf.

Keybindings (keybinds.conf)

For a complete reference of all keyboard shortcuts and their usage, see the Keyboard Shortcuts wiki page.

Format examples:

keybind_help = F1
keybind_reload_theme = CTRL+R
keybind_exit = CTRL+Q
keybind_show_pkgbuild = CTRL+X
keybind_comments_toggle = CTRL+T

Defaults (comprehensive):

# GLOBAL — App
keybind_help = F1
# Alternative help shortcut
keybind_help = ?
keybind_reload_theme = CTRL+R
keybind_exit = CTRL+Q
keybind_show_pkgbuild = CTRL+X
keybind_comments_toggle = CTRL+T

# GLOBAL — Pane switching
keybind_pane_left = Left
keybind_pane_right = Right
keybind_pane_next = Tab

# GLOBAL — Sorting
keybind_change_sort = BackTab

# SEARCH — Navigation
keybind_search_move_up = Up
keybind_search_move_down = Down
keybind_search_page_up = PgUp
keybind_search_page_down = PgDn

# SEARCH — Actions
keybind_search_add = Space
keybind_search_install = Enter

# SEARCH — Focus/Edit
keybind_search_focus_left = Left
keybind_search_focus_right = Right
keybind_search_backspace = Backspace

# SEARCH — Normal Mode (Focused Search Window)
keybind_search_normal_toggle = Esc
keybind_search_normal_insert = i
keybind_search_normal_select_left = h
keybind_search_normal_select_right = l
keybind_search_normal_delete = d
keybind_search_normal_clear = Shift+Del

# SEARCH — Normal Mode (Menus)
keybind_toggle_config = Shift+C
keybind_toggle_options = Shift+O
keybind_toggle_panels = Shift+P

# SEARCH — Normal Mode (Other)
keybind_search_normal_open_status = Shift+S
keybind_search_normal_import = Shift+I
keybind_search_normal_export = Shift+E

# RECENT — Navigation
keybind_recent_move_up = k
keybind_recent_move_down = j

# RECENT — Actions
keybind_recent_use = Enter
keybind_recent_add = Space
keybind_recent_remove = d
keybind_recent_remove = Del
keybind_recent_clear = Shift+Del

# RECENT — Find/Focus
keybind_recent_find = /
keybind_recent_to_search = Esc
keybind_recent_focus_right = Right

# INSTALL — Navigation
keybind_install_move_up = k
keybind_install_move_down = j

# INSTALL — Actions
keybind_install_confirm = Enter
keybind_install_remove = Del
keybind_install_remove = d
keybind_install_clear = Shift+Del

# INSTALL — Find/Focus
keybind_install_find = /
keybind_install_to_search = Esc
keybind_install_focus_left = Left

# NEWS — Actions
keybind_news_mark_read = r
keybind_news_mark_all_read = CTRL+R

Recognized aliases (compatibility):

• keybind_help_overlay, keybind_reload, keybind_quit, keybind_pkgbuild, keybind_toggle_pkgbuild, keybind_sort, keybind_next_pane, keybind_switch_pane
• keybind_show_comments, keybind_toggle_comments (for keybind_comments_toggle)

Theme keys (theme.conf)

Preferred names (with legacy aliases in parentheses):

• Background: background_base (base, background), background_mantle (mantle), background_crust (crust)
• Surfaces: surface_level1 (surface1, surface_1), surface_level2 (surface2, surface_2)
• Overlays: overlay_primary (overlay1, border_primary), overlay_secondary (overlay2, border_secondary)
• Text: text_primary (text), text_secondary (subtext0), text_tertiary (subtext1)
• Accents/Semantics: accent_interactive (sapphire, accent_info), accent_heading (mauve, accent_primary), accent_emphasis (lavender, accent_border), semantic_success (green), semantic_warning (yellow), semantic_error (red)

Example theme block (Catppuccin Mocha):

background_base = #1e1e2e
background_mantle = #181825
background_crust = #11111b
surface_level1 = #45475a
surface_level2 = #585b70
overlay_primary = #7f849c
overlay_secondary = #9399b2
text_primary = #cdd6f4
text_secondary = 166,173,200
text_tertiary = #bac2de
accent_interactive = #74c7ec
accent_heading = #cba6f7
accent_emphasis = #b4befe
semantic_success = #a6e3a1
semantic_warning = #f9e2af
semantic_error   = #f38ba8

The theme.conf file includes commented examples for alternative themes (Light, Tokyo Night, Nord, Dracula) that you can uncomment and use.

Persistence and auto‑append

On startup, Pacsea appends any missing known keys to all three config files (non‑destructive) so you always have a complete, self‑documenting config.

Troubleshooting configuration

• If you see an alert about unknown/missing/duplicate keys, check the reported line numbers and fix the entries.
• If pane widths don't add up to 100, Pacsea falls back to defaults at runtime.
• Colors must be #RRGGBB or R,G,B (0‑255). Invalid values are reported.
• Config files are separate: settings.conf for behavior, theme.conf for colors, keybinds.conf for shortcuts.