Getting Started with the AetherPak CLI#

1. Introduction#

AetherPak CLI is a standalone, performance-focused command-line tool for building, publishing, and managing Flatpak applications using OCI-backed distribution via GitHub Container Registry (GHCR) and static index hosting via GitHub Pages 1. Rather than treating your Flatpak workflow as a black box, the CLI exposes the full pipeline as composable, scriptable commands you can mix and match in any environment — local workstations, CI runners, or custom automation.

Plumbing vs. Porcelain#

The CLI follows a Plumbing vs. Porcelain design philosophy, modelled directly on Git 2 3:

• Plumbing (Primitives) — Independent, highly-scoped, single-responsibility commands suited for complex workflows and custom CI matrices. These include plan, build, import, push-oci, build-site, inspect-repo, and resolve-channel.
• Porcelain (Convenience Wrappers) — High-level commands that coordinate multiple plumbing modules automatically in-memory, providing a streamlined experience for the most common workflows. These include status, add, publish, and release.

The separation means you can use the high-level publish command for day-to-day work, but drop down to build + push-oci individually whenever you need fine-grained control — for example, to insert custom steps between build and publish, or to drive a dynamic CI matrix.

Configuration is Optional#

A key design principle of the CLI is that most commands work without a configuration file. You can pass all parameters as CLI flags or AETHERPAK_-prefixed environment variables (e.g. AETHERPAK_REGISTRY) 4. The aetherpak.yaml file becomes valuable when you want to manage multiple apps, persist defaults, or drive the automated plan/release cycle — but it is never required for one-off operations or quick testing.

2. Installation#

The AetherPak CLI is a single statically-linked binary for Linux (amd64 and arm64). There are two ways to get it: via the aetherpak/setup-cli GitHub Action for CI environments, or by downloading a release archive manually.

Using aetherpak/setup-cli (Recommended for CI)#

The setup-cli action downloads, extracts, and adds the aetherpak binary to $GITHUB_PATH in a single step 5. All composite actions in aetherpak/actions call this automatically when the CLI isn't already on PATH, but you can invoke it directly to pin a specific version.

- name: Set up AetherPak CLI
  uses: aetherpak/setup-cli@v1
  with:
    version: 'latest' # or a specific tag, e.g. 'v0.15.1'
    install-dependencies: 'true' # installs flatpak, ostree, flatpak-builder, etc.

Inputs 6:

The action is idempotent — if the requested version is already on PATH, it skips the download entirely 7. It supports Linux runners only (amd64 and arm64) and installs the binary to $RUNNER_TEMP/aetherpak-bin 8.

Tip: When you're using the aetherpak/actions reusable workflow, all composite actions call setup-cli automatically if the CLI isn't already on PATH. You only need to invoke setup-cli manually when pinning to a specific version or running on a bare ubuntu-latest runner without the AetherPak container.

To pin to a specific version and skip dependency installation (e.g. inside a container that already has the toolchain):

- uses: aetherpak/setup-cli@v1
  with:
    version: v0.15.1
    install-dependencies: 'false'

Manual Installation#

Pre-built release archives are published to github.com/aetherpak/cli/releases for every tagged release 9. Archives are named aetherpak-linux-amd64.tar.gz and aetherpak-linux-arm64.tar.gz.

# Example: download and install the latest release for amd64
VERSION=$(curl -s https://api.github.com/repos/aetherpak/cli/releases/latest \
  | grep '"tag_name"' | cut -d'"' -f4)
curl -sL "https://github.com/aetherpak/cli/releases/download/${VERSION}/aetherpak-linux-amd64.tar.gz" \
  | tar -xz
chmod +x aetherpak
sudo mv aetherpak /usr/local/bin/

Verify the installation:

aetherpak --version
aetherpak status

3. Zero-Config Commands#

Many AetherPak CLI commands work without a configuration file. Rather than requiring an aetherpak.yaml, they accept all parameters as CLI flags or AETHERPAK_-prefixed environment variables — for example, AETHERPAK_REGISTRY=ghcr.io or AETHERPAK_OCI_REPOSITORY=myorg/myrepo 4. This makes them ideal for one-off operations, quick local testing, and CI/CD pipelines where configuration is supplied by the environment rather than a committed file.

The commands below are listed roughly in the order you'd use them through the pipeline.

aetherpak status#

Validates that required system dependencies are present, checks any configuration file, and optionally decrypts and verifies GPG keys 10.

# Quick dependency check
aetherpak status

# Verify a GPG signing key
aetherpak status --gpg-key /path/to/key.asc --gpg-key-passphrase "$GPG_PASSPHRASE"

