aux4
Documentation
Home
Getting Started
Installation
IDEs
Variables
Executors
Functions
Configuration
Commands
Hooks
Security
Render
Testing
Package Manager
Packaging
GitHub Actions
Docker

Packaging

aux4 allows you to package your CLI tools and distribute them to your team or the community through the aux4 Hub.

Installation

Install aux4/pkger:

1curl https://pkger.aux4.sh | sh

Getting Started

Package Structure

A valid aux4 package requires the following structure:

1package/ 2├── .aux4 # Package metadata (REQUIRED) 3├── LICENSE # License file (REQUIRED) 4├── README.md # Package documentation (REQUIRED) 5├── RELEASE.md # Release notes for this version (recommended) 6├── man/ # Command documentation (optional) 7│ └── <profile>__<command>.md 8├── test/ # Command examples (optional) 9│ └── <profile>__<command>.test.md 10├── dist/ # Platform-specific binaries (optional) 11│ ├── darwin/ 12│ │ ├── amd64/ 13│ │ └── arm64/ 14│ ├── linux/ 15│ │ ├── amd64/ 16│ │ ├── arm64/ 17│ │ └── 386/ 18│ └── windows/ 19│ ├── amd64/ 20│ ├── arm64/ 21│ └── 386/ 22└── lib/ # Additional files (optional)

Package Metadata (.aux4)

The .aux4 file contains package metadata and command definitions:

1{ 2 "scope": "<scope>", 3 "name": "<name>", 4 "version": "<version>", 5 "description": "<description>", 6 "license": "<license>", 7 "git": "<repository_url>", 8 "tags": ["<tag1>", "<tag2>"], 9 "dependencies": ["<scope/name@version>"], 10 "system": [ 11 ["test:<command>", "<packager>:<package>"] 12 ], 13 "profiles": [...] 14}

Required Fields

FieldDescription
scopeOrganization or user namespace. Must match a scope in your aux4 account.
nameUnique package identifier within the scope.
versionSemantic version (SemVer): MAJOR.MINOR.PATCH
licenseLicense type. Must match the LICENSE file.

Optional Fields

FieldDescription
descriptionBrief description of the package.
gitGit repository URL.
tagsKeywords for package discovery.
dependenciesArray of aux4 package dependencies. See Package with Dependencies.
systemArray of system-level dependencies. See Package with System Dependencies.

Supported System Package Managers

  • brew: Homebrew (macOS)
  • apt: APT (Debian/Ubuntu)
  • dnf: DNF (Fedora/RHEL)
  • yum: YUM (CentOS/RHEL)
  • apk: APK (Alpine Linux)
  • npm: Node Package Manager
  • pkgx: pkgx package manager
  • linux: Generic alias used by all Linux package managers (apt, dnf, yum, apk)

Package Directory Variable

Use ${packageDir} in execute commands to reference files within your installed package:

1{ 2 "execute": [ 3 "node ${packageDir}/lib/my-script.js", 4 "${packageDir}/bin/my-binary" 5 ] 6}

This resolves to: ~/.aux4.config/packages/<scope>/<name>/

Package Documentation

README.md

Create a README.md file in your package root. This is displayed on the aux4 Hub.

RELEASE.md

Create a RELEASE.md file in your package root describing the version you are publishing.

pkger does not require it — a build succeeds without one — but it is the expected convention for every aux4 package, so treat it as part of a complete release.

It is not a cumulative changelog. It is overwritten on every version and covers only what is in the release going out now — a changelog grows stale because nobody rewrites history in it, while a per-version file stays short enough that it actually gets written.

1# Release notes 2 3## Package discovery is now built in 4 5`aux4 aux4 pkger find "<what you want to do>"` searches installed packages and their commands, 6and returns runnable command lines rather than package names. 7 8The command path is unchanged, so nothing that already used it needs updating.

Write it for someone using the package: what changed, and what they do differently as a result. Not a summary of the diff.

Update it in the same commit as the change you are describing, alongside the README and man pages — leaving it until publish time means writing it once the reasoning has faded.

LICENSE

Use aux4/license to generate your LICENSE file:

1# List available open source licenses 2> aux4 license list 3 4# Generate a LICENSE file 5> aux4 license use \ 6 --name mit \ 7 --owner "Alice Doe" \ 8 --year 2023 \ 9 --project "my-awesome-project"

Command Manuals

Add documentation for commands in man/<profile>__<command>.md.

Command Examples

Add test files in test/<profile>__<command>.test.md. See Testing.

Quick Reference

For full details on each command, see the Package Manager page.

Build

1> aux4 aux4 pkger build <output_dir> <source_dir>

Login

1> aux4 aux4 login

Publish

1> aux4 aux4 pkger publish <package.zip>

Install from Hub

1> aux4 aux4 pkger install <scope>/<name> 2> aux4 aux4 pkger install <scope>/<name>@<version>

Install from File

1> aux4 aux4 pkger install --fromFile <package.zip>

For multi-platform packages, use the platform-specific zip file (e.g., darwin_arm64_myorg_tool_1.0.0.zip), not the main zip.

List Installed Packages

1> aux4 aux4 pkger list

View Documentation

1> aux4 aux4 pkger man <scope>/<name>

Uninstall

1> aux4 aux4 pkger uninstall <scope>/<name>

Logout

1> aux4 aux4 logout

Package Installation Location

Packages are installed to:

1~/.aux4.config/packages/<scope>/<name>/

See Also