# 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
```sh
cargo install --path . --locked
knott --version
```
Install the published crate from crates.io:
```sh
cargo install knott --locked
# or pin it explicitly:
cargo install knott --version 0.1.17 --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
```sh
cargo build --release
./target/release/knott --help
```
## Commands
```sh
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:
```sh
knott --resume
```
If the interruption happened during the repo/pacman phase, finish pacman first:
```sh
sudo pacman -Syu
knott --resume
```
For guided checks:
```sh
knott --repair
```
To discard Knott's saved plan without rolling back installed packages:
```sh
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:
```sh
knott --keys Germany
knott --keys South Korea
```
Pass key IDs after the country, or as the first argument when using the default
country:
```sh
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_DBPATH`: pacman database root, defaults to `/var/lib/pacman`.
- `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
```sh
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:
```sh
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
```