knott 0.1.9

Fast Rust package manager helper for Arch Linux repos and the AUR
Documentation

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.
  • 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.9 --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 -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 --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

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_MAKEPKG: makepkg executable, defaults to makepkg.
  • KNOTT_GIT: git executable, defaults to git.
  • 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