Skip to content

docs: add CLI installation and quick start #166

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
abn merged 1 commit into from
Sep 20, 2026
Merged

docs: add CLI installation and quick start #166

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
103 changes: 103 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,109 @@ A standalone, performance-focused Go command-line tool for orchestrating Flatpak

---

## Installation

AetherPak CLI is a single compiled Go binary. It has no runtime dependencies of its own, but the commands that compile, sign, and lint Flatpak applications expect the usual Flatpak toolchain on the host.

### System Prerequisites

* **flatpak** and **ostree**: required for repository, bundle, and ref operations.
* **flatpak-builder**: required by `build`, `publish`, and `release` when compiling from a manifest.
* **flatpak-builder-lint**: optional, used when `run_linter` is enabled.

Signing does not shell out to `gpg`. Repositories and OCI images are signed in-process from armored GPG key material, so no `gpg` binary is needed. Disable signing with `no_sign: true` or `--no-sign`.

Run `aetherpak status` after installing to see which of these are available.

### Option 1: Prebuilt Binary

Download the release archive for your architecture, extract it, and install the binary onto your `PATH`:

```bash
# x86_64
curl -LO https://github.com/aetherpak/cli/releases/latest/download/aetherpak-linux-amd64.tar.gz
tar -xzf aetherpak-linux-amd64.tar.gz
sudo install -Dm755 aetherpak-linux-amd64 /usr/local/bin/aetherpak

# aarch64
curl -LO https://github.com/aetherpak/cli/releases/latest/download/aetherpak-linux-arm64.tar.gz
tar -xzf aetherpak-linux-arm64.tar.gz
sudo install -Dm755 aetherpak-linux-arm64 /usr/local/bin/aetherpak
```

### Option 2: Build from Source

With Go 1.26.3 or newer, clone the repository and install the binary from the checkout:

```bash
git clone https://github.com/aetherpak/cli.git
cd cli
go install .
```

`go install .` writes the binary to `$(go env GOPATH)/bin/aetherpak`, so make sure that directory is on your `PATH`. A source build reports its version as `dev`, since the release version is stamped in at build time. For a version-stamped local build, `make build` writes the binary to `bin/aetherpak`.

### Option 3: Container Image

The published CLI image bakes in the Flatpak toolchain, so it needs no host setup. Mount the repository you want to build into `/workspace`:

```bash
# CLI image
podman run --rm -v "$PWD:/workspace" ghcr.io/aetherpak/cli:latest aetherpak status

# Builder image, with flatpak-builder available
podman run --rm -v "$PWD:/workspace" ghcr.io/aetherpak/cli:latest-builder aetherpak build --app-id org.example.App
```

Replace `podman` with `docker` if you use that runtime.

### Verify the Installation

```bash
aetherpak --version
aetherpak status
```

`status` prints a per-dependency report and validates your configuration file and GPG keys.

---

## Quick Start

AetherPak reads repository settings from `aetherpak.yaml` (or `aetherpak.yml`) in the working directory. A minimal single-app configuration looks like:

```yaml
app_id: org.example.App
runtime: org.freedesktop.Platform//25.08
manifest: apps/org.example.App/manifest.yaml
```

Then walk through a first build:

```bash
# Inspect the resolved configuration and active overrides
aetherpak config show

# Validate the local toolchain, config file, and signing setup
aetherpak status

# Build, push, and sign a single app end to end
aetherpak publish --app-id org.example.App --registry ghcr.io

# Or plan and release every app changed since a base commit
aetherpak release --base-sha <git-sha>
```

If you would rather not write the configuration by hand, `aetherpak add` can bootstrap it from a local manifest, a bundle URL, or a git repository:

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