# Machine-readable JSON output (useful in CI scripts)
aetherpak status --json

Key flags 11:

aetherpak build#

Wraps flatpak-builder in a managed sandbox. It automatically installs/resolves flatpak-builder-lint, runs pre-build linting on the manifest, executes the build with ccache/state management, and runs post-build linting on the generated OSTree repository 12.

# Build for x86_64 (default)
aetherpak build --manifest apps/org.example.App/manifest.json --arch x86_64

# Build for aarch64 with linting enabled
aetherpak build --manifest apps/org.example.App/manifest.json --arch aarch64 --run-linter

# Build with an extra flatpak remote and SDK pre-installed
aetherpak build \
  --manifest manifest.json \
  --arch x86_64 \
  --flatpak-remote flathub=https://dl.flathub.org/repo/flathub.flatpakrepo \
  --flatpak-dep flathub:org.gnome.Sdk//47

Key flags 13 14:

Note: build is a plumbing command. For most use cases, prefer aetherpak publish --manifest <path>, which chains build + push-oci in a single step.

aetherpak import#

Ingests a prebuilt .flatpak bundle into a local OSTree repository. The app ID, architecture, and branch are auto-detected from the bundle's metadata when not specified — so you usually only need to provide the URL 15.

# Download and import a bundle (app-id/arch/branch auto-detected)
aetherpak import --bundle-url https://example.com/org.example.App_x86_64.flatpak

# Verify checksum and set an explicit branch
aetherpak import \
  --bundle-url https://example.com/app.flatpak \
  --bundle-sha256 abc123...64hexchars \
  --branch stable

# Import a local bundle file
aetherpak import --bundle-path ./build/org.example.App.flatpak

Key flags 16:

aetherpak push-oci#

Converts a local OSTree repository branch to an OCI container image and pushes it to a registry. This is the plumbing command underlying the OCI publish step 17.

# Push to GHCR (unsigned — useful for local dev)
aetherpak push-oci \
  --app-id org.example.App \
  --registry ghcr.io \
  --oci-repository myorg/myrepo \
  --no-sign

# Push with GPG signing
aetherpak push-oci \
  --app-id org.example.App \
  --registry ghcr.io \
  --oci-repository myorg/myrepo \
  --gpg-key /path/to/key.asc

Key flags 18:

aetherpak publish#

A porcelain command that chains build (or import) and push-oci sequentially in memory. This is the recommended starting point for one-off or zero-config publishing — use it instead of calling build and push-oci separately unless you need to insert custom steps between them 19.

# Build from a manifest and push to GHCR
aetherpak publish \
  --manifest apps/org.example.App/manifest.json \
  --registry ghcr.io \
  --oci-repository myorg/myrepo

# Import a bundle and push
aetherpak publish \
  --bundle https://example.com/app.flatpak \
  --registry ghcr.io \
  --oci-repository myorg/myrepo

# Disable signing for local testing
aetherpak publish \
  --manifest manifest.json \
  --registry ghcr.io \
  --oci-repository myorg/myrepo \
  --no-sign

aetherpak plan#

A plumbing command that computes the build matrix — which apps and architectures need to be built. When given a manifest directly, it expands it into the requested architectures. When given a config file with --base-sha, it compares git history to find only the apps that changed 20.

# Compute a build matrix for a single manifest
aetherpak plan --manifest apps/manifest.json --arch x86_64 --arch aarch64

# Config-driven planning with change detection
aetherpak plan --config aetherpak.yaml --base-sha "$GITHUB_SHA" --output matrix

# Output as a GitHub Actions matrix JSON
aetherpak plan --manifest manifest.json --arch x86_64 --output matrix

Key flags 21:

4. Bootstrapping a Multi-App Repository#

When you want to manage multiple Flatpak apps from a single repository, AetherPak uses an aetherpak.yaml configuration file. There is no init command — instead, you use aetherpak add repeatedly to incrementally build up the configuration, one app at a time 22.

aetherpak add#

The add command creates or modifies aetherpak.yaml by adding one application entry from one of three source types 23:

1. Local manifest — the app ID is auto-detected from the manifest file
2. Bundle URL — the bundle is downloaded, fingerprinted, and its SHA-256 is recorded
3. Git repository — the repo is added as a recursively-initialized submodule with the manifest auto-detected inside it

After resolving the app, a colored diff is displayed showing exactly what will be written to aetherpak.yaml. Changes are only applied after you confirm. Pass -y / --confirm to skip the prompt in non-interactive scripts.

When run on a TTY without any source flags, add launches an interactive wizard that walks you through choosing the source type and filling in the required details 24.

