Simple Package
This guide walks you through creating, building, publishing, and installing a simple aux4 package — using only .aux4 and plain shell commands, no external scripts or compiled binaries.
Package Structure
A simple package contains the following files:
1my-package/
2├── .aux4 # Package metadata and commands (REQUIRED)
3├── LICENSE # License file (REQUIRED)
4├── README.md # Package documentation (REQUIRED)
5├── RELEASE.md # Release notes for this version (recommended)
6└── lib/ # Additional files (optional)
7 └── script.jsStep 1: Create the Package
Create the directory structure
1mkdir -p my-greeter/lib
2cd my-greeterCreate the .aux4 file
Create the .aux4 file with your package metadata and commands:
1{
2 "scope": "myorg",
3 "name": "greeter",
4 "version": "1.0.0",
5 "description": "A simple greeting command",
6 "license": "MIT",
7 "tags": ["greeting", "hello"],
8 "profiles": [
9 {
10 "name": "main",
11 "commands": [
12 {
13 "name": "greet",
14 "execute": [
15 "profile:greet"
16 ],
17 "help": {
18 "text": "Greeting commands"
19 }
20 }
21 ]
22 },
23 {
24 "name": "greet",
25 "commands": [
26 {
27 "name": "hello",
28 "execute": [
29 "echo \"Hello, ${name}!\""
30 ],
31 "help": {
32 "text": "Say hello to someone",
33 "variables": [
34 {
35 "name": "name",
36 "text": "Name to greet",
37 "default": "World"
38 }
39 ]
40 }
41 },
42 {
43 "name": "goodbye",
44 "execute": [
45 "echo \"Goodbye, ${name}!\""
46 ],
47 "help": {
48 "text": "Say goodbye to someone",
49 "variables": [
50 {
51 "name": "name",
52 "text": "Name to say goodbye to",
53 "default": "World"
54 }
55 ]
56 }
57 }
58 ]
59 }
60 ]
61}Create the LICENSE file
1cat > LICENSE << 'EOF'
2MIT License
3
4Copyright (c) 2024 MyOrg
5
6Permission is hereby granted, free of charge, to any person obtaining a copy
7of this software and associated documentation files (the "Software"), to deal
8in the Software without restriction, including without limitation the rights
9to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
10copies of the Software, and to permit persons to whom the Software is
11furnished to do so, subject to the following conditions:
12
13The above copyright notice and this permission notice shall be included in all
14copies or substantial portions of the Software.
15
16THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
22SOFTWARE.
23EOFTip: You can also use aux4/license to generate your LICENSE file:
1# List available open source licenses
2aux4 license list
3
4# Generate a LICENSE file
5aux4 license use \
6 --name mit \
7 --owner "MyOrg" \
8 --year 2024 \
9 --project "greeter"Create the README.md file
1cat > README.md << 'EOF'
2# Greeter
3
4A simple greeting command for aux4.
5
6## Usage
7
8Say hello:
9
10```bash
11aux4 greet hello --name John
12```
13
14Say goodbye:
15
16```bash
17aux4 greet goodbye --name John
18```
19EOFStep 2: Test Locally
Before building, test your package locally by loading the .aux4 file:
1aux4 greet hello --name John1Hello, John!Step 3: Build the Package
Build the package using the aux4 aux4 pkger build command:
1aux4 aux4 pkger build ./out .This creates:
1out/
2└── myorg_greeter_1.0.0.zipStep 4: Install from File (Local Testing)
Before publishing, you can test the built package by installing it from the file:
1aux4 aux4 pkger install --fromFile ./out/myorg_greeter_1.0.0.zipVerify the installation:
1aux4 greet hello --name "Local Test"1Hello, Local Test!Step 5: Publish the Package
Login to aux4 Hub
First, authenticate with your aux4 account:
1aux4 aux4 loginThis opens a browser for OAuth authentication.
Publish
Upload your package to the aux4 Hub:
1aux4 aux4 pkger publish ./out/myorg_greeter_1.0.0.zipStep 6: Install from aux4 Hub
Once published, anyone can install your package:
1aux4 aux4 pkger install myorg/greeterOr install a specific version:
1aux4 aux4 pkger install myorg/greeter@1.0.0Step 7: Use the Package
After installation, the commands are available:
1aux4 greet hello --name World1Hello, World!Uninstall
To remove the package:
1aux4 aux4 pkger uninstall myorg/greeterThis package never shells out to another language — every command is plain shell (echo, etc.) declared directly in .aux4. If you need to bundle an actual script instead, see Simple JS Package.