# Packaging

aux4 allows you to package your CLI tools and distribute them to your team or the community through the [aux4 Hub](https://hub.aux4.io).

## Installation

Install [aux4/pkger](https://hub.aux4.io/r/public/packages/aux4/pkger):

```bash
curl https://pkger.aux4.sh | sh
```

## Getting Started

- [Simple Package](/packaging/simple) - Create, build, publish, and install a basic package using only `.aux4`, no scripts or binaries
- [Simple JS Package](/packaging/js-package) - Bundle a Node.js script instead of plain shell commands
- [Package with Dependencies](/packaging/dependencies) - Add aux4 package dependencies
- [Package with System Dependencies](/packaging/system-dependencies) - Add system-level dependencies (Node.js, Python, etc.)
- [Creating System Installers](/packaging/system-installer) - Build custom system installers for new package managers
- [Multi-Platform Package](/packaging/multi-platform) - Create packages with platform-specific binaries or command overrides

## Package Structure

A valid aux4 package requires the following structure:

```text
package/
├── .aux4                 # Package metadata (REQUIRED)
├── LICENSE               # License file (REQUIRED)
├── README.md             # Package documentation (REQUIRED)
├── RELEASE.md            # Release notes for this version (recommended)
├── man/                  # Command documentation (optional)
│   └── <profile>__<command>.md
├── test/                 # Command examples (optional)
│   └── <profile>__<command>.test.md
├── dist/                 # Platform-specific binaries (optional)
│   ├── darwin/
│   │   ├── amd64/
│   │   └── arm64/
│   ├── linux/
│   │   ├── amd64/
│   │   ├── arm64/
│   │   └── 386/
│   └── windows/
│       ├── amd64/
│       ├── arm64/
│       └── 386/
└── lib/                  # Additional files (optional)
```

## Package Metadata (.aux4)

The `.aux4` file contains package metadata and command definitions:

```json
{
  "scope": "<scope>",
  "name": "<name>",
  "version": "<version>",
  "description": "<description>",
  "license": "<license>",
  "git": "<repository_url>",
  "tags": ["<tag1>", "<tag2>"],
  "dependencies": ["<scope/name@version>"],
  "system": [
    ["test:<command>", "<packager>:<package>"]
  ],
  "profiles": [...]
}
```

### Required Fields

| Field | Description |
|-------|-------------|
| `scope` | Organization or user namespace. Must match a scope in your [aux4 account](https://user.aux4.io). |
| `name` | Unique package identifier within the scope. |
| `version` | Semantic version ([SemVer](https://semver.org)): `MAJOR.MINOR.PATCH` |
| `license` | License type. Must match the `LICENSE` file. |

### Optional Fields

| Field | Description |
|-------|-------------|
| `description` | Brief description of the package. |
| `git` | Git repository URL. |
| `tags` | Keywords for package discovery. |
| `dependencies` | Array of aux4 package dependencies. See [Package with Dependencies](/packaging/dependencies). |
| `system` | Array of system-level dependencies. See [Package with System Dependencies](/packaging/system-dependencies). |

## Supported System Package Managers

- [`brew`](https://hub.aux4.io/r/public/packages/aux4/system-installer-brew): Homebrew (macOS)
- [`apt`](https://hub.aux4.io/r/public/packages/aux4/system-installer-apt): APT (Debian/Ubuntu)
- [`dnf`](https://hub.aux4.io/r/public/packages/aux4/system-installer-dnf): DNF (Fedora/RHEL)
- [`yum`](https://hub.aux4.io/r/public/packages/aux4/system-installer-yum): YUM (CentOS/RHEL)
- [`apk`](https://hub.aux4.io/r/public/packages/aux4/system-installer-apk): APK (Alpine Linux)
- [`npm`](https://hub.aux4.io/r/public/packages/aux4/system-installer-npm): Node Package Manager
- [`pkgx`](https://hub.aux4.io/r/public/packages/aux4/system-installer-pkgx): pkgx package manager
- [`linux`](https://hub.aux4.io/r/public/search?q=linux): Generic alias used by all Linux package managers (apt, dnf, yum, apk)

## Package Directory Variable

Use [`${packageDir}`](/variables#package-directory-variable) in execute commands to reference files within your installed package:

```json
{
  "execute": [
    "node ${packageDir}/lib/my-script.js",
    "${packageDir}/bin/my-binary"
  ]
}
```

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.

```markdown
# Release notes

## Package discovery is now built in

`aux4 aux4 pkger find "<what you want to do>"` searches installed packages and their commands,
and returns runnable command lines rather than package names.

The 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](https://hub.aux4.io/r/public/packages/aux4/license) to generate your LICENSE file:

```bash
# List available open source licenses
> aux4 license list

# Generate a LICENSE file
> aux4 license use \
  --name mit \
  --owner "Alice Doe" \
  --year 2023 \
  --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](/testing).

## Quick Reference

For full details on each command, see the [Package Manager](/package-manager) page.

### Build

```bash
> aux4 aux4 pkger build <output_dir> <source_dir>
```

### Login

```bash
> aux4 aux4 login
```

### Publish

```bash
> aux4 aux4 pkger publish <package.zip>
```

### Install from Hub

```bash
> aux4 aux4 pkger install <scope>/<name>
> aux4 aux4 pkger install <scope>/<name>@<version>
```

### Install from File

```bash
> 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

```bash
> aux4 aux4 pkger list
```

### View Documentation

```bash
> aux4 aux4 pkger man <scope>/<name>
```

### Uninstall

```bash
> aux4 aux4 pkger uninstall <scope>/<name>
```

### Logout

```bash
> aux4 aux4 logout
```

## Package Installation Location

Packages are installed to:

```text
~/.aux4.config/packages/<scope>/<name>/
```

---

## See Also

- [Commands](/commands)
- [Variables](/variables)
- [Testing](/testing)
- [Package Manager](/package-manager)
- [Docker](/docker)