aux4/pkger

The official aux4 package manager.

aux4/pkger is the core package management system for the aux4 ecosystem. It enables you to discover, install, manage, and publish aux4 packages from the aux4 hub. Whether you're using existing packages to extend your CLI capabilities or creating and sharing your own packages, aux4/pkger provides all the tools you need.

The package manager also handles system-level dependencies, automatically installing required tools from package managers like brew, apt, pkgx, or npm when packages need them.

Installation

aux4 aux4 pkger install aux4/pkger

Quick Start

List all installed packages:

aux4 aux4 pkger list

Managing Packages

Installing Packages

Install a package from the aux4 hub:

aux4 aux4 pkger install scope/package-name

Install several packages at once:

aux4 aux4 pkger install aux4/2table aux4/adapter aux4/config

Install from a specific repository:

aux4 aux4 pkger install scope/package-name --repository private

Install from a local file:

aux4 aux4 pkger install --fromFile ./my-package.tar.gz

Force a reinstall or downgrade. --force overrides the currently installed version regardless of dependencies, so you can reinstall a package or drop to an older version without first uninstalling everything that depends on it:

aux4 aux4 pkger install scope/package-name@1.2.0 --force

Listing Installed Packages

View all installed packages:

aux4 aux4 pkger list

Filter packages by name:

aux4 aux4 pkger list --filter aws

Show packages with their dependencies:

aux4 aux4 pkger list --showDependencies

Finding Commands

list and search answer "which packages exist"; find answers "which command do I run". It searches the documentation of everything installed — each package README and every command man page — and returns runnable command lines:

aux4 aux4 pkger find "get a configuration value"

aux4 config get  (aux4/config)
If file is not provided it will look for a file named config.yaml, config.yml, or config.json in the current directory.

aux4 config set  (aux4/config)
If file is not provided it will look for a file named config.yaml, config.yml, or config.json in the current directory.

The first line of each result is the exact command to run, with its package beside it; the line below is a short description from its documentation. Search by what you want to do rather than by package name — pkger list --filter returns package names, which are not commands.

Limit the number of results:

aux4 aux4 pkger find "send an email" --limit 3

The index lives at ~/.aux4.config/.pkg-index/index.json. You should never need to manage it: it is built lazily the first time you search, and rebuilt automatically whenever your set of installed packages has changed, by comparing the index against the package ledger. Installing and uninstalling also rebuild it ahead of time, so the cost rarely lands on a search. To force a rebuild:

aux4 aux4 pkger reindex

Viewing Package Documentation

Display the manual for a package:

aux4 aux4 pkger man aux4/aws

Open documentation in your browser:

aux4 aux4 pkger man aux4/aws --browser

Output raw markdown:

aux4 aux4 pkger man aux4/aws --markdown

Uninstalling Packages

Remove an installed package:

aux4 aux4 pkger uninstall scope/package-name

Remove several packages at once:

aux4 aux4 pkger uninstall aux4/2table aux4/adapter

Force the removal of a package even when other packages still depend on it. --force cascades: the package and every package that depends on it (directly or transitively) are removed together, so the package database is never left with a dangling reference:

aux4 aux4 pkger uninstall scope/package-name --force

Verifying Installed Packages

verify checks installed packages against the hub's authoritative per-file integrity manifest for the exact version that is installed. At publish time the hub records a SHA-256 of every file shipped in a package (the .aux4, the dist/ binaries, and lib/*.mjs), keyed by platform. verify fetches that manifest over HTTPS for the pinned version recorded in the lockfile (all.json) — never latest — re-hashes the files on disk, and compares them to the hub's copy. This detects post-install local tampering by anchoring the check to a trusted remote reference. Packages are fetched and hashed in parallel:

aux4 aux4 pkger verify

Verifying installed packages against the hub...
 ✓ aux4/aux4 5.1.29 (matches hub)
 ✓ aux4/config 1.0.0 (matches hub)
Rebuilding global.aux4 from verified sources...
 ✓ global.aux4 rebuilt
Summary: 2 verified, 0 unverifiable, 0 FAILED

