AetherPak CLI

What it is

AetherPak CLI is a Go-compiled tool that fully automates local compilation, signature backfilling, registry distribution, and index generation. It acts as the core engine that powers AetherPak GitHub Actions, but can also run independently on any developer machine or non-containerized CI runner.

• Zero Dependencies: Single compiled binary needing only local system tools (flatpak, ostree, and gpg).
• Integrated Linter: Automatically hooks flatpak-builder-lint check points into compilation.
• CI-Agnostic Output: Dotenv format files capture resolved build coordinates easily.

Interactive CLI Execution

AetherPak CLI outputs status logs using structured timing metrics and beautiful Lipgloss-styled status banners during execution:

Real execution logs simulation displaying AetherPak release stages.

Command Reference

aetherpak add --manifest org.example.App.yaml

aetherpak release --base-sha abc123def --workers 4

# Config-driven publish
aetherpak publish --app-id org.example.App --registry ghcr.io

# One-off publish from local manifest
aetherpak publish --manifest apps/manifest.json --arch x86_64

# One-off publish from Flatpak bundle (URL or local path)
aetherpak publish --bundle https://example.com/app.flatpak

aetherpak status --gpg-key key.asc

aetherpak preview --port 8080

aetherpak plan --base-sha HEAD~1 --output-file plan.env

aetherpak build --manifest manifest.json --flatpak-remote flathub=https://dl.flathub.org/repo/flathub.flatpakrepo --flatpak-dep flathub:org.gnome.Sdk//45

aetherpak import --app-id org.example.App --bundle-url https://example.com/download.flatpak

aetherpak push-oci --app-id org.example.App --gpg-key key.asc

aetherpak build-site --pages-url https://flatpak.org --site-dir _site

aetherpak resolve-channel --ref-type tag --ref-name v1.0.0

aetherpak inspect-repo --repo-path repo

# Get a configuration value
aetherpak config get remote_name
aetherpak config get branding.logo_url

# Set a configuration value
aetherpak config set remote_name custom-remote
aetherpak config set branding.logo_url https://new-logo.png

# Show resolved configuration and active overrides
aetherpak config show

Developer Configuration

AetherPak CLI loads config instructions dynamically. Below is an example of an aetherpak.yaml configuration mapping multiple source structures:

registry: ghcr.io
oci_repository: my-org/my-app
pages_url: https://flatpak.example.com
remote_name: example-repo
output_dir: .aetherpak-output
no_sign: false
repo_title: "My Custom Flatpak Repository"

channel_mappings:
  "main": "beta"
  "staging/*": "alpha"

linter:
  strict: true
  ignore_rules: ["appstream-screenshot-missing"]
  exceptions: ["appstream-license-missing"]
  exceptions_file: "linter-exceptions.json"

defaults:
  ccache: true
  run_linter: true
  state_dir: ".builder-state"
  remotes:
    flathub: https://dl.flathub.org/repo/flathub.flatpakrepo
  flatpaks:
    - remote: flathub
      ref: org.gnome.Sdk//45

branding:
  logo_url: "https://example.com/logo.png"
  accent_color: "#a855f7"
  footer_text: "Custom Repo Landing Page Footer"
  index_template: "templates/custom_index.html"

apps:
  - id: org.example.App
    manifest: apps/org.example.App/manifest.json
    runtime: gnome-50
    arches: [x86_64, aarch64]
    run-linter: true
    remotes:
      repoA: https://example.com/repoA.flatpakrepo
    flatpaks:
      - remote: repoA
        ref: org.gnome.Sdk.ExtensionA//45

  - id: com.example.Other
    branch: beta
    bundles:
      x86_64:
        url: https://upstream.com/Other_x86_64.flatpak
        sha256: 2159fc643175dcf54f8b9293f48fb8b11577fa0ea5514...

Custom Index Templating

AetherPak CLI supports custom landing page templates using Go's html/template engine. This allows you to generate a fully customized HTML index page detailing all the repository applications, releases, and installation steps.

To use a custom template, configure branding.index_template in aetherpak.yaml, or pass the --index-template flag (or AETHERPAK_INDEX_TEMPLATE env var) to aetherpak build-site / aetherpak release.

<!DOCTYPE html>
<html>
<head>
  <title>{{.RepoTitle}}</title>
  <link rel="icon" href="{{.FaviconURL}}">
</head>
<body>
  <h1>{{.RepoTitle}}</h1>

  {{range .Apps}}
    <div class="app-card">
      {{if .Icon}}<img src="{{.Icon}}" width="64">{{end}}
      <h2>{{.Name}} ({{.ID}})</h2>
      <p>{{.Summary}}</p>

      <h3>Releases</h3>
      <ul>
        {{range .Branches}}
          <li>
            Branch: <strong>{{.Branch}}</strong> | Arches: {{join .Arches ", "}}
            <br>Released on: {{.FormattedDate}} | Size: {{formatSize .InstalledSize}}
            <br>Install: <code>{{.InstallCmd}}</code>
          </li>
        {{end}}
      </ul>
    </div>
  {{end}}

  <footer>{{.FooterText}}</footer>
</body>
</html>

Related Repositories