Task-oriented package bundle manager for Arch Linux.
Vokun is a pure Bash CLI tool that wraps pacman, paru, and yay to provide
task-oriented package bundles for Arch Linux and pacman-based distributions such
as CachyOS, EndeavourOS, and Manjaro. Instead of memorizing dozens of individual
package names, you install a bundle -- a curated group of packages organized
around a task like "python development" or "system administration" -- with a
single command.
Under the hood, vokun is a thin wrapper. Every operation shows you the exact
pacman or paru command being run, so nothing is hidden. Packages installed
through vokun are standard system packages; there is no lock-in and no custom
package format. You can mix vokun install with plain pacman -S freely, and
use vokun sync later to reconcile the two.
The name "vokun" (pronounced voh-KOON) means "shadow" in the dragon language from The Elder Scrolls V: Skyrim. It has zero namespace collisions in the CLI/package tool space.
paru -S vokun # Install from the AUR
vokun setup # Check dependencies, bootstrap paru if needed
vokun # Launch interactive mode (first-run wizard on fresh install)
vokun list # Browse available bundles
vokun install sysadmin # Install the sysadmin toolkitparu -S vokun
# or
yay -S vokuncurl -fsSL https://raw.githubusercontent.com/blacktechwarrior/vokun/main/install.sh | bashgit clone https://github.com/blacktechwarrior/vokun.git
cd vokun
sudo make installvokun install <bundle> # Install a bundle (shows packages, confirms)
vokun install <bundle> --pick # Interactively select which packages to install
vokun install <bundle> --exclude pkg1,pkg2 # Install everything except these packages
vokun install <bundle> --only pkg1,pkg2 # Install only these packages from the bundle
vokun install <bundle> --dry-run # Preview what would be installed
vokun rollback # Undo the last reversible action
vokun remove <bundle> # Remove only what vokun installed
vokun remove <bundle> --untrack # Stop tracking, keep packages on system
vokun remove <bundle> --all # Remove ALL packages including pre-existing
vokun remove bundle1 bundle2 # Remove multiple bundles
vokun select <bundle> # Change pick-one selections for a bundle
vokun list # List all available bundles
vokun list --installed # List installed bundles only
vokun list --deps # List packages installed as dependencies
vokun info <bundle> # Show bundle contents without installing
vokun search <keyword> # Search bundles by name, tag, or packageInstall also runs a conflict pre-flight check -- before calling pacman, each
package is checked via pacman -Si for conflicts with already-installed
packages. If conflicts are found, you are warned before proceeding.
vokun get <pkg> # Install a package (pacman -S)
vokun get <pkg> --downgrade # Downgrade to older version (pacman -U)
vokun yeet <pkg> # Remove with deps/configs (pacman -Rns)
vokun yeet <pkg> --untrack # Remove from bundle tracking only
vokun find <query> # Search repos (pacman -Ss)
vokun find <query> --aur # Search repos + AUR
vokun find <query> --pick # Search and interactively select to install
vokun which <pkg> # Info on installed package (pacman -Qi)
vokun which <pkg> --remote # Info on remote/uninstalled (pacman -Si)
vokun owns <file> # Which package owns a file (pacman -Qo)
vokun files <pkg> # List files in a package (pacman -Ql)
vokun update # Full system update (pacman -Syu)
vokun update --aur # Include AUR packages
vokun update --aur-only # Update only AUR packages (paru/yay -Sua)
vokun update --check # Show available upgrades (checkupdates)
vokun update --check --aur # Include AUR in check (paru -Qu)
vokun update --check --aur-only # Check only AUR updatesvokun log # Show last 20 logged actions
vokun log --count 50 # Show last 50 logged actionsEvery bundle install, remove, get, yeet, rollback, and dotfiles action is
recorded in ~/.config/vokun/vokun.log. Entries are color-coded by action type
(green for installs, red for removals).
vokun dotfiles init # Initialize dotfile tracking
vokun dotfiles apply # Apply dotfiles to the system
vokun dotfiles push # Push dotfile changes upstream
vokun dotfiles pull # Pull dotfile changes from upstream
vokun dotfiles status # Show dotfile tracking status
vokun dotfiles edit # Edit a tracked dotfileWraps chezmoi, yadm, or stow behind a unified interface. The backend is
auto-detected or can be set via dotfiles.backend in vokun.conf. All
destructive actions show a preview and require confirmation.
vokun status # Show system overview (profile, bundles, packages, times)
vokun why <pkg> # Show which bundles include a package
vokun untracked # List ad-hoc installs not in any bundle
vokun doctor # Run all health checks (deps, drift, orphans, cache)
vokun snapshot create <name> # Save current system state
vokun snapshot list # List saved snapshots
vokun snapshot diff <name> # Compare snapshot vs current state
vokun snapshot restore <name> # Restore to a snapshot (--dry-run to preview)
vokun snapshot delete <name> # Remove a snapshotvokun orphans # List orphaned packages
vokun orphans --clean # Remove orphans
vokun orphans --deep # Deep cleanup incl. AUR build deps (paru/yay -c)
vokun cache # Show cache size and stats
vokun cache --clean # Keep last 2 versions (paccache -rk2)
vokun cache --purge # Remove all cached packages
vokun size # List packages sorted by installed size
vokun recent # Show recently installed packages
vokun history # Last 50 pacman transactions
vokun history --search nvidia # Find nvidia-related changes
vokun history --upgraded # Only upgrades
vokun foreign # List AUR/foreign packages
vokun explicit # List explicitly installed packages
vokun broken # Check for broken symlinks and depsvokun export # Export custom bundles and config (TOML)
vokun export mybackup.toml # Export to a specific file
vokun export --json # Export in JSON format
vokun import <file> # Import bundles from a file
vokun import <file> --dry # Preview import without applyingWhen importing, vokun shows hook safety warnings -- any post_install
commands found in the imported bundles are displayed for review before you
confirm the import.
vokun sync # Detect untracked packages (forward sync)
vokun sync --auto # Auto-add untracked packages without prompting
vokun sync --quiet # Suppress informational outputSync also performs reverse sync (detects packages removed outside vokun) and drift detection (compares installed state against current TOML definitions to find new or removed packages upstream).
vokun profile show # Show the active profile
vokun profile list # List all profiles
vokun profile switch <name> # Switch to a different profile
vokun profile create <name> # Create a new profile
vokun profile delete <name> # Delete a profileProfiles let you maintain separate sets of installed bundles. Each profile has
its own state file (state-<name>.json). The default profile uses state.json
for backwards compatibility.
vokun check <package> # AUR trust scoring (votes, age, maintainer)
vokun diff <package> # View the PKGBUILD for an AUR packagevokun hook install # Install pacman notification hook
vokun hook install --dry-run # Preview without changes
vokun hook remove # Remove the hook
vokun hook remove --dry-run # Preview removal
vokun setup # Check dependencies and bootstrap paru
vokun uninstall # Remove vokun from the system$ vokun info sysadmin
sysadmin (v1.0.0)
System Administration Toolkit
Tags: admin, essentials, cli
--------------------------------------------------
Packages:
htop Interactive process viewer
btop Resource monitor with rich TUI
fastfetch Fast system information tool
fd Simple, fast alternative to find
ripgrep Blazingly fast recursive text search
bat Cat clone with syntax highlighting
eza Modern replacement for ls
fzf General-purpose fuzzy finder
...
Optional:
sd Intuitive find-and-replace CLI
choose Human-friendly alternative to cut/awk
Vokun ships with 25 default bundles across six categories.
| Bundle | Tags | Key Packages |
|---|---|---|
coding |
dev, essentials | git, base-devel, cmake, gdb, valgrind, strace, man-db, tldr |
sysadmin |
admin, essentials, cli | htop, btop, fastfetch, fd, ripgrep, bat, eza, dust, duf, fzf, zoxide |
networking |
net, admin | nmap, wireshark-cli, traceroute, mtr, curl, wget, iperf3, tcpdump, socat |
| Bundle | Tags | Key Packages |
|---|---|---|
python-dev |
dev, python | python, python-pip, ipython, python-virtualenv, ruff, mypy, python-pytest |
c-cpp-dev |
dev, c, cpp, systems | gcc, clang, gdb, valgrind, cmake, cppcheck |
rust-dev |
dev, rust, systems | rustup, cargo-watch (AUR), cargo-edit (AUR), sccache (AUR) |
web-dev |
dev, web, js | nodejs, npm, bun-bin (AUR), deno (AUR) |
java-dev |
dev, java | jdk-openjdk, maven, gradle |
go-dev |
dev, go | go, gopls (AUR) |
| Bundle | Tags | Key Packages |
|---|---|---|
embedded |
dev, embedded, hardware | openocd, minicom, picocom, arm-none-eabi-gcc, arm-none-eabi-gdb |
fpga-dev |
dev, fpga, hardware | iverilog, gtkwave, verilator, yosys, nextpnr-ice40 (AUR) |
security |
sec, hacking, pentesting | nmap, wireshark-cli, john, hashcat, aircrack-ng, hydra, gobuster |
| Bundle | Tags | Key Packages |
|---|---|---|
multimedia |
media, creative | ffmpeg, mpv, imagemagick, yt-dlp, sox, gimp, inkscape |
latex |
writing, academic | texlive-basic, texlive-latexextra, biber, texlab, pandoc |
gaming |
gaming, fun | steam, lutris, wine, gamemode, mangohud, proton-ge-custom-bin (AUR) |
| Bundle | Tags | Key Packages |
|---|---|---|
vm-container |
devops, infra | docker, podman, qemu-full, virt-manager, vagrant, libvirt |
cloud-tools |
devops, cloud | kubectl, helm, terraform, aws-cli-v2 (AUR) |
| Bundle | Tags | Key Packages |
|---|---|---|
fonts |
desktop, appearance | ttf-fira-code, noto-fonts, noto-fonts-emoji, ttf-jetbrains-mono |
terminal-rice |
desktop, rice, terminal | starship, tmux, zsh, neovim, alacritty |
Vokun stores its configuration in ~/.config/vokun/vokun.conf (TOML format):
[general]
aur_helper = "paru" # paru, yay, or none (auto-detected if unset)
color = true # Colored output
confirm = true # Ask before installing (--yes to override)
fzf = true # Use fzf for interactive pickers if available
[sync]
hook = false # Install pacman hook for new-package notifications
auto_prompt = true # After 'vokun get', prompt to add to a bundle
[dotfiles]
backend = "" # chezmoi, yadm, or stow (auto-detected if unset)
[aur]
trust_threshold = 50 # Minimum votes for "trusted" AUR status
warn_age_days = 180 # Warn if an AUR package has not been updated in this many days
show_pkgbuild = false # Automatically display PKGBUILD on AUR installsState is tracked in ~/.config/vokun/state.json. This file records which
bundles are installed, which packages belong to each bundle, and which packages
were skipped. It is managed automatically; you should not need to edit it by
hand.
Custom bundles live in ~/.config/vokun/bundles/custom/ and use TOML format.
Create a file such as my-tools.toml:
[meta]
name = "My Favorite Tools"
description = "Personal selection of daily-driver utilities"
tags = ["personal", "cli"]
version = "1.0.0"
[packages]
neovim = "Hyperextensible Vim-based text editor"
tmux = "Terminal multiplexer for managing multiple sessions"
starship = "Cross-shell prompt with smart, minimal defaults"
[packages.aur]
visual-studio-code-bin = "Microsoft VS Code (prebuilt binary)"
[packages.optional]
wezterm = "GPU-accelerated terminal emulator with Lua configuration"
[hooks]
post_install = [
"echo 'All set! Restart your shell to pick up changes.'"
]Sections:
[meta]-- Bundle metadata: name, description, tags (used byvokun search), and version. Setextends = "sysadmin"to inherit packages from another bundle, orextends = ["sysadmin", "python-dev"]for multi-parent inheritance (mixins).[packages]-- Core packages from the official repositories. Each key is a package name; the value is a human-readable description shown during install.[packages.aur]-- AUR packages. These are flagged with integrity warnings and require an AUR helper (paru or yay).[packages.optional]-- Packages offered but not selected by default. The user is asked whether to include them during install.[select.<category>]-- Pick-one categories where the user chooses exactly one package from alternatives (e.g., editor, pager, shell). Includelabelfor the display name and optionallydefault. Usevokun select <bundle>to change picks after install.[hooks]-- Lifecycle hook arrays:pre_install,post_install,pre_remove,post_remove. Hook commands are shown to the user and require confirmation before execution.
Once the file is saved, the bundle appears immediately in vokun list and can
be installed with vokun install my-tools.
You can also manage custom bundles from the command line:
vokun bundle create <name> # Create a new custom bundle interactively
vokun bundle add <bundle> <pkg> # Add a package to an existing bundle
vokun bundle rm <bundle> <pkg> # Remove a package from a bundle
vokun bundle edit <bundle> # Open a bundle in your editor
vokun bundle delete <bundle> # Delete a custom bundleNote: Colors are automatically disabled when output is piped to another command or redirected to a file.
See CONTRIBUTING.md for guidelines on adding bundles, coding style, testing, and the pull request process.
MIT -- see LICENSE.