The full command surface, including the plumbing primitives and configuration schema, is documented under [Command Reference](#command-reference) below.

---

## Architecture

The CLI follows a **Plumbing vs. Porcelain** design:
Expand Down
56 changes: 55 additions & 1 deletion docs/site/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -202,7 +202,7 @@ <h1>AetherPak CLI</h1>
<h2>What it is</h2>
<p class="lead">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.</p>
<ul class="points">
<li><strong>Zero Dependencies:</strong> Single compiled binary needing only local system tools (flatpak, ostree, and gpg).</li>
<li><strong>Zero Dependencies:</strong> Single compiled binary needing only local system tools (flatpak and ostree).</li>
<li><strong>Integrated Linter:</strong> Automatically hooks <code>flatpak-builder-lint</code> check points into compilation.</li>
<li><strong>CI-Agnostic Output:</strong> Dotenv format files capture resolved build coordinates easily.</li>
</ul>
Expand Down Expand Up @@ -247,6 +247,60 @@ <h2>Interactive CLI Execution</h2>
<p class="caption">Real execution logs simulation displaying AetherPak release stages.</p>
</section>

<section>
<h2>Installation</h2>
<p>AetherPak CLI ships as a single Go binary, as buildable source, and as a container image with the Flatpak toolchain pre-baked. The build and publish commands also expect <code>flatpak</code> and <code>ostree</code>, plus <code>flatpak-builder</code> for manifest builds and optionally <code>flatpak-builder-lint</code>, on the host. Signing uses in-process OpenPGP from armored key material, so no <code>gpg</code> binary is required.</p>

<div class="card" style="margin-top: 1rem;">
<div class="tabs" role="tablist">
<button class="tab" role="tab" data-tab="install-binary" aria-selected="true">Prebuilt binary</button>
<button class="tab" role="tab" data-tab="install-go" aria-selected="false">Build from source</button>
<button class="tab" role="tab" data-tab="install-container" aria-selected="false">Container</button>
</div>

<div class="panel" data-tab="install-binary">
<p style="margin-bottom: 1rem;">Download the release archive for your architecture, extract it, and install the binary onto your <code>PATH</code>:</p>
<div class="code-block">
<pre><code># x86_64
curl -LO https://github.com/aetherpak/cli/releases/latest/download/aetherpak-linux-amd64.tar.gz
tar -xzf aetherpak-linux-amd64.tar.gz
sudo install -Dm755 aetherpak-linux-amd64 /usr/local/bin/aetherpak

# aarch64
curl -LO https://github.com/aetherpak/cli/releases/latest/download/aetherpak-linux-arm64.tar.gz
tar -xzf aetherpak-linux-arm64.tar.gz
sudo install -Dm755 aetherpak-linux-arm64 /usr/local/bin/aetherpak</code></pre>
<button class="btn-copy" title="Copy" aria-label="Copy" onclick="copyBlock(this)"></button>
</div>
</div>

<div class="panel" data-tab="install-go" hidden>
<p style="margin-bottom: 1rem;">With Go 1.26.3 or newer, clone the repository and install from the checkout:</p>
<div class="code-block">
<pre><code>git clone https://github.com/aetherpak/cli.git
cd cli
go install .</code></pre>
<button class="btn-copy" title="Copy" aria-label="Copy" onclick="copyBlock(this)"></button>
</div>
<p class="hint">Installs to <code>$(go env GOPATH)/bin/aetherpak</code>; a source build reports its version as <code>dev</code>.</p>
</div>

<div class="panel" data-tab="install-container" hidden>
<p style="margin-bottom: 1rem;">The published image bakes in the Flatpak toolchain. Mount your repository into <code>/workspace</code>:</p>
<div class="code-block">
<pre><code># CLI image
podman run --rm -v "$PWD:/workspace" ghcr.io/aetherpak/cli:latest aetherpak status

# Builder image, with flatpak-builder available
podman run --rm -v "$PWD:/workspace" ghcr.io/aetherpak/cli:latest-builder aetherpak build --app-id org.example.App</code></pre>
<button class="btn-copy" title="Copy" aria-label="Copy" onclick="copyBlock(this)"></button>
</div>
</div>
</div>

<p class="hint" style="margin-top: 1rem;">Verify the install with <code>aetherpak --version</code>, then <code>aetherpak status</code> to check system dependencies, configuration, and signing keys.</p>
</section>

<section>
<h2>Command Reference</h2>
<div class="card">
Expand Down
Loading