Skip to content

How to use Pacsea

Jump to bottom
Firstp1ck edited this page Apr 17, 2026 · 23 revisions

A practical, step‑by‑step guide for getting productive with Pacsea’s keyboard‑first TUI on Arch Linux.

Quick start workflow

  1. Start typing to search. With an empty query, Pacsea shows the official index (after the first refresh).
  2. Use ↑/↓ or PageUp/PageDown to navigate results.
  3. Press Space to add the selected package to the Install list.
  4. Press Enter to install the selected (in Results) or all queued (in Install).
  5. Use the Recent pane to reuse prior queries; Enter loads, Space quickly adds the first match.

Tips:

  • Click the URL in Package Info to open it in your browser.
  • Click “Show PKGBUILD” to open a side‑by‑side PKGBUILD preview; use Esc to close.

Configuration files (quick reference)

  • Where: ~/.config/pacsea/ by default, or $XDG_CONFIG_HOME/pacsea/. Three files: settings.conf (behavior), theme.conf (colors), keybinds.conf (shortcuts). Full reference: Configuration.
  • Every launch: Pacsea runs migration and repair before the UI paints: old single-file pacsea.conf setups are split when needed; missing theme colors are filled from defaults (empty theme.conf gets the full default theme); missing settings keys are appended. You can start from a tiny theme.conf and still get a complete palette—see Startup: migration and automatic key completion.
  • While the app is open: theme.conf changes need Ctrl+R to reload. settings.conf and keybinds.conf are read from disk when used—see Live reload.

Main vertical layout (results, search, details)

Pacsea draws the three stacked main bands (results list, middle row with search + Recent + Install, and Package Info / details) in an order you choose, and clamps how many terminal rows each band may use.

  • Configure: In settings.conf, set main_pane_order to a comma-separated permutation of results, search, and package_info (you can use aliases middle instead of search and details instead of package_info). See Configuration — Layout for defaults, aliases, and validation rules.
  • Heights: Use vertical_min_* / vertical_max_* keys for the results and middle rows, and vertical_min_package_info (or vertical_min_details) for the details band. Keys apply to semantic bands, not fixed “top/middle/bottom” slots—so reordering the stack still tunes the correct pane.
  • Apply while running: After editing layout keys in an external editor, press Ctrl+R so Pacsea reloads settings.conf into memory (or restart the app).
  • Menus: Dropdowns from the top bar anchor to their buttons, so they stay aligned when the results band is not at the top.

Searching effectively

  • Unified search: Pacsea queries official repositories (including optional ones indexed by pacman, such as BlackArch when [blackarch] is enabled) and the AUR. Extra sync repos declared in repos.conf are merged into indexing when enabled (see Custom repositories); the Results title bar can expose a Repos overflow menu for related filters when applicable.
  • Debounced typing keeps search snappy.
  • Prefetching: details for the first few results are prefetched to reduce latency in the Package Info pane.

Fuzzy search mode:

  • Press CTRL+F to toggle fuzzy search mode (fzf-style matching). See Keyboard Shortcuts for all shortcuts.
  • Fuzzy search allows finding packages even when you don't know the exact name
  • Toggle back to normal substring search with CTRL+F again
  • The current search mode is indicated in the UI
  • Configure fuzzy search to be enabled by default via fuzzy_search = true in settings.conf (see Configuration)

Sorting and filters:

  • Click "Sort ▾" in the Results title to switch between Best matches (relevance), AUR popularity, or Alphabetical (Pacman‑first).
  • Toggle repo visibility by clicking badges in the Results title bar: [AUR], [core], [extra], [multilib], and—when your system exposes them—optional official sources such as [EOS], [CachyOS], [Artix], and [BlackArch] (see BlackArch repository below). Artix uses a dropdown; BlackArch, EOS, and CachyOS use simple on/off chips that appear only when those repos are present in the index.

AUR package status markings:

  • [OOD] - Out-of-date packages flagged by maintainers (displayed in red)
  • [ORPHAN] - Orphaned packages with no active maintainer (displayed in red)
  • These markers appear before the package name in the Results list
  • Help identify packages that may need attention before installation

Focused details:

  • The Package Info pane reflects the selection in your currently focused pane (Results, Recent, or Install/Remove).
  • AUR vote/unvote shortcut: press Ctrl+E on a selected AUR package to open a confirmation modal. Pacsea chooses Vote vs Unvote automatically from cached live vote-state.

BlackArch repository

Pacsea treats the BlackArch community repository as an optional official source once it is configured in pacman—not as part of the AUR.

