aam pack (deprecated)¶

Package Authoring

Synopsis¶

aam pkg pack [PATH]

Description¶

Build a distributable .aam archive from a validated package. Creates a gzipped tar archive containing the package manifest, all artifacts, and supporting files. The archive can be published to a registry or shared manually.

Runs validation automatically before packing. Maximum archive size is 50 MB.

Arguments¶

Options¶

This command has no command-specific options.

Examples¶

Example 1: Pack Current Directory¶

aam pkg pack

Output:

Building my-package@1.0.0...
  Adding aam.yaml
  Adding skills/my-skill/
  Adding agents/my-agent/
  Adding prompts/welcome.md

✓ Built my-package-1.0.0.aam (127.3 KB)
  Checksum: sha256:a1b2c3d4e5f6789...

Example 2: Pack Specific Directory¶

aam pkg pack ./my-package/

Creates archive in the package directory.

Example 3: Scoped Package¶

cd my-scoped-package
aam pkg pack

Output:

Building @author/my-package@2.0.0...
  Adding aam.yaml
  Adding skills/advanced-skill/

✓ Built author-my-package-2.0.0.aam (45.2 KB)
  Checksum: sha256:9f8e7d6c5b4a321...

Example 4: Validation Failure¶

aam pkg pack

Output:

Error: Package validation failed. Run 'aam pkg validate' for details.
  ✗ Missing: agents/broken-agent/

Example 5: Large Package¶

aam pkg pack

Output:

Building large-package@1.0.0...
  Adding aam.yaml
  Adding skills/skill-1/
  Adding skills/skill-2/
  Adding skills/skill-3/
  Adding assets/large-file.pdf
  Adding assets/documentation/

✓ Built large-package-1.0.0.aam (15.8 MB)
  Checksum: sha256:1a2b3c4d5e6f7g8...

Example 6: Minimal Package¶

aam pkg pack

Output:

Building minimal-skill@0.1.0...
  Adding aam.yaml
  Adding skills/simple-skill/

✓ Built minimal-skill-0.1.0.aam (8.5 KB)
  Checksum: sha256:7h8i9j0k1l2m3n4...

Exit Codes¶

Archive Details¶

Archive Name Format¶

Unscoped packages:

package-name-1.0.0.aam

Scoped packages:

scope-package-name-1.0.0.aam

Note: The @ symbol is removed from scoped package archives.

Archive Contents¶

The .aam archive contains:

• aam.yaml - Package manifest
• All artifact directories and files
• Supporting files referenced by artifacts
• README.md (if present)
• LICENSE (if present)

Excluded Files¶

The following are automatically excluded:

• .git/ directory
• .aam/ directory (workspace files)
• node_modules/
• __pycache__/
• .DS_Store
• Temporary files (.tmp, .temp)
• Archive files (*.aam)

Maximum Size¶

Archives are limited to 50 MB. If your package exceeds this:

Error: Archive size exceeds 50 MB limit (actual: 65.3 MB)

Solutions:

• Remove large binary files
• Move documentation to repository
• Split into multiple packages
• Use external asset hosting

Related Commands¶

• aam pkg validate - Validate before packing
• aam pkg publish - Publish the archive to a registry
• aam install - Install from an archive file

Notes¶

Automatic Validation¶

The pack command runs validation automatically. If validation fails, packing is aborted. You can pre-validate with:

aam pkg validate && aam pkg pack

Checksum¶

The SHA-256 checksum is calculated for integrity verification. Registries use this to verify uploads, and aam install uses it to verify downloads.

Archive Format¶

Archives use the .aam extension but are standard gzipped tar files (tar.gz). You can inspect them with:

tar -tzf my-package-1.0.0.aam

Extract manually:

tar -xzf my-package-1.0.0.aam -C ./extracted/

Version in Filename¶

The archive filename includes the version from aam.yaml. Ensure the version is correct before packing:

version: 1.0.0

Reproducible Builds¶

Archives are deterministic - packing the same package multiple times produces identical checksums (excluding timestamps).

Publishing Workflow¶

Typical workflow:

# 1. Validate package
aam pkg validate

# 2. Pack archive
aam pkg pack

# 3. Publish to registry
aam pkg publish

# Or combine:
aam pkg validate && aam pkg pack && aam pkg publish

Local Installation¶

You can install directly from the packed archive without publishing:

aam pkg pack
aam install ./my-package-1.0.0.aam

Useful for testing before publishing.

CI/CD Integration¶

Example GitHub Actions workflow:

- name: Pack package
  run: aam pkg pack

- name: Upload artifact
  uses: actions/upload-artifact@v3
  with:
    name: package-archive
    path: '*.aam'