Metadata-Version: 2.4
Name: archlinux-manager
Version: 1.0.0
Summary: Utilities to configure and manage ArchLinux systems.
Project-URL: Homepage, https://github.com/sevaht/archlinux-manager
Project-URL: Source, https://github.com/sevaht/archlinux-manager
Project-URL: Issues, https://github.com/sevaht/archlinux-manager/issues
Author-email: Jacob McIntosh <nacitar.sevaht@gmail.com>
License-Expression: Unlicense
License-File: LICENSE
Keywords: arch,archlinux,cli,configuration,linux,system
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: platformdirs>=4.10.0
Requires-Dist: questionary>=2.1.0
Requires-Dist: rich>=14.0.0
Description-Content-Type: text/markdown

# 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:

```console
$ 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):

```console
$ 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:

```console
$ 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:

```console
$ 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:

```console
$ 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):

```console
$ 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

```console
-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.