What Pacsea does

  • Indexes BlackArch packages together with core, extra, multilib, and other optional official mirrors you have enabled (via the same official index path Pacsea already uses).
  • Labels those packages with a BlackArch repo label in results and related UI.
  • Filter chip: When BlackArch packages are present in the loaded official index, a [BlackArch] chip appears in the Results title bar. Click it to show or hide BlackArch results, like the EndeavourOS and CachyOS optional chips (not a dropdown).
  • Preflight: In install/remove preflight views, BlackArch dependencies are highlighted with the same “special optional repo” badge treatment as other recognized optional official sources where applicable.

What Pacsea does not do

  • No bootstrap: Pacsea does not add the BlackArch repo to pacman.conf, install the BlackArch keyring, or run BlackArch setup scripts. Configure BlackArch using the official BlackArch documentation (or your distro’s instructions) first.
  • No AUR helper changes: paru / yay behavior is unchanged; BlackArch is handled through pacman’s official package lists.

If the chip or packages are missing

  • Confirm the repo is enabled and synced, for example: grep -E '^\[blackarch\]' /etc/pacman.conf and sudo pacman -Sy. If pacman -Sl blackarch returns nothing or the repo is absent, Pacsea has nothing to merge into the index and the chip will not appear—this is expected.

Custom repositories (repos.conf and Repositories modal)

Pacsea can help you maintain extra pacman sync repositories (third-party or internal mirrors) without hand-editing pacman.conf every time—on Linux only for the privileged apply path.

Files and scope

  • Recipe: ~/.config/pacsea/repos.conf (or $XDG_CONFIG_HOME/pacsea/repos.conf). TOML with [[repo]] entries: name (pacman section name), enabled, and a source (server, mirrorlist, or remote mirrorlist_url), plus optional signing fields (key_id, sig_level). Duplicate name values in the file are rejected.
  • Managed drop-in: Successful apply writes /etc/pacman.d/pacsea-repos.conf and ensures a guarded Include block exists in /etc/pacman.conf (Pacsea only touches lines between its markers).
  • Examples: See the shipped config/repos.conf in the Pacsea repo.

Opening the modal

  • Options → Repositories, or use the Repos overflow control in the Results title bar when custom-repo filters are available (see in-app help).

The modal merges your repos.conf rows with a live pacman scan (what is actually configured on disk). Use Apply to reconcile the managed drop-in and run the planned privileged steps (download mirrorlists, refresh keys, pacman -Sy, etc.). --dry-run prints the same commands without executing mutating steps.

Keys (summary)

Key Action
Space Toggle enabled for Pacsea-managed rows (Linux) and run the same apply-oriented path as Enter where applicable
Enter Run the apply plan (preview in dry-run)
o Open repos.conf in your editor (VISUAL / EDITOR)
r Refresh the signing key for the selected row (pacman-key, Linux)
s Open the in-tree example file for setup hints
↑/↓, j/k, PgUp/PgDn, Home/End Navigate the list
Mouse wheel When the pointer is inside the modal, move the focused row up/down (same as arrow keys)
Esc / q Close

Full detail: Keyboard Shortcuts — Repositories modal.

Apply behavior

  • All [[repo]] disabled: Apply still succeeds: the managed drop-in is written as a short comment-only stub (no active Server entries), instead of erroring.
  • Indexing: When building the official index, extra pacman -Sl work ignores disabled [[repo]] rows—so toggling a repo off does not keep costing -Sl passes for that name.
  • Failed privileged run: If a sudo/password step fails, Pacsea clears pending overlap check and “reopen Repositories” resume flags so stale wizards do not run afterward.

After apply: foreign overlap (AUR vs new repo)

When you enable a repository whose sync database ships the same package names you already installed as foreign/AUR packages, updates can get confusing (helpers and sync repos may disagree on which build you want).

After a full successful Repositories apply, Pacsea compares a snapshot of pacman -Qm from queue time with pacman -Sl output for the repository you added:

  • Non-empty overlap: A multi-step “AUR vs new repository” wizard opens (acknowledge → optional per-package migrate selection → sudo summary). Migration uses privileged pacman to replace selected AUR installs with the repo build; --dry-run stays respected.
  • Empty overlap: A short toast explains there is nothing to reconcile (or the DB did not list overlaps).
  • Enter: On the overlap flow, Enter is ignored until the apply executor has finished and the UI shows the log line telling you to continue—avoid confirming too early.
  • Esc / q on the first warning step: Can turn off that repository in repos.conf and queue another apply so the drop-in matches your recipe (undo path without leaving the wizard’s intent unclear).
  • If pacman -Sl fails after you removed a repo (e.g. DB gone), Pacsea treats overlap as empty instead of surfacing a misleading “connection” style error.

Reopening Repositories after other modals