Adding from a local manifest#

# App ID is detected automatically from the manifest
aetherpak add --manifest apps/org.example.App/manifest.json

# Skip the diff confirmation
aetherpak add --manifest apps/org.example.App/manifest.json -y

# Specify arch and branch explicitly
aetherpak add \
  --manifest apps/org.example.App/manifest.json \
  --arch x86_64 --arch aarch64 \
  --branch stable

Adding from a bundle URL#

# SHA-256 is computed automatically on first download and recorded
aetherpak add \
  --bundle-url https://example.com/org.example.App_x86_64.flatpak \
  --app-id org.example.App

# Provide the checksum explicitly (skips download for verification)
aetherpak add \
  --bundle-url https://example.com/org.example.App_x86_64.flatpak \
  --app-id org.example.App \
  --bundle-sha256 abc123...64hexchars

Adding from a Git repository#

# The repo is added as a submodule; manifest is auto-detected inside it
aetherpak add --git https://github.com/org/app-manifest.git

# Specify where to place the submodule and which manifest to use
aetherpak add \
  --git https://github.com/org/app-manifest.git \
  --submodule-path manifests/app-manifest \
  --git-manifest org.example.App.json

If the user declines the diff confirmation after a --git add, the submodule addition is automatically rolled back 24.

Resulting aetherpak.yaml#

After running aetherpak add for a few apps, the resulting configuration might look like this:

registry: ghcr.io
pages_url: https://myorg.github.io/myrepo
oci_repository: myorg/myrepo

apps:
  # Manifest-based app: built from source on each push
  - id: org.example.AppOne
    manifest: apps/org.example.AppOne/org.example.AppOne.json
    arches: [x86_64, aarch64]
    branch: stable

  # Bundle-based app: ingested from upstream prebuilt binaries
  - id: com.example.AppTwo
    branch: stable
    bundles:
      x86_64:
        url: https://upstream.example.com/AppTwo_x86_64.flatpak
        sha256: "abc123...64hexchars"
      aarch64:
        url: https://upstream.example.com/AppTwo_aarch64.flatpak
        sha256: "def456...64hexchars"

Each app requires exactly one of manifest or bundles — not both 25. For the full aetherpak.yaml schema reference, including global settings, defaults, branding, channel_mappings, and linter configuration, see the CLI README 26 and the Maintainer Guide §5 25.

Common add Flags Reference#

27 28

5. Local Testing & Container Images#

For local end-to-end testing using Docker or Podman Compose, see the Local End-to-End Testing with Podman Compose guide. For details on the CLI container image variants (standard vs. builder), tagging, and usage in CI/CD, see CLI Container Images: Standard and Builder Variants. For the underlying utility images (ghcr.io/aetherpak/flatpak and ghcr.io/aetherpak/flatpak-builder), see Utility Images: flatpak and flatpak-builder.

6. Next Steps#

You now have everything you need to run the AetherPak CLI locally and in CI. Here are the natural next steps depending on what you want to do:

Set Up a Full GitHub Actions Pipeline#

The AetherPak Maintainer Guide covers the complete end-to-end workflow setup 25: creating the reusable workflow, enabling GitHub Pages, configuring GHCR permissions, and going from a first push to a publicly installable Flatpak repository in minutes.

Configure GPG Signing#

Signed repositories give users cryptographic assurance that the packages they install haven't been tampered with. The Maintainer Guide's GPG Signing section 25 walks through generating a key, adding it as a repository secret, and configuring signing: auto (or signing: gpg) in your workflow. For local testing, pass --gpg-key /path/to/key.asc to push-oci, publish, or release, or use --no-sign to skip signing entirely.

Build for Multiple Architectures#

The build and publish commands accept --arch as a repeatable flag. The plan command accepts multiple --arch values and emits a parallelizable matrix. In aetherpak.yaml, set arches: [x86_64, aarch64] per app (or in defaults) to build for both architectures automatically 35. The GitHub Actions reusable workflow runs each architecture on a native runner in parallel.

Customize Your Landing Page#

The generated index.html landing page can be fully customized through the branding block in aetherpak.yaml — set a custom logo, accent color, favicon, and footer text 36. For complete control, supply your own Go HTML template via branding.index_template (or the --index-template flag on build-site and release). See the Custom Index Templating section of the CLI README for the full template context and available helper functions 37.

Explore the Full CLI Reference#

Every command, flag, and environment variable is documented in the AetherPak CLI README 38. The --help flag on any subcommand also prints the full flag listing inline:

aetherpak --help
aetherpak build --help
aetherpak publish --help
aetherpak release --help