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, main vertical stack order, row limits, 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
• Theme path resolution (which file is loaded and which file is repaired on startup) uses the same rules: prefer theme.conf under your Pacsea config directory, then legacy combined pacsea.conf locations where applicable (see startup section below).

Startup: migration and automatic key completion

Before the UI initializes the theme (including optional terminal color queries), Pacsea runs a short config preflight on every launch:

1. Legacy migration — If you still have an older single-file pacsea.conf layout, it is split into theme.conf, settings.conf, and keybinds.conf when needed.
2. Theme completeness — The active theme file is brought up to a full palette:
   • If theme.conf is missing or empty, the full default theme skeleton is written.
   • If the file exists but is missing required color roles, Pacsea appends default lines from the built-in skeleton. Appended blocks are marked with a comment line (# Missing theme keys added automatically) so you can find them in an editor.
   • Repair uses the same path as normal theme loading, so what you see on disk matches what the app reads.
3. Settings refresh — Settings are re-read from disk after migration/theme repair.
4. Settings key ensure — Any missing known keys in settings.conf are appended non-destructively (same idea as before, but after the above steps so values stay consistent).

What this means for you

• You can keep a minimal theme.conf (even a single color line) and Pacsea will still start with a coherent full theme; customize or delete the auto-added lines whenever you like.
• Invalid syntax, duplicate keys, and bad color values are not auto-fixed—the loader still reports those with line numbers (see Validation and diagnostics). Only missing valid keys are filled in.
• --dry-run does not skip this disk repair; it only avoids package-changing commands. Config files may still be updated so the TUI can render.

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, main vertical layout keys like main_pane_order and vertical limits, 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
• If you edit settings.conf in an external editor while Pacsea is running, use Ctrl+R after saving so layout and other cached settings fields are reapplied without restarting

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
• main_pane_order (alias layout_main_pane_order) — top-to-bottom order of the three main vertical bands. Value is a comma-separated list containing each of these tokens exactly once: results, search, package_info.
  • Aliases: middle = search row (search input + Recent + Install panes); details = Package Info band (details, PKGBUILD, comments, etc.).
  • Example (historical default): main_pane_order = results, search, package_info
  • If the line is invalid (wrong tokens, duplicates, etc.), Pacsea logs a warning and keeps the previous order.
• Vertical row limits (terminal row counts per band; Pacsea still shares space with the terminal, then applies these semantic clamps):
  • vertical_min_results, vertical_max_results — results list band
  • vertical_min_middle or vertical_min_search, vertical_max_middle or vertical_max_search — middle row band
  • vertical_min_package_info or vertical_min_details — minimum rows for the Package Info band (there is no separate vertical_max_package_info; the remainder of the terminal height is shared after the other limits)

Behavior:

• app_dry_run_default — true/false; default dry‑run behavior at startup
• use_passwordless_sudo — true/false; legacy opt-in switch for passwordless privileged operations when using sudo. (New installs should prefer auth_mode + privilege_tool below for clearer behavior.)
• privilege_tool — auto | sudo | doas; which privilege escalation tool to use for install/remove/downgrade (default: auto). auto prefers doas when available and falls back to sudo.
• auth_mode — prompt | passwordless_only | interactive; how Pacsea authenticates before privileged operations (default: prompt):
  • prompt: Pacsea captures a password and pipes it to the tool when supported.
  • passwordless_only: only proceeds without prompting when passwordless execution is available.
  • interactive: hands off to the terminal so the privilege tool handles PAM prompts directly (including fingerprint via fprintd, when configured).
• sort_mode — alphabetical | aur_popularity | best_matches
• show_recent_pane, show_install_pane, show_keybinds_footer — pane/footer visibility
• search_startup_mode — insert_mode | normal_mode; which mode the search pane uses on startup (default: 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)

AUR voting (SSH):

• aur_vote_enabled — true/false; enables AUR vote/unvote integration in the UI (default: true)
• aur_vote_ssh_timeout_seconds — SSH connection timeout used for vote and vote-state operations (default: 10)
• aur_vote_ssh_command — SSH binary/command to execute (default: ssh)
• Requires your SSH public key on your AUR account and a valid SSH host setup (the aur-ssh-setup helper in Optional Deps can create/update the required config block)

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.

Custom repositories (repos.conf, Linux)

Pacsea can manage additional pacman sync repositories from a user-owned recipe file and a privileged drop-in:

• Recipe file: $XDG_CONFIG_HOME/pacsea/repos.conf (fallback: ~/.config/pacsea/repos.conf). TOML format with one or more [[repo]] tables (name, enabled, server or mirrorlist fields, optional key_id / sig_level, etc.).
• Applied config: Enabled rows are written to /etc/pacman.d/pacsea-repos.conf. Pacsea also maintains managed markers in /etc/pacman.conf so that drop-in is included—details and safety rules are enforced in the apply plan.
• UI: Options → Repositories merges repos.conf with a live pacman scan, supports Apply (curl mirrorlists, pacman-key, write drop-in, sync), and documents keys in the in-app help (F1). Full workflows: How to use Pacsea — Custom repositories.
• Indexing: Extra pacman -Sl passes used to enrich the package index skip [[repo]] rows with enabled = false, so disabled recipes do not slow or confuse indexing.
• All disabled: Apply is still valid: the managed drop-in becomes a short comment-only file (no enabled sections), instead of failing the plan.

Example and comments: see the shipped config/repos.conf in the Pacsea repository.

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.

Results title bar filters (optional official repos)

Repository chips in the Results title (for example [BlackArch], [EOS], [CachyOS], [Artix]) are session UI toggles: they are not separate keys in settings.conf. They appear only when Pacsea’s official index actually contains packages from that source (e.g. after [blackarch] is enabled and databases are synced—see How to use Pacsea — BlackArch repository). Default visibility for new sessions follows the app’s built-in defaults (optional official filters start enabled). For sort order and persisted behavior keys, see Behavior (sort_mode, etc.) above.

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)

The renderer expects a complete set of palette roles (16 canonical colors). Preferred and legacy alias names in your file all map to those roles. If any role is missing after parsing, Pacsea adds defaults on startup before the first theme load (see Startup: migration and automatic key completion).

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

In addition to the theme repair step in Startup: migration and automatic key completion, Pacsea continues to append any missing known keys to the config files (non‑destructive) where applicable—so settings.conf, keybinds.conf, and the theme file stay aligned with new app versions without wiping your comments or custom values.

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.
• If main_pane_order seems ignored, check the log for a parse warning (invalid lines keep the previous order). After fixing the file, press Ctrl+R or restart.
• If vertical min/max combinations cannot be satisfied in a very small terminal, Pacsea normalizes limits (max bumped up to at least min, etc.); extreme values still need a reasonable terminal size to look good.
• 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.