# 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:

```text
my-package/
├── .aux4         # Package metadata and commands (REQUIRED)
├── LICENSE       # License file (REQUIRED)
├── README.md     # Package documentation (REQUIRED)
├── RELEASE.md    # Release notes for this version (recommended)
└── lib/          # Additional files (optional)
    └── script.js
```

## Step 1: Create the Package

### Create the directory structure

```bash
mkdir -p my-greeter/lib
cd my-greeter
```

### Create the .aux4 file

Create the `.aux4` file with your package metadata and commands:

```json
{
  "scope": "myorg",
  "name": "greeter",
  "version": "1.0.0",
  "description": "A simple greeting command",
  "license": "MIT",
  "tags": ["greeting", "hello"],
  "profiles": [
    {
      "name": "main",
      "commands": [
        {
          "name": "greet",
          "execute": [
            "profile:greet"
          ],
          "help": {
            "text": "Greeting commands"
          }
        }
      ]
    },
    {
      "name": "greet",
      "commands": [
        {
          "name": "hello",
          "execute": [
            "echo \"Hello, ${name}!\""
          ],
          "help": {
            "text": "Say hello to someone",
            "variables": [
              {
                "name": "name",
                "text": "Name to greet",
                "default": "World"
              }
            ]
          }
        },
        {
          "name": "goodbye",
          "execute": [
            "echo \"Goodbye, ${name}!\""
          ],
          "help": {
            "text": "Say goodbye to someone",
            "variables": [
              {
                "name": "name",
                "text": "Name to say goodbye to",
                "default": "World"
              }
            ]
          }
        }
      ]
    }
  ]
}
```

### Create the LICENSE file

```bash
cat > LICENSE << 'EOF'
MIT License

Copyright (c) 2024 MyOrg

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
EOF
```

**Tip:** You can also 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 "MyOrg" \
  --year 2024 \
  --project "greeter"
```

### Create the README.md file

````bash
cat > README.md << 'EOF'
# Greeter

A simple greeting command for aux4.

## Usage

Say hello:

```bash
aux4 greet hello --name John
```

Say goodbye:

```bash
aux4 greet goodbye --name John
```
EOF
````

## Step 2: Test Locally

Before building, test your package locally by loading the `.aux4` file:

```bash
aux4 greet hello --name John
```

```text
Hello, John!
```

## Step 3: Build the Package

Build the package using the `aux4 aux4 pkger build` command:

```bash
aux4 aux4 pkger build ./out .
```

This creates:

```text
out/
└── myorg_greeter_1.0.0.zip
```

## Step 4: Install from File (Local Testing)

Before publishing, you can test the built package by installing it from the file:

```bash
aux4 aux4 pkger install --fromFile ./out/myorg_greeter_1.0.0.zip
```

Verify the installation:

```bash
aux4 greet hello --name "Local Test"
```

```text
Hello, Local Test!
```

## Step 5: Publish the Package

### Login to aux4 Hub

First, authenticate with your aux4 account:

```bash
aux4 aux4 login
```

This opens a browser for OAuth authentication.

### Publish

Upload your package to the aux4 Hub:

```bash
aux4 aux4 pkger publish ./out/myorg_greeter_1.0.0.zip
```

## Step 6: Install from aux4 Hub

Once published, anyone can install your package:

```bash
aux4 aux4 pkger install myorg/greeter
```

Or install a specific version:

```bash
aux4 aux4 pkger install myorg/greeter@1.0.0
```

## Step 7: Use the Package

After installation, the commands are available:

```bash
aux4 greet hello --name World
```

```text
Hello, World!
```

## Uninstall

To remove the package:

```bash
aux4 aux4 pkger uninstall myorg/greeter
```

This 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](/packaging/js-package).

---

## See Also

- [Simple JS Package](/packaging/js-package)
- [Package with Dependencies](/packaging/dependencies)
- [Package with System Dependencies](/packaging/system-dependencies)
- [Multi-Platform Package](/packaging/multi-platform)