If you dismiss Preflight, Post-summary, the overlap wizard without migrating, or certain related alerts, Pacsea may reopen the Repositories modal with a fresh pacman scan (your row selection is restored by name). Pressing r in the Repositories modal for key refresh does not arm this resume behavior. Starting foreign migrate clears the pending resume.

AUR installs when a sync repo has the same name

Community repos (e.g. Chaotic-AUR) often publish AUR-adjacent packages under the same pkgname as the AUR. paru and yay may otherwise satisfy an “AUR” install from sync instead of the AUR.

Pacsea addresses this in two ways:

  1. Queue command shape: For mixed queues, Pacsea runs pacman for official/sync names and a separate helper invocation with paru / yay -S --aur (or equivalent) for AUR-only names so the helper is forced toward true AUR builds. Scan-cache priming uses the same probe shape.
  2. One-shot warning: If you select an AUR result row for install but the same name also appears as an official/sync row in the current combined results, Pacsea shows a red warning once per continuation—you can proceed with Enter or cancel with Esc / q.

Configuration reference

See Configuration — Custom repositories for file location and relationship to settings.conf.

Find within lists:

  • Recent pane and Install/Remove pane support in‑pane find with / then Enter=next, Esc=cancel.

Queueing and installing

Add to queue:

  • In Results, press Space to queue the selected package into the Install list.

Review the queue:

  • Switch focus to the Install pane to see queued items with repo badges and AUR popularity when available.

Install behavior:

  • Press Enter in the Install pane to confirm installing all queued packages.
  • Preflight modal: By default, Pacsea shows a Preflight confirmation modal (unless skip_preflight = true in settings.conf). See Configuration for details. This allows you to:
    • For Install actions: Inspect dependencies and files that will be installed, review config conflicts, and for AUR packages, press S to run security scans before installing
    • For Remove actions: Inspect reverse dependencies (packages that depend on what you're removing), affected services, and files that will be removed
  • If the queue mixes official/sync and AUR-only names, Pacsea runs pacman -S (via your privilege tool) for the official set and a second helper invocation for AUR-only names using paru or yay with -S --aur, so helpers do not satisfy “AUR” picks from sync databases (relevant when third-party repos mirror AUR package names).
  • If every queued package is AUR, the whole queue goes through the helper (still using the -S --aur shape where applicable).
  • If no AUR packages are present, official packages are installed with pacman -S --needed --noconfirm via your configured privilege tool (privilege_tool = auto|sudo|doas).
  • Password prompts and passwordless sudo: See Passwordless sudo below.
  • In --dry-run, Pacsea prints the exact commands instead of making changes.

Passwordless sudo
Install, update, and downgrade operations may require authentication. Pacsea supports multiple modes:

  • Interactive (fingerprint-friendly): set auth_mode = interactive to let sudo/doas handle PAM prompts directly in the terminal (including fingerprint via fprintd, when configured).
  • Passwordless-only: set auth_mode = passwordless_only to only proceed when passwordless execution is available (no password prompt UI).
  • Legacy passwordless sudo opt-in: use_passwordless_sudo = true (older switch; still supported when using sudo).

Choose the privilege tool with privilege_tool = auto|sudo|doas in settings.conf. For system setup (sudoers / doas.conf), see Troubleshooting.

Install logging:

  • A timestamped install_log.txt is written under the XDG state dir.

Privilege setup assistants (sudo timestamp + doas persist)

Pacsea includes two guided setup flows to reduce authentication interruptions during long installs/updates:

  • Sudo credential cache (sudoers): suggests timestamp_timeout presets and shows safe manual steps for creating /etc/sudoers.d/99-pacsea-timestamp with visudo.
  • Doas persist setup: shows vetted doas.conf snippets and a validation checklist for persist policy + optional PAM/fingerprint readiness.

Where to open them:

  • Options → Optional Deps: select sudo_timestamp_setup or doas_persist_setup
  • Startup setup tasks: Pacsea may surface these as recommended setup actions depending on your configured privilege tool

Notes:

  • These are guidance/setup helpers; Pacsea does not silently rewrite privileged auth policy files for you.
  • --dry-run is respected for command execution paths; setup text and checks can still be displayed for review.

Long-run authentication warnings

Before operations that may run for a long time (install/update/remove/downgrade and related privileged paths), Pacsea can show a one-time readiness warning if your current auth setup may pause mid-run for re-authentication.

  • The warning points to configuring sudo timestamp timeout or doas persist policy (and PAM where available).
  • Continue with Enter if you are ready, or cancel to adjust your privilege setup first.

Installed‑only and removal

Enable installed‑only mode:

  • Options → "List installed packages". The Results switch to installed packages only and the right pane becomes the Remove/Downgrade list.

Installed packages filter mode:

  • By default, only "leaf" packages are shown (explicitly installed with no dependents). This is safer for removal.
  • To show all explicitly installed packages (including those with dependents), configure installed_packages_mode = all in settings.conf and reload config (Ctrl+R). See Configuration for details.

Queue removals:

  • Space adds the selected package to the Remove list. Enter in the Remove list opens a confirmation dialog.

Safety:

  • Core packages show a prominent warning. --dry-run prints the planned command instead of executing it.
  • The Preflight modal for Remove actions shows reverse dependencies (packages that depend on what you're removing) and affected services.

Package downgrade

Pacsea supports downgrading installed packages to previous versions using the downgrade tool.

Prerequisites:

  • Install the downgrade tool:
    • Via Optional Deps modal: Options → Optional Deps → Navigate to "Downgrade-Tool" → Press Enter
    • Or manually: sudo pacman -S downgrade

Using downgrade:

  1. Enable installed‑only mode: Options → "List installed packages"
  2. Navigate to the Downgrade list in the right pane
  3. Add packages to downgrade: Space adds the selected package to the Downgrade list
  4. Execute downgrade: Enter in the Downgrade list opens the downgrade tool in a terminal
  5. Follow the downgrade tool prompts to select the version to downgrade to

Note: The downgrade operation respects the skip_preflight setting. If skip_preflight = false, you'll see the Preflight modal before the downgrade tool opens. See Configuration for details.

Security scans for AUR packages

Pacsea includes a comprehensive security scanning workflow for AUR packages:

Available scanners:

  • ClamAV: Antivirus scanning for malware
  • Trivy: Filesystem vulnerability scanning
  • Semgrep: Static analysis checks
  • ShellCheck: Linting for PKGBUILD and .install scripts
  • VirusTotal: Hash lookups (requires API key configuration)
  • Custom patterns: Suspicious pattern scanning
  • aur-sleuth: LLM-based audit tool (runs in a separate terminal window)

aur-sleuth setup:

  • First-time setup required: Options → Optional Deps → Navigate to "aur-sleuth-setup" → Press Enter
  • Setup wizard helps you:
    • Install aur-sleuth (choose system or user installation)
    • Configure your API endpoint and key
    • Select your preferred model
  • Runs in a separate terminal window so you can continue using Pacsea
  • Uses proxy and certificate settings from your Pacsea configuration

How to use (Install actions):

  1. Queue AUR packages for installation
  2. Press Enter to open the Preflight confirmation dialog
  3. Press S to open the Scan Configuration modal
  4. Toggle scanners on/off with Space
  5. Press Enter to run selected scans
  6. Review the comprehensive scan summary showing:
    • Infections found (ClamAV)
    • Vulnerabilities by severity (Trivy)
    • Semgrep findings count
    • VirusTotal statistics
    • ShellCheck results
    • Custom pattern matches
    • aur-sleuth audit results

How to use (Remove actions):

  1. Add packages to the Remove list
  2. Press Enter to open the Preflight confirmation dialog
  3. Review reverse dependencies (packages that depend on what you're removing)
  4. Review affected services that will be impacted
  5. Review files that will be removed
  6. Meta-packages (like base) show warnings when they have no reverse dependencies, as removal may affect system state

VirusTotal API Setup: Configure your VirusTotal API key directly from the Optional Deps modal. Press Enter on the "Security: VirusTotal API" entry to open the API key page, then paste and save your key. Alternatively, you can set virustotal_api_key in settings.conf (see Configuration).

AUR voting via SSH

Pacsea supports voting and unvoting AUR packages directly from the Results list through an SSH-based flow.

Requirements:

  • Your SSH public key must be added to your AUR account: https://aur.archlinux.org/account
  • A working SSH client (ssh by default, configurable)
  • A selected AUR package in Results

How to use:

  1. Select an AUR package in the Results pane.
  2. Press Ctrl+E.
  3. Review the confirmation modal (Pacsea automatically picks vote or unvote based on cached state).
  4. Confirm with Enter (or cancel with Esc).

Guided SSH setup helper:

  • Open Options → Optional Deps and select aur-ssh-setup.
  • The setup flow prepares local SSH state first (~/.ssh/config, key generation if needed, and host-key readiness) and then shows an apply key on AUR confirmation step before running the live SSH validation.
  • If an existing AUR host block is detected in ~/.ssh/config, Pacsea shows an overwrite confirmation before writing.
  • You can copy the shown public key directly from the setup modal using C (or the copy action row with the mouse), then paste it into your AUR account SSH keys.
  • Use O in the setup modal when you want to open the AUR account/login page; Pacsea does not force-open the browser automatically.
  • Success feedback appears after the remote AUR SSH validation succeeds.

Notes:

  • If your AUR server-side endpoint does not support vote-state lookup, Pacsea degrades gracefully and still allows vote/unvote actions.
  • In --dry-run, mutating vote actions are not executed.

TUI Optional Deps

Options → "Optional Deps" opens a dedicated view to install and verify recommended helper tools:

Features:

  • Environment-aware defaults (detects Wayland/X11, desktop environment, distro)
  • Desktop-aware preferences (e.g., GNOME Terminal on GNOME, Klipper on KDE)
  • Shows installation status for each tool
  • Press Enter on any entry to install missing packages
  • Categories include:
    • Editors (nvim, vim, helix, emacs/emacsclient, nano)
    • Terminals (alacritty, kitty, ghostty, xterm, gnome-terminal, konsole, xfce4-terminal, tilix, mate-terminal)
    • Clipboard utilities (wl-clipboard for Wayland, xclip for X11)
    • Mirror updaters (reflector, pacman-mirrors, eos-rankmirrors, cachyos-rate-mirrors)
    • AUR helpers (paru, yay)
    • Security utilities (ClamAV, Trivy, Semgrep, ShellCheck, VirusTotal API setup, aur-sleuth)
    • AUR SSH helper (aur-ssh-setup) for vote/unvote setup
    • Package downgrade (downgrade)

The modal blocks main UI interactions to prevent accidental clicks/keys while configuring.

Mouse wheel: With the pointer inside the Optional Deps list (not on the small [Wizard] button), scroll up/down to move the highlighted row. [Wizard] still uses a normal click to open the startup-setup selector.

System update dialog

Options → "Update System" opens a checklist to run common maintenance actions in a terminal:

  • Update Arch mirrors (optionally pick a country, distro-aware tool selection)
  • Update system packages (sudo pacman -Syu)
  • Update AUR packages (paru/yay -Sua, only updates AUR packages since official packages are already updated)
  • Clear pacman and AUR caches

Force Sync mode: When on the pacman update row, you can toggle between sync modes:

  • Normal (-Syu): Standard sync - only refreshes package databases that have changed
  • Force Sync (-Syyu): Force-refreshes all package databases, even if unchanged

Use ←/→ or Tab keys on the pacman row to toggle between modes. Force Sync is useful after switching mirrors or when you suspect database corruption.

Distro-aware behavior: Pacsea automatically detects your distribution and uses the appropriate mirror tool:

  • Manjaro: Uses pacman-mirrors
  • EndeavourOS: Uses eos-rankmirrors
  • CachyOS: Uses cachyos-rate-mirrors
  • Standard Arch: Uses reflector

Mirror index operations now include improved error handling and recovery, providing clearer feedback when mirror updates encounter issues.

Use Space to toggle items and Enter to execute the selected actions.

Mouse wheel: With the pointer inside the System Update checklist modal, scroll up/down to move the highlighted option (same range as keyboard navigation).

AUR update behavior:

  • AUR updates use -Sua flag (only updates AUR packages, not official packages which are already updated by pacman)
  • If pacman update fails but AUR update is enabled, a confirmation popup appears asking if you want to continue with AUR update anyway
  • Press Enter or Y to continue with AUR update, or Esc, Q, or N to cancel
  • This allows you to proceed with AUR updates even if pacman encountered issues, though it may fail if AUR packages require newer official packages

Package Info and PKGBUILD viewer

Package Info shows:

  • Name, version, description, repo, URL
  • AUR popularity (when available)
  • Maintainer and metadata for AUR packages

PKGBUILD preview:

  • Click "Show PKGBUILD" to open an inline preview. Use the mouse wheel to scroll the text; press Esc to close.
  • Fetching: Each PKGBUILD download runs in its own async task so one slow upstream (for example GitLab) does not block other packages’ fetches. If you change rows faster than the network, Pacsea drops responses that no longer match the focused package so the viewer does not flash stale scripts. Unreachable hosts fail faster thanks to short curl connect/time limits.
  • AUR: https://aur.archlinux.org/cgit/aur.git/plain/PKGBUILD?h=<name>
  • Official: Arch GitLab raw PKGBUILD (tries main, falls back to master)

Clipboard helper:

  • Click "Copy PKGBUILD" to copy the PKGBUILD to your clipboard
  • Requires wl-clipboard (Wayland) or xclip (X11) to be installed
  • The copied PKGBUILD includes a suffix configured in settings.conf (clipboard_suffix)
  • This suffix serves as a reminder to review build scripts for suspicious activities
  • Configure the suffix in ~/.config/pacsea/settings.conf: 
    clipboard_suffix = Check PKGBUILD and source for suspicious and malicious activities

AUR Package Status Markings

Pacsea displays status indicators for AUR packages to help you identify packages that may need attention:

Out-of-date packages [OOD]:

  • Shown in red before the package name
  • Package has been flagged as out-of-date
  • May need an update or the maintainer may be inactive
  • Check the AUR package page for more details before installing

Orphaned packages [ORPHAN]:

  • Shown in red before the package name
  • Package has no active maintainer
  • May still work but won't receive updates
  • Consider finding an alternative if regular updates are important

How to use:

  • Markings appear automatically in the Results list
  • No action needed - they're just for information
  • Click the package to see details or use Comments viewer (Ctrl+T) to read discussions

AUR Comments viewer

Pacsea includes a built-in viewer for AUR package comments, allowing you to read community discussions directly within the application.

Features:

  • Automatic fetching: Comments are fetched from the AUR package page when you toggle the viewer
  • Markdown support: Comments support markdown formatting (bold, italic, code blocks, links)
  • Clickable URLs: Automatically detects and makes URLs clickable (http://, https://, www.)
  • User profile links: Click on author names to open their AUR profile page
  • Timestamp links: Click on timestamps to view the comment on the AUR website
  • Auto-update: Comments automatically update when you navigate to a different AUR package (if comments are visible)
  • Caching: Comments are cached in memory to avoid repeated network requests
  • Scrollable: Use mouse wheel or keyboard to scroll through comments

How to use:

  1. Select an AUR package in the Results pane
  2. Toggle comments viewer using one of these methods:
    • Press Ctrl+T (default keybind, configurable in keybinds.conf)
    • Click the "Show comments" button in the Package Info pane
  3. Comments will be fetched and displayed in a split pane alongside Package Info
  4. Navigate between packages to automatically update comments (if comments are visible)
  5. Toggle off comments using Ctrl+T again or click "Hide comments"

Layout behavior:

  • When only comments visible: Package Info 50%, Comments 50%
  • When only PKGBUILD visible: Package Info 50%, PKGBUILD 50%
  • When both visible: Package Info 50%, PKGBUILD 25%, Comments 25%

Notes:

  • Comments are only available for AUR packages (not official repository packages)
  • Comments are fetched via web scraping from https://aur.archlinux.org/packages/<pkgname>
  • Comments are sorted by date (latest first)
  • If a package has no comments, you'll see "No comments yet"
  • Network errors are displayed as error messages in the comments pane

Customizing the keybind: You can change the comments toggle keybind in ~/.config/pacsea/keybinds.conf:

keybind_comments_toggle = CTRL+T

See Keyboard Shortcuts for the complete list of shortcuts and Configuration for keybind customization details.

Package updates and news

Updates available

  • A button at the top of the interface shows how many packages have updates available
  • Click the button to view a detailed list of all available updates, showing both current and new versions for each package
  • Mouse wheel: With the pointer over the updates list body, scroll up/down to move the highlighted entry (respects the active / filter when set). See Keyboard Shortcuts — Updates available modal.
  • The update list includes both official repository packages and AUR packages
  • Preflight integration: Press Enter on an update to review it in detail before installing
    • Check dependencies, files, and potential conflicts
    • For AUR packages, you can run security scans
    • Can be disabled with skip_preflight setting (see Configuration)
  • Updates are automatically checked in the background every 30 seconds (configurable via updates_refresh_interval in settings.conf - see Configuration)
  • The updates count refreshes automatically after install, remove, or downgrade operations
  • Real-time progress display during update operations

News mode (Extended News Feed)

Pacsea's News Mode provides a comprehensive feed of Arch Linux news, security advisories, package updates, and AUR comments with advanced filtering and smart features.

Switching to News mode:

  • Switch modes via Options → News mode (Normal mode: Shift+O opens Options, then choose "News mode")
  • Set app_start_mode = news in settings.conf to start directly in News mode (default: package)

News sources:

  • Arch Linux News: Latest announcements and updates from archlinux.org
  • Security Advisories: Security alerts with severity indicators and affected packages
  • Package Updates: Track version changes for your installed packages with automatic change detection (version, maintainer, dependencies)
  • AUR Comments: Recent community discussions and feedback from AUR package pages

Layout:

  • Center pane lists news items with a search bar
  • Left pane shows search history
  • Right pane shows bookmarks
  • Use Tab/←/→ to move between results, history, and bookmarks
  • Hide/show history or bookmarks from the Panels menu (Shift+P)

Filters:

  • Header filter chips toggle each source type: Arch news, security advisories, package updates, and AUR comments
  • Installed-only filter: When enabled, shows only advisories and updates for packages on your system
  • Age filter: Configure maximum age in days via news_max_age_days in settings.conf (default: unlimited). Filter chips show active filters with clickable areas for easy toggling.

Sorting:

  • Use Shift+Tab to cycle through sort modes: date, title, severity (for advisories), or unread status
  • Sort menu stays open until you select an option or close it (no longer auto-closes)
  • The change_sort keybind is shown in the help footer in News mode
  • Sorting works consistently across all panes and modes

Search:

  • Type in the news search bar to filter items
  • Independent search inputs: News mode and Package mode have separate search fields — no shared state when switching between modes
  • Search text is preserved when switching modes, so you can switch back and forth without losing your queries
  • Searches auto-save to history (deduped, persisted)
  • Pick a history entry to reuse a query

Actions:

  • Enter: Opens the selected item in your browser and loads its content
  • r: Marks the selected item as read/unread (toggle) — only works in normal mode (prevents accidental marking when typing 'r' in insert mode)
  • Ctrl+R: Marks all visible items as read — only works in normal mode
  • Space: Bookmarks the selected item and stores a cached copy of its content

Bookmarks:

  • Bookmarks live in the right pane
  • j/k or arrows to navigate; Enter loads the bookmarked item and its cached body
  • Delete removes a bookmark
  • Cached content is reused on reopen to avoid refetching

Smart features:

  • Change Detection: Automatically detects package changes (version, maintainer, dependencies) and highlights them in package update items
  • Offline Support: Caches package data to disk for offline access and faster loading. Multi-layer caching (15min memory, 14 days disk) reduces network requests
  • Background Processing: Failed requests are automatically retried in the background with exponential backoff (10s, 20s, 40s), up to 3 attempts
  • Streaming Updates: After initial 50 items, additional news items load automatically in the background and stream to the UI at 1 per second
  • AUR Balance: Ensures AUR packages are always represented alongside official packages (dedicated allocation)
  • Rate Limiting: Intelligent request management prevents server blocking
  • Error Recovery: Gracefully handles repeated failures without blocking your workflow

Content:

  • Selecting an item fetches and caches the article body
  • Reopening uses the cache when available
  • Installed-only filter keeps advisories scoped to packages on your system
  • Package updates show change indicators when versions, maintainers, or dependencies have changed

Announcements

Pacsea includes an announcement system to keep you informed about important updates, new features, security issues, and development information.

Types of announcements:

  • Version announcements: Automatically shown when you first launch a new version, highlighting what's new in that release. These are always shown regardless of settings.
  • Remote announcements: Important updates and notices fetched from the announcement service. These can be disabled via the get_announcement setting (see Configuration).

Features:

  • Smart display: Announcements appear at startup in a modal dialog
  • Clickable URLs: URLs in announcement content are automatically detected and clickable (opens in your default browser)
  • Markdown support: Announcements support markdown formatting (headers, bold, italic, code blocks, links)
  • Persistent read status: Mark announcements as read so they won't appear again
  • Sequential display: Multiple announcements are shown one at a time (version announcements first, then remote announcements, then news items)

How to use:

  • Mark as read: Press r to mark the current announcement as read. It won't show again on future startups.
  • Dismiss temporarily: Press Enter, Esc, or q to dismiss the announcement. It will show again on the next startup.
  • Scroll content: Use ↑/↓, j/k, or PageUp/PageDown to scroll through long announcement content
  • Click URLs: Click on any URL in the announcement content to open it in your browser

Configuration:

  • Disable remote announcements by setting get_announcement = false in ~/.config/pacsea/settings.conf (see Configuration)
  • Version announcements always show when you first launch a new version, regardless of this setting

Announcement queue:

  • Announcements are shown sequentially: version announcements first, then remote announcements, then news items
  • Each announcement must be dismissed or marked as read before the next one appears
  • News items are queued to show after all announcements are dismissed

Panels visibility and persistence

Panels dropdown:

  • Quickly hide/show the Recent pane, the Install/Remove pane, and the Keybinds footer.
  • Your choices persist in settings.conf (show_recent_pane, show_install_pane, show_keybinds_footer) and are restored on next run.

Enhanced footer:

  • The Keybinds footer now displays keybindings in a multi-line format for better readability
  • Shows all relevant shortcuts for the current context and mode

Collapsed menu:

  • Automatically appears when your window is too narrow for all menu buttons
  • Provides access to Config/Lists, Panels, and Options in one compact menu
  • Click the collapsed menu button to open it
  • Works seamlessly when resizing your terminal window

Loading indicators:

  • Visual feedback during data fetching with informative messages
  • Loading states are clearly indicated throughout the application
  • Helps you understand when operations are in progress

Keyboard and mouse essentials

Modal mouse wheel: In System Update, Repositories, Optional Deps, and the Updates available list, moving the scroll wheel while the pointer is inside the modal moves the focused row or option (in addition to normal keyboard navigation).

Core navigation:

  • Help overlay: F1 or ?
  • Switch panes: Tab / Shift+Tab, or ← / →
  • Exit: Ctrl+C (Esc does not quit; it cancels/defocuses)
  • Extended keybinds: Shift+char keybind support is available across all panes and modes for consistent navigation

Search pane:

  • Move selection: ↑ / ↓ / PageUp / PageDown
  • Add to install: Space
  • Install selected: Enter
  • Toggle Normal/Insert: Esc / i
  • Normal mode: h/l to extend select, d to delete, j/k to move list selection, Shift+Del to clear
  • Normal mode menus: Shift+C (Config), Shift+O (Options), Shift+P (Panels). From the Config menu you can open settings, theme, or keybinds for editing in your preferred editor (VISUAL or EDITOR). See Configuration for details.
  • Normal mode actions: Shift+S (open Arch status), Shift+I (import packages), Shift+E (export Install list)
    • Import packages (Shift+I): Import package names from a file. Enhanced validation now provides better error handling and prevents invalid package names from being processed, with clearer error messages for problematic entries.

Recent pane:

  • Move: j / k, or ↑ / ↓
  • Use query / Add first match: Enter / Space
  • Find: /, Enter=next, Esc=cancel

Install pane:

  • Move: j / k, or ↑ / ↓
  • Confirm install all: Enter
  • Remove selected / Clear all: d or Delete / Shift+Delete
  • Find: /, Enter=next, Esc=cancel

Details, PKGBUILD & Comments:

  • Open URL: Ctrl+Shift+left‑click on URL
  • Show/Hide PKGBUILD: Mouse left‑click on label or CTRL+X; Esc closes
  • Show/Hide Comments: Mouse left‑click on "Show comments" button or CTRL+T; Esc closes
  • Copy PKGBUILD: Click "Copy PKGBUILD" button (requires wl-clipboard on Wayland or xclip on X11)
    • The copied PKGBUILD includes a suffix configured in settings.conf (clipboard_suffix)
    • This suffix serves as a reminder to review build scripts for suspicious activities

For a complete, always‑current keybindings table, see the Keyboard Shortcuts wiki page.

CLI Commands

Pacsea supports powerful command-line operations, allowing you to manage packages without launching the TUI.

Search packages

pacsea -s <query>          # or: pacsea --search <query>

Searches for packages in both official repositories and AUR, then exits.

Install packages

pacsea -i <package1> <package2>          # or: pacsea --install <package1> <package2>
pacsea -I <filename.txt>                 # Install from file (supports comments with #)

Installs packages directly from the command line. Supports both official and AUR packages. The -I flag reads package names from a file (one per line, comments with # are ignored). Package import validation has been enhanced to provide better error handling and prevent invalid package names from being processed.

Remove packages

pacsea -r <package1> <package2>          # or: pacsea --remove <package1> <package2>

Removes packages with a confirmation prompt. After removal, shows any remaining config directories in $HOME and $HOME/.config.

System update

pacsea -u          # or: pacsea --update

Updates both official packages (sudo pacman -Syu) and AUR packages (via paru -Sua or yay -Sua). The AUR update uses -Sua to only update AUR packages since official packages are already updated by pacman. If pacman update fails, AUR update is skipped automatically. Results are logged to ~/.config/pacsea/logs/update.log with detailed failure summaries including failed commands and packages.

List installed packages

pacsea -l                    # Explicitly installed (default)
pacsea -l --exp              # Explicitly installed
pacsea -l --imp              # Implicitly installed
pacsea -l --all              # All installed packages

Lists installed packages to stdout, one per line.

Arch News

pacsea -n                    # All news (default)
pacsea -n --unread           # Unread news only
pacsea -n --read             # Read news only
pacsea -n --all              # All news

Displays Arch Linux news items with date, title, and URL. Outputs a link to the website at the end.

Clear cache

pacsea --clear-cache

Removes all cache files (dependencies, files, services, sandbox, details) and exits.

General options

pacsea --dry-run              # Perform a dry run without making actual changes
pacsea --verbose             # Enable verbose output (equivalent to --log-level debug)
pacsea -v                     # Short form of --verbose
pacsea --log-level <level>    # Set the logging level (trace, debug, info, warn, error)
pacsea --no-color             # Disable colored output
pacsea --version              # Show version information
pacsea --help                 # Show help message

Refresh package database

pacsea -y                     # Update package database before starting TUI
pacsea --refresh              # Long form of -y

Getting help

For a complete list of all available options and flags, run:

pacsea --help

Note: All CLI commands exit after completion and don't launch the TUI interface, except when using --refresh which updates the database and then launches the TUI.

Clone this wiki locally