hkp

A collection of housekeeping tools to manage files and folders, set permissions, combine and crop PDF files — packaged as a single hk binary written in Rust.

usage

hk — housekeeping tools

usage: hk <command> [argument]

commands:
  cmbi   combine all PDF files in the current folder
  cmbs   combine PDF files per subfolder
  crop   crop PDF header/footer (--top/--bott N inches, default 1.0)
  fffp [--yes] [--all]
         fix permissions: dirs 755, files 644 (keeps +x, skips private)
  sffn   sanitise folder and file names
  help   show this help

crop can take more than one pdf file, e.g.,

hk crop --top 1.5 --bott 0.5 file-1.pdf file-2.pdf ... file-n.pdf

For a single file, the command can simply be:

hk crop --top 1.5 --bott 0.5 file.pdf

install

prebuilt binaries

Download the archive for your system from Releases, extract it, and put hk (or hk.exe) somewhere on your PATH:

system	archive
Windows (x86-64)	hk-<version>-windows-x86_64.zip
macOS (Apple silicon, M-series)	hk-<version>-macos-arm64.tar.gz
Raspberry Pi 5 (64-bit Pi OS/Linux)	hk-<version>-linux-arm64-rpi5.tar.gz
Linux x86-64 (any distro)	hk-<version>-linux-x86_64.tar.gz

The binaries are not code-signed or notarized, so macOS will block hk on first run. Before overriding that, verify the download (see releases), then clear the quarantine flag: xattr -d com.apple.quarantine hk.

For macOS (Apple silicon) and Linux (x86-64, arm64), a bash install script inst.sh is provided. It detects the OS and CPU it runs on, and does the following:

1. Downloads the latest release for that system
2. Verifies the download against its hash in SHA256SUMS.txt
3. If the hash matches, extracts the hk binary (otherwise stops)
4. Clears the quarantine flag (macOS only)
5. Installs hk to /usr/local/bin (uses sudo if needed)

Run it as follows from a terminal (be sure to check the script, if unsure):

curl --proto '=https' --tlsv1.2 -sSfL https://raw.githubusercontent.com/ckunte/hk/refs/heads/master/inst.sh | bash

from source

Rust is required to build hk. Install it via rustup:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Then, from a clone of this repository, build and install the binary:

cargo install --path . --locked

After that, hk <command> is available anywhere.

dependencies

None — hk is a single self-contained binary.

notes

• cmbi and cmbs use pure Rust (lopdf) — no Ghostscript needed for combining PDFs. Re-running them replaces the previous *-comb.pdf without merging it into itself; the output is written atomically, inputs over 1 GiB or malformed files are reported as errors, and cmbs carries on past a failing folder
• sffn skips any rename whose target already exists, and reports it
• sffn sanitises folder names and the names of document (pdf, doc/docx, typ, xls/xlsx, ppt/pptx, odt/ods/odp, rtf, txt, md, csv, epub, pages/numbers/key), image (jpg, png, gif, webp, heic, tiff, bmp, svg), audio (mp3, wav, flac, m4a, aac, ogg) and video (mp4, mov, mkv, avi, webm, m4v) files natively — no fd, detox, or rename needed. Other files and hidden files are left alone. The list is SANITISE_EXTS in src/main.rs
• fffp is pure Rust — no shell tools needed (macOS / Linux only; not available on Windows). It asks for confirmation (--yes to skip), refuses to run in / or your home folder, keeps the executable bit on files that already have it (755), and skips private entries with no group/other access (such as 600 keys) unless you pass --all

releases

Release archives are built from a tagged commit, listed with checksums in SHA256SUMS.txt, and carry signed build provenance. Verify a download with:

gh attestation verify hk-<version>-<system>.tar.gz --repo ckunte/hkp