knott

knott is a fast Rust Arch Linux package helper for pacman repositories and the AUR. It combines repo/AUR search, provider-aware AUR planning, and upfront install menus.

Current Features

• Pacman-like CLI defaults: knott runs -Syu, bare terms open a search menu.
• Combined repo/AUR search with AUR narrowing by the shortest term first.
• AUR RPC client with keep-alive, gzip, batching, request timeouts, and per-run caches.
• AUR package info, PKGBUILD printing, and PKGBUILD clone/update support.
• AUR install dry-run/planning with dependency graph ordering and provider lookup.
• Journaled repo/AUR upgrades that can be resumed, repaired, or aborted after an interruption.
• AUR builds and installs are split into makepkg -s, makepkg --packagelist, and explicit pacman -U phases.
• Prefers AUR -bin package variants for installs, upgrades, and dependency providers when they are available.
• Local pacman DB parser for installed markers and AUR update checks, loaded only when those local markers are needed.
• Arch-like version comparison for local-vs-AUR upgrade detection.
• Numeric menu parser supporting 1 2, 1-3, ^4, and package names.
• Sanitized terminal output for package metadata, errors, and dry-run commands.
• Aisling-powered tqdm progress loaders for batched AUR metadata fetches.
• Release builds keep Cargo defaults, with ring capped at opt-level = 2 to avoid a GCC 16.1 internal compiler error during cargo install.

Installation

cargo install --path . --locked
knott --version

Install the published crate from crates.io:

cargo install knott --locked
# or pin it explicitly:
cargo install knott --version 0.1.16 --locked

If the crates.io index has not picked up the latest release yet, use the exact version above or retry after the index updates.

Build

cargo build --release
./target/release/knott --help

Commands

knott                       # repo upgrade, then AUR upgrade
knott ripgrep               # interactive search/install
knott -Ss linux headers     # combined repo/AUR search
knott --aur -Ss shellcheck-bin  # AUR-only search
knott -S ripgrep            # install repo or AUR target
knott -Syu --needed         # refresh repos, upgrade, skip installed targets
knott -Ss linux --no-progress # disable progress loaders for this run
knott --aur -S shellcheck-bin --dry-run --noconfirm
knott -S visual-studio-code # prefers visual-studio-code-bin if available
knott -Si shellcheck-bin    # package info
knott -G shellcheck-bin     # clone/update PKGBUILD
knott -Gp shellcheck-bin    # print PKGBUILD
knott -Qm                   # foreign packages
knott -Qua --aur            # AUR updates
knott --diagnostics         # resource limits and process diagnostics
knott --keys                # update keys, rank safe US mirrors, then upgrade
knott --keys Germany 432705FACDD40325 # pick mirror country and import key
knott --resume              # resume interrupted transaction
knott --repair              # check pacman state, then resume safely
knott --abort               # discard saved plan without rollback
knott --help                # command help
knott --version             # version

Interrupted transactions

If Knott is interrupted during an upgrade, rerun:

knott --resume

If the interruption happened during the repo/pacman phase, finish pacman first:

sudo pacman -Syu
knott --resume

For guided checks:

knott --repair

To discard Knott's saved plan without rolling back installed packages:

knott --abort

Keys And Mirrors

knott --keys imports AUR PGP keys from the active transaction build dirs, updates pacman's Arch keyring the way Arch expects, ranks safe mirrors with reflector, and syncs again against the new mirrorlist. The default mirror country is United States.

For pacman package keys, Knott first syncs archlinux-keyring and reflector, then runs pacman-key --init, pacman-key --populate archlinux, and pacman-key --updatedb. It does not use keyservers as the primary trust path for official package keys.

The default mirror policy is IPv4 HTTPS only, recently synced within 12 hours, reported sync delay of 1 hour or less, 100% completion, 5 second connection and download timeouts, top 25 by MirrorStatus score and freshness, speed-tested with 4 threads, keep the fastest 8, sorted by rate. After saving the mirrorlist, Knott runs a forced database refresh and system upgrade.

Reflector writes to a temporary mirrorlist first. Knott captures reflector's per-mirror failures, reports a short summary, validates HTTPS Server entries, then installs the mirrorlist to /etc/pacman.d/mirrorlist as root.

Pass a country as the first argument to choose another mirror location:

knott --keys Germany
knott --keys South Korea

Pass key IDs after the country, or as the first argument when using the default country:

knott --keys 432705FACDD40325
knott --keys Germany 432705FACDD40325

Knott imports AUR keys into the user's GPG keyring with gpg --recv-keys. It only imports long/full hex key IDs, and it does not disable makepkg signature checks.

Resource Limits

• AUR info RPC requests are batched in chunks of 150 package names.
• AUR info cache is capped at 4096 packages per process.
• AUR search cache is capped at 128 search entries per process.
• Search result sets larger than 2048 packages are returned but not cached.
• PKGBUILD responses are capped at 1 MiB, with Content-Length rejected early when the server provides it.
• AUR dependency resolution is capped at 4096 packages per graph.
• Local pacman desc files are read with a 1 MiB per-file limit.
• knott does not spawn background Tokio tasks or use channels; child processes are awaited directly.

Use knott --diagnostics to print the active limits and current RSS where the platform exposes it.

Output Safety

• Package metadata, search results, info output, status lines, errors, warnings, prompts, and dry-run command echoes go through sanitized output helpers before printing to a terminal.
• Sanitization strips ANSI escape sequences and control characters while keeping normal Unicode text, tabs, and line breaks where appropriate.
• knott -Gp prints raw PKGBUILD data intentionally so it remains suitable for redirection and inspection.
• Progress loaders use aisling's tqdm loader on stderr only when stderr is a TTY. --quiet, --no-progress, or KNOTT_PROGRESS=0 disable them.

Environment

• KNOTT_AUR_URL: AUR base URL, defaults to https://aur.archlinux.org.
• KNOTT_BUILDDIR: AUR build cache, defaults to $XDG_CACHE_HOME/knott/build.
• KNOTT_PACMAN: pacman executable, defaults to pacman.
• KNOTT_PACMAN_KEY: pacman-key executable, defaults to pacman-key.
• KNOTT_MAKEPKG: makepkg executable, defaults to makepkg.
• KNOTT_GIT: git executable, defaults to git.
• KNOTT_GPG: gpg executable, defaults to gpg.
• KNOTT_REFLECTOR: reflector executable, defaults to reflector.
• KNOTT_SUDO: privilege escalation command, defaults to sudo.
• KNOTT_PROGRESS: set to 0, false, or off to disable progress loaders; values are trimmed and matched case-insensitively.
• Transaction state is stored under $XDG_STATE_HOME/knott, falling back to $HOME/.local/state/knott. The active pointer is current.json, transaction history is under transactions/, and the Knott lock uses $XDG_RUNTIME_DIR when available.

Verification

cargo fmt --check
cargo clippy --all-targets -- -D warnings
cargo test

Maintenance

• Bump the patch version for every project change, and keep Cargo.toml, Cargo.lock, and README install examples on the same version.
• Keep README.md, knott --help output in src/cli.rs, and CLI parser tests synced whenever commands or options change.
• Keep all caches, dependency graphs, and file reads bounded; update the Resource Limits section and knott --diagnostics output when limits change.
• Before publishing, verify the package and install path:

cargo package
cargo install --path . --locked --root /tmp/knott-install-check --force
/tmp/knott-install-check/bin/knott --version
/tmp/knott-install-check/bin/knott --help
/tmp/knott-install-check/bin/knott --diagnostics