Each package is reported as ✓ OK (matches hub), ! unverifiable (no hub reference for the pinned version — the package/version is not on the hub, or the hub returned no manifest), or x CHANGED (a changed, missing, or extra file, a missing directory, or a version that disagrees with the lockfile). When every package verifies cleanly, verify re-derives global.aux4 from the verified sources; if verification fails, it refuses to rebuild from unverified sources and exits non-zero.

Strict vs --soft: by default verify is strict and fail-closed — a mismatch fails, and an unverifiable package also fails. With --soft, a genuine mismatch still fails (a real tamper is never hidden), but an unverifiable package is tolerated as a warning and its files are compared against the local install-time manifest to report drift (local drift: none or the drifted files):

aux4 aux4 pkger verify --soft

Note: until the hub ships per-file manifests and the existing catalog is backfilled, most packages have no hub manifest yet and are reported as unverifiable. During that window, use --soft to tolerate unverifiable packages while still catching genuine tampering.

Note: on macOS the installer ad-hoc codesigns dist/darwin/** binaries after extraction, which mutates them, so their on-disk hash cannot match the hub manifest. verify does not hard-fail those files; it reconciles them against the local install-time manifest and labels them codesigned locally, hub re-hash n/a. Every other file stays hub-anchored.

Pass a filter to verify only a subset of packages. This is a diagnostic mode: it checks the matching packages but intentionally skips the global.aux4 rebuild, since only part of the tree was verified:

aux4 aux4 pkger verify aux4/config

Building and Publishing Packages

Building a Package

Build a package including specific files:

aux4 aux4 pkger build .aux4 LICENSE README.md

Build a package including all files in the current directory:

aux4 aux4 pkger build .

Specify an output directory:

aux4 aux4 pkger build . --out ./dist

The build command generates a .tar.gz package file ready for publishing.

Package Structure

Your package must include a .aux4 configuration file:

{
  "scope": "your-scope",
  "name": "package-name",
  "version": "1.0.0",
  "description": "Your package description",
  "license": "MIT",
  "dependencies": [
    "aux4/aux4"
  ],
  "profiles": [
    ...
  ]
}

Include a LICENSE file and a README.md for documentation.

Publishing a Package

First, login to the aux4 hub:

aux4 aux4 login

You can create an aux4 account if you don't have one.

Then publish your package:

aux4 aux4 pkger publish my-package-1.0.0.tar.gz

Publish to a specific repository:

aux4 aux4 pkger publish my-package-1.0.0.tar.gz --repository private

Logout when finished:

aux4 aux4 logout

System Dependencies

aux4/pkger can automatically manage system-level dependencies for packages. When a package requires external tools, the system installer handles installation automatically.

Declaring System Dependencies

In your .aux4 file, specify system dependencies:

{
  "scope": "your-scope",
  "name": "package-name",
  "version": "1.0.0",
  "system": [
    ["test:aws --version", "pkgx:aws", "brew:awscli"],
    ["test:jq --version", "pkgx:jq", "brew:jq"]
  ],
  "profiles": [
    ...
  ]
}

Each dependency is an array containing:

• A test command to check if the package is already installed
• One or more installation options for different package managers

Available System Installers

Users need one of these system installers to install packages with system dependencies:

• brew - Homebrew for macOS/Linux
• apt - APT for Debian/Ubuntu
• pkgx - pkgx universal package manager
• npm - Node.js packages

Managing System Packages Manually

Install a system package:

aux4 aux4 pkger system brew install jq

Uninstall a system package:

aux4 aux4 pkger system brew uninstall jq

Package Documentation

Command Documentation

Add documentation for specific commands by creating markdown files in a man/ directory:

man/<profile_name>__<command_name>.md

Replace colons in profile names with underscores. For example, documentation for the build command in the aux4:pkger profile would be:

man/aux4_pkger__build.md

Command Examples

Include usage examples by creating test files in a test/ directory:

test/<profile_name>__<command_name>.test.md

License

This package is licensed under a Commercial License.

See LICENSE for details.