archlinux-manager 1.0.0

Utilities to configure and manage ArchLinux systems.

archlinux-manager

Utilities to configure and manage an ArchLinux system, usable either through an interactive text menu or scripted directly from the command line.

It distinguishes two kinds of actions:

• Modifications install or remove a managed file/setting (e.g. a pacman cleanup hook, journald size limits, an xorg TearFree drop-in). Each can be reviewed against what is already on disk, confirmed, and written into place with sudo only when needed.
• Tasks are operations the tool performs itself rather than configuring the system to do later (e.g. clearing the user cache directory).

Running interactively

With no subcommand it drops into an interactive menu:

$ archlinux-manager

Pick a category (Modifications or Tasks), then the specific action. Controls:

• ↑/↓ (or j/k) to move
• → or enter (or l) to select
• ←, h, or esc to step back a level
• q or ctrl-c to quit

For a modification you then choose apply (install) or remove (uninstall); the change is shown and confirmed before anything is written. A task runs as soon as you select it.

Running from the command line

Drive it non-interactively by passing a subcommand and one or more names (handy for scripts and keybinds). Every name is the CLI name shown by list.

Discovering names

list prints the exact name to pass for every modification and task (the CLI name, with its menu label beneath it):

$ archlinux-manager list
==> Modifications
  -> pacman_hook_paccache
     pacman hook to run paccache
  -> pacman_hook_uv_reinstall_tools_after_python_upgrade
     pacman hook to reinstall uv tools after a Python upgrade
  ...
==> Tasks
  -> clear_user_cache_dir
     Clear user cache dir
  -> update_mirrorlist_with_reflector_fast
     Update pacman mirrorlist with reflector (fast: top 30 by score)
  -> update_mirrorlist_with_reflector_full
     Update pacman mirrorlist with reflector (full: test all mirrors)

Applying a modification

This is the default operation — it installs the managed file(s)/setting:

$ archlinux-manager modification pacman_hook_paccache
$ archlinux-manager modification NAME [NAME ...]   # apply several at once

Removing a modification

Add --remove to uninstall instead of install:

$ archlinux-manager modification --remove pacman_hook_paccache
$ archlinux-manager modification --remove NAME [NAME ...]

Running a task

Tasks are actions the tool performs directly; just name them:

$ archlinux-manager task clear_user_cache_dir
$ archlinux-manager task NAME [NAME ...]           # run several at once

By default, applying/removing a modification still prompts you to review the change and confirm before writing (escalating with sudo as needed). Add --non-interactive to a modification to skip all review/confirm/sudo prompts (see scripting below).

Privileges — run as your user, not with sudo

Run the tool as your normal user. It does not run the Python process as root; instead it runs only the privileged file operations (install / unlink) under sudo, prompting for your password when a write actually needs it. This is the same model AUR helpers use, and it matters here:

• Do not run sudo archlinux-manager. Doing so would execute the interpreter as root, which (a) writes root-owned __pycache__/*.pyc files into your user-installed tool environment, and (b) makes $HOME resolve to root's, so a task like Clear user cache dir would target the wrong cache.
• Run as yourself and let the tool escalate per operation — no root-owned bytecode is ever created, and per-user paths stay correct.

Scripting it non-interactively

Because a scripted run can't answer a password prompt, authenticate sudo once up front so its timestamp is valid, then run with --non-interactive (which uses sudo -n and never prompts):

$ sudo -v                                       # cache sudo credentials
$ archlinux-manager modification --non-interactive \
      pacman_hook_paccache pacman_hook_uv_reinstall_tools_after_python_upgrade

Still run as your user (not via sudo) so the .pyc/$HOME issues above don't apply. For fully unattended use you can instead grant a NOPASSWD sudoers rule for /usr/bin/install and /usr/bin/unlink — note that this is effectively broad root access, so scope it carefully.

Options

-v / --verbose        Console log level INFO
-q / --quiet          Console log level ERROR (overrides -v)
--debug               Console log level DEBUG (overrides -v and -q)
--log-file FILE       Also write rotating logs to FILE
--color auto|always|never

Notes

• Designed for ArchLinux; modifications write to system paths under /etc, /usr, /opt, and /etc/pacman.d/hooks, creating parent directories as needed.
• The pacman-hook modifications are self-guarding: each hook does nothing if the program it drives isn't installed, and applying the modification warns (with the pacman -S command) when that program is missing.
• Clear user cache dir resolves the cache via the XDG base directory spec ($XDG_CACHE_HOME, falling back to ~/.cache) and is best-effort: files in use by a running program are skipped with a warning rather than aborting.
• Update pacman mirrorlist with reflector runs reflector as your user (it needs reflector installed — sudo pacman -S reflector), ranks the fastest current HTTPS mirrors, and writes /etc/pacman.d/mirrorlist via sudo. It does not filter by country (the fastest mirrors are chosen regardless of location). Two variants:
  • fast caps the candidates to the 30 best-scored mirrors before the speed test, so it finishes quickly.
  • full speed-tests every current HTTPS mirror — slower, but won't miss a nearby mirror that a score cap might exclude.