A friendly command line for everyday Arch Linux package management.
Familiar words in front. Real paru, yay, and pacman underneath.
Arch is powerful. Everyday package management should not feel like a test of how many flags you can remember.
I built Archdown to smooth out my own Arch experience. I wanted to type what I
meant—search, install, update,
upgrade—and still keep the package ecosystem and control that made
me choose Arch in the first place.
The mission: make Arch friendlier without hiding Arch, replacing its tools, or inventing another package ecosystem.
Archdown is a small compatibility layer for humans. It chooses an available backend, runs the real Arch tooling, and turns common workflows into memorable commands with clearer output and safer defaults.
Archdown is not in the AUR or PyPI yet. Install the current release directly with uv:
sudo pacman -S --needed uv
uv tool install "git+https://github.com/vitalNohj/archdown@v0.2.0"
archdown doctorThen try the everyday loop:
archdown search terminal emulator
archdown install neovim
archdown update
archdown upgradePrefer something shorter? The installed ad command is a complete
alias:
ad search ripgrep
ad updateImportant
archdown update is read-only. It reports available updates but
never installs them. Only archdown upgrade performs the full
system upgrade.
| Archdown gives you | What that means |
|---|---|
| Intent-first commands | Remember install, not a collection of flags. |
| Arch-native behavior | Packages still come from official repositories and the AUR. |
| Backend awareness | Archdown prefers paru, then yay, then pacman. |
| Safer update semantics | Checking for updates and installing them are separate, explicit actions. |
| Human output | Results are grouped, aligned, color-aware, and clear when nothing was found. |
| No new daemon or database | Archdown remains a lightweight wrapper over tools you already trust. |
| Command | Purpose | Package-system effect |
|---|---|---|
archdown search <terms> |
Search official repositories and the AUR | Read-only |
archdown info <package> |
Show package details | Read-only |
archdown which <command-or-path> |
Find the package that owns a command or file | Read-only |
archdown uses <package> |
Show what still depends on a package | Read-only |
archdown list |
Browse explicitly installed packages | Read-only packages; updates local tracking |
archdown outdated |
List available upgrades | Read-only |
archdown update |
Check and report available updates | Read-only |
archdown install <package...> |
Install packages | Changes packages |
archdown uninstall <package...> |
Remove packages and unused dependencies | Changes packages |
archdown cleanup |
Preview and remove orphaned dependencies | Changes packages after preview |
archdown upgrade |
Perform a full system upgrade | Changes packages |
archdown refresh |
Explicitly sync live package databases | Changes package metadata; warns first |
archdown adopt <package...> |
Add existing packages to Archdown tracking | Local bookkeeping only |
archdown doctor |
Explain detected tools and command mappings | Read-only |
Most package-changing commands support the global --dry-run flag:
archdown --dry-run install ripgrep
archdown --dry-run cleanup
archdown --backend pacman --dry-run upgradeArchdown is deliberately clear about what can change your system.
search, info, which,
uses, list, outdated,
update, and doctor never install, remove, or upgrade
packages.
install, uninstall, cleanup,
refresh, and upgrade are the commands that can change
package or live database state. They expose the backend command, honor dry-run
where applicable, and only print a success message after the backend succeeds.
This split matters on Arch: a bare live database sync can create a
partial-upgrade window. That is why update uses safe query paths
and upgrade remains the one obvious verb for a full
-Syu.
$ archdown update
Outdated packages
-----------------
firefox 152.0-1 -> 153.0-1
linux 6.18.4.arch1 -> 6.18.5.arch1
ripgrep 14.1.1-1 -> 14.2.0-1
Run archdown upgrade to upgrade them.
On a current system:
$ archdown update
Everything is up to date.
Color follows terminal capabilities and respects NO_COLOR.
Use archdown update --no-color when plain output is preferable.
Archdown automatically selects the first backend it finds:
paru → yay → pacman
Run archdown doctor at any time to see what was detected and the
exact backend commands Archdown maps to. You can also force a backend:
archdown --backend pacman search ripgrep
archdown --backend yay updateArchdown does not replace pacman, an AUR helper, or the Arch Wiki. It gives their most common workflows a smaller, friendlier surface.
The current release is v0.2.0, the first feature-complete development release.
- Friendly install, uninstall, search, info, update, and upgrade workflows
- Official repository and AUR-aware backend selection
- Read-only outdated, ownership, and reverse-dependency queries
- Orphan cleanup with a visible preview
- Managed-package adoption and recently-updated markers
- Friendly empty states, success confirmations, color, and dry-run support
- Tested on Python 3.10, 3.11, and 3.12
- Publish maintained AUR and PyPI packages
- Add shell completions
- Add structured JSON output
- Guide users when a preferred backend is missing
- Enrich package information and dependency views
- Keep sanding down rough Arch workflows as real users find them
Have an idea that would make Arch feel kinder? Please open an issue.
Does Archdown replace pacman, yay, or paru?
No. Archdown calls the real backend tools. It is a user-experience layer, not a new package manager or repository.
Is archdown update safe?
Yes. It is read-only and never runs an upgrade or a bare live
-Sy. It reports what can be upgraded and points you to the
explicit archdown upgrade command.
Does it support the AUR?
Yes. Archdown uses paru or yay when available and
falls back to pacman for official repositories.
Why not just memorize the backend flags?
You absolutely can—and Archdown will never take that option away. This project exists for people who would rather remember their intention than the spelling of every routine operation.
Is this an official Arch Linux project?
No. Archdown is an independent community project and is not affiliated with or endorsed by Arch Linux.
Archdown is meant to make Arch more approachable, and the project should feel approachable too. New contributors are welcome. You do not need to be a package manager expert to improve an error message, document a confusing workflow, write a test, or share the friction you hit.
- Read CONTRIBUTING.md for the development and release loop.
- Browse the behavior-first specs in openspec/.
- Report bugs and propose ideas in GitHub Issues.
- Check the changelog to see how the project is evolving.
git clone https://github.com/vitalNohj/archdown.git
cd archdown
python -m venv .venv
.venv/bin/pip install -e '.[dev]'
.venv/bin/pytest -qThe test suite mocks package backends; it never installs, removes, or upgrades real packages.
Archdown is available under the MIT License.
Made on Arch, for people who want to enjoy Arch.