{"id":50360167,"url":"https://github.com/aetherpak/cli","last_synced_at":"2026-06-12T17:01:02.584Z","repository":{"id":361228739,"uuid":"1253632174","full_name":"aetherpak/cli","owner":"aetherpak","description":null,"archived":false,"fork":false,"pushed_at":"2026-06-01T00:10:11.000Z","size":237,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-01T02:00:36.763Z","etag":null,"topics":["flatpak","flatpak-applications","flatpak-repository"],"latest_commit_sha":null,"homepage":"https://aetherpak.github.io/cli/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aetherpak.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-29T16:56:58.000Z","updated_at":"2026-06-01T00:10:07.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/aetherpak/cli","commit_stats":null,"previous_names":["aetherpak/cli"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/aetherpak/cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aetherpak%2Fcli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aetherpak%2Fcli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aetherpak%2Fcli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aetherpak%2Fcli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aetherpak","download_url":"https://codeload.github.com/aetherpak/cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aetherpak%2Fcli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33756581,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-01T02:00:06.963Z","response_time":115,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["flatpak","flatpak-applications","flatpak-repository"],"created_at":"2026-05-30T01:04:53.631Z","updated_at":"2026-06-12T17:01:02.575Z","avatar_url":"https://github.com/aetherpak.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AetherPak Core CLI\n\nA standalone, performance-focused Go command-line tool for orchestrating Flatpak application build pipelines, registry distribution (OCI), and static index site generation.\n\n---\n\n## Architecture\n\nThe CLI follows a **Plumbing vs. Porcelain** design:\n* **Plumbing (Primitives):** Independent, highly-scoped, single-responsibility commands suited for complex workflows or customizable matrices.\n* **Porcelain (Convenience Wrappers):** Standard high-level triggers that coordinate plumbing calls automatically in-memory.\n\nFor details on the Go package layout:\n* [`pkg/config`](pkg/config/): Configuration parsing and validations rules.\n* [`pkg/record`](pkg/record/): Execution output records JSON contracts (`record.json` / `labels.json`).\n* [`pkg/plan`](pkg/plan/): Planning engine and git diff matrices logic.\n* [`pkg/builder`](pkg/builder/): system wrapper for `flatpak-builder`.\n* [`pkg/importer`](pkg/importer/): bundle downloader, checker, and rebind.\n* [`pkg/oci`](pkg/oci/): OSTree-to-OCI tags compiler and push transporters.\n* [`pkg/signing`](pkg/signing/): cryptographical in-memory detached GPG signatures.\n* [`pkg/site`](pkg/site/): indexing merges and site aggregation engines.\n---\n\n## Configuration\n\nThe CLI parses settings from a configuration file, looking for `aetherpak.yaml` or `aetherpak.yml` in the local working directory by default.\n\n\u003e [!NOTE]\n\u003e The configuration file can use both `.yaml` and `.yml` extensions. You can also specify a custom configuration file path at runtime using the `--config` flag or override any configuration parameter using environment variables prefixed with `AETHERPAK_` (e.g. `AETHERPAK_REGISTRY`).\n\n### Configuration Schema\n\n#### Global Settings\n* **`registry`** (string): The target OCI registry host (e.g., `ghcr.io` or `quay.io`).\n* **`pages_url`** (string): The public URL where the repository landing page and index files are hosted.\n* **`oci_repository`** (string): The target repository path/name for OCI distribution (replaces deprecated `remote_name` for OCI registry pushes).\n* **`remote_name`** (string): The repository name configured in user Flatpak clients (defaults to `\u003cowner\u003e-\u003crepo\u003e`). Historically used for OCI registry pushes; now acts as a fallback for `oci_repository` (deprecated for registry pushes).\n* **`output_dir`** (string): Base directory for all output assets (state, records, site, ccache, repo) unless overridden.\n* **`no_sign`** (boolean): Set to `true` to disable GPG signing of repositories and OCI images entirely (defaults to `false`).\n* **`repo_title`** (string): Customized title shown on the landing page and `.flatpakrepo` metadata (defaults to `\"Flatpak Repository\"`).\n* **`repo_homepage`** (string): URL link for repository homepage metadata.\n* **`runtime_repo`** (string): Fallback `.flatpakrepo` URL used to resolve dependencies (defaults to Flathub).\n* **`channel_mappings`** (map[string]string): Key-value pairs mapping Git references (supporting glob wildcards like `staging/*`) to target flatpak branches.\n\n#### `branding`\nCustomizes the look and feel of the generated landing page:\n* **`logo_url`** (string): URL to a custom repository header logo.\n* **`favicon_url`** (string): URL to a page favicon file.\n* **`accent_color`** (string): Hex color code defining the primary brand accent (defaults to `#8b5cf6`).\n* **`footer_text`** (string): Custom text/HTML to display in the footer (defaults to `\"Powered by AetherPak\"`).\n* **`index_template`** (string): Local path to an alternative HTML file template to override index generation entirely. Supports structured Go HTML templates with access to repository applications and formatting helper functions (see [Custom Index Templating](#custom-index-templating) below).\n\n#### `linter`\nGlobal linter behavior configuration:\n* **`strict`** (boolean): Set to `true` to fail builds if any linter warnings or errors are raised.\n* **`ignore_rules`** (list[string]): Specific `flatpak-builder-lint` rule IDs to bypass.\n* **`exceptions`** (list[string]): Inline list of `flatpak-builder-lint` rule IDs to bypass (alternative/alias for `ignore_rules`). Can be overridden via the `AETHERPAK_LINTER_EXCEPTIONS` environment variable or the `--linter-exception` flag.\n* **`exceptions_file`** (string): Local path to a JSON configuration file containing app-specific or wildcard linter exceptions (e.g. `\"linter-exceptions.json\"`). Can be overridden via the `AETHERPAK_LINTER_EXCEPTIONS_FILE` environment variable or the `--linter-exceptions-file` flag.\n\n#### `defaults`\nFallback build configurations applied when individual application settings are omitted:\n* **`ccache`** (boolean): Enable compiler cache to speed up compilation.\n* **`ccache_dir`** (string): Custom folder directory to store compiler cache assets.\n* **`state_dir`** (string): Path to store intermediate state outputs (defaults to `.state`).\n* **`run_linter`** (boolean): Set to `true` to run linter checks on manifests and built repositories.\n* **`builder_args`** (list[string]): Additional command-line flags to pass directly to `flatpak-builder`.\n* **`no_install_deps`** (boolean): Disable automatic injection of `--install-deps-from` flags when running `flatpak-builder` (defaults to `false`).\n* **`no_flathub`** (boolean): Disable automatic injection of the `flathub` remote as a dependency source (defaults to `false`).\n* **`remotes`** (map[string]string | map[string]RemoteConfig): Map of Flatpak remote repository names to their configuration (pre-registered before build). Can be a simple URL string or an exploded map supporting:\n  * **`url`** (string, required): The flatpakrepo URL.\n  * **`gpg_verify`** (boolean, optional): Enable/disable GPG verification.\n  * **`gpg_key`** (string, optional): GPG public key (can be a local path, URL, or inline ASCII-armored GPG public key block).\n  * **`sig_verify_url`** (string, optional): Signature lookaside URL.\n* **`flatpaks`** (list[FlatpakDep]): Flatpak runtimes or SDK extensions/dependencies to pre-install before build. Each entry requires a `remote` (string) and a `ref` (string).\n\n#### `apps`\nA list of applications managed in the repository. Each entry supports the following settings:\n* **`id`** (string, required): The reverse-DNS Flatpak application identifier (e.g. `org.example.App`).\n* **`branch`** (string): The release channel branch (defaults to `stable`).\n* **`arches`** (list[string]): Target architectures to compile/import (defaults to `[x86_64]`).\n* **`manifest`** (string): Local relative path to the Flatpak manifest file (required for source-based builds).\n* **`runtime`** (string): Upstream runtime dependencies list (required for source-based builds).\n* **`run-linter`** (boolean): Local toggle to execute linter validation checks.\n* **`linter`** (block): Override block for linter strictness, ignore rules, and exceptions. Supports `strict` (boolean), `ignore_rules` (list[string]), `exceptions` (list[string]), and `exceptions_file` (string).\n* **`ccache`** / **`ccache_dir`** / **`state_dir`** / **`builder_args`** / **`no_install_deps`** / **`no_flathub`**: Application-specific overrides for compilation parameters.\n* **`remotes`** / **`flatpaks`**: Application-specific overrides/merges for Flatpak remotes and dependencies.\n* **`bundles`** (map[string]Bundle): Prebuilt Flatpak bundle inputs mapped per architecture. Under each arch (e.g. `x86_64`):\n  * **`url`** (string, required): Download link to the `.flatpak` bundle.\n  * **`sha256`** (string, required): 64-character SHA-256 validation checksum of the file.\n\n---\n\n### Example Configuration (`aetherpak.yaml`)\n\n```yaml\nregistry: ghcr.io\npages_url: https://flatpak.example.com\nremote_name: example-repo\nrepo_title: \"My Custom Flatpak Repository\"\n\nchannel_mappings:\n  \"main\": \"beta\"\n  \"staging/*\": \"alpha\"\n\nlinter:\n  strict: true\n  ignore_rules: [\"appstream-screenshot-missing\"]\n\ndefaults:\n  ccache: true\n  run_linter: true\n  state_dir: \".builder-state\"\n  builder_args: [\"--sandbox\", \"--disable-rofiles-fuse\"]\n  remotes:\n    flathub: https://dl.flathub.org/repo/flathub.flatpakrepo\n    custom_repo:\n      url: https://example.com/repo.flatpakrepo\n      gpg_verify: true\n      gpg_key: https://example.com/keys/gpg.key\n      sig_verify_url: https://example.com/signatures\n  flatpaks:\n    - remote: flathub\n      ref: org.gnome.Sdk//45\n\nbranding:\n  logo_url: \"https://example.com/logo.png\"\n  accent_color: \"#a855f7\"\n  footer_text: \"Custom Repo Landing Page Footer\"\n\napps:\n  - id: org.example.App\n    manifest: apps/org.example.App/manifest.json\n    runtime: gnome-50\n    arches: [x86_64, aarch64]\n    run-linter: true\n    remotes:\n      repoA: https://example.com/repoA.flatpakrepo\n    flatpaks:\n      - remote: repoA\n        ref: org.gnome.Sdk.ExtensionA//45\n\n  - id: com.example.Other\n    branch: beta\n    bundles:\n      x86_64:\n        url: https://upstream.com/Other_x86_64.flatpak\n        sha256: 2159fc643175dcf54f8b9293f48fb8b11577fa0ea5514ea47d4e3ef4431f13b1\n```\n\n---\n\n### Linter Exceptions\n\nAetherPak automatically registers default exceptions for linter checks that are not applicable to self-hosted/independent repositories:\n- `appstream-external-screenshot-url`\n- `appstream-screenshots-not-mirrored-in-ostree`\n\nExceptions can be configured in two ways:\n\n#### 1. Inline Configuration\nYou can specify list of exceptions directly under the `linter.exceptions` property globally or per-app:\n```yaml\nlinter:\n  exceptions:\n    - appstream-screenshot-missing\n    - appstream-license-missing\n```\nOr override them at runtime using:\n- CLI repeatable flag: `--linter-exception \u003crule\u003e`\n- Env Var: `AETHERPAK_LINTER_EXCEPTIONS` (comma-separated list of exceptions)\n\n#### 2. External JSON File (Flathub format)\nYou can point to a linter exceptions JSON file containing app-specific or wildcard rules:\n```json\n{\n  \"org.example.App\": [\n    \"appstream-screenshot-missing\",\n    \"appstream-summary-too-long\"\n  ],\n  \"*\": [\n    \"appstream-license-missing\"\n  ]\n}\n```\nThis file path can be configured globally/per-app in `aetherpak.yaml` using the `exceptions_file` property, or overridden at runtime via:\n- CLI flag: `--linter-exceptions-file \u003cpath\u003e`\n- Env Var: `AETHERPAK_LINTER_EXCEPTIONS_FILE` (or `AETHERPAK_LINTER_EXCEPTIONS` if it has a `.json` suffix)\n\n---\n\n### Custom Index Templating\n\nWhen using a custom template file via the `index_template` config option, the `--index-template` flag, or the `AETHERPAK_INDEX_TEMPLATE` environment variable, AetherPak executes the template using Go's `html/template` engine.\n\nThe template is executed with a structured context containing all resolved repository, branding, signing, and application details.\n\n#### Template Context Structure\n\nThe data structure passed to your custom template is defined as follows:\n\n* **`.RemoteName`** (string): The resolved Flatpak remote repository name.\n* **`.RepoTitle`** (string): The repository title.\n* **`.PagesURL`** (string): The URL where the repository static files are hosted.\n* **`.RepoHomepage`** (string): The homepage URL link.\n* **`.RuntimeRepo`** (string): The upstream runtime dependency repository URL.\n* **`.LogoURL`** (string): Custom repository header logo URL.\n* **`.LogoHTML`** (template.HTML): Pre-formatted HTML image element containing `LogoURL` if configured.\n* **`.FaviconURL`** (string): Custom page favicon file URL.\n* **`.AccentColor`** (string): Hex color code defining the brand accent color.\n* **`.FooterText`** (template.HTML): Custom footer HTML text.\n* **`.Signing`** (block):\n  * **`.Signing.Enabled`** (boolean): True if GPG signing is enabled.\n  * **`.Signing.Fingerprint`** (string): GPG public key fingerprint.\n  * **`.Signing.PublicKey`** (string): Path to the armored public key file (`sigs/key.asc`).\n  * **`.Signing.Lookaside`** (string): Path to the GPG signature lookaside directory (`sigs`).\n* **`.Apps`** (list): A list of preprocessed, structured application records:\n  * **`.ID`** (string): Reverse-DNS application identifier (e.g. `org.example.App`).\n  * **`.Name`** (string): Application name extracted from AppStream appdata, falling back to ID.\n  * **`.Summary`** (string): Application summary description extracted from AppStream appdata.\n  * **`.Icon`** (string): URL to the 64x64 application icon if defined.\n  * **`.Branches`** (list): List of release channel branches sorted newest first:\n    * **`.Branch`** (string): Flatpak branch channel (e.g. `stable`, `beta`).\n    * **`.Arches`** (list[string]): Alphabetic list of supported architectures (e.g. `[aarch64, x86_64]`).\n    * **`.Timestamp`** (int64): Latest build release Unix epoch timestamp.\n    * **`.FormattedDate`** (string): Human-readable release date formatted as `Jan 02, 2006`.\n    * **`.InstalledSize`** (int64): Latest build installed size in bytes.\n    * **`.DownloadSize`** (int64): Latest build download size in bytes.\n    * **`.Commit`** (string): Flatpak commit identifier.\n    * **`.RefFile`** (string): Path to target download flatpakref file (e.g. `refs/org.example.App-stable.flatpakref`).\n    * **`.InstallCmd`** (string): Helper command to install the application branch client-side.\n\n#### Template Helper Functions\n\nYou can use the following custom Go template helpers inside your custom template:\n\n* **`join \u003cslice\u003e \u003cseparator\u003e`**: Joins a slice of strings using the specified separator.\n  * Example: `{{join .Arches \"/\"}}` -\u003e `aarch64/x86_64`\n* **`formatSize \u003cbytes\u003e`**: Formats raw bytes into a human-readable string representation.\n  * Example: `{{formatSize .InstalledSize}}` -\u003e `20 MB`\n* **`formatDate \u003ctimestamp\u003e \u003clayout\u003e`**: Formats a UNIX epoch timestamp using a standard Go time layout.\n  * Example: `{{formatDate .Timestamp \"2006-01-02\"}}` -\u003e `2026-06-01`\n\n#### Example Custom Template\n\nHere is a simple example of a custom HTML template:\n\n```html\n\u003c!DOCTYPE html\u003e\n\u003chtml\u003e\n\u003chead\u003e\n  \u003ctitle\u003e{{.RepoTitle}}\u003c/title\u003e\n  \u003clink rel=\"icon\" href=\"{{.FaviconURL}}\"\u003e\n\u003c/head\u003e\n\u003cbody\u003e\n  \u003ch1\u003e{{.RepoTitle}}\u003c/h1\u003e\n\n  {{range .Apps}}\n    \u003cdiv class=\"app-card\"\u003e\n      {{if .Icon}}\u003cimg src=\"{{.Icon}}\" width=\"64\"\u003e{{end}}\n      \u003ch2\u003e{{.Name}} ({{.ID}})\u003c/h2\u003e\n      \u003cp\u003e{{.Summary}}\u003c/p\u003e\n\n      \u003ch3\u003eReleases\u003c/h3\u003e\n      \u003cul\u003e\n        {{range .Branches}}\n          \u003cli\u003e\n            Branch: \u003cstrong\u003e{{.Branch}}\u003c/strong\u003e | Arches: {{join .Arches \", \"}}\n            \u003cbr\u003eReleased on: {{.FormattedDate}} | Size: {{formatSize .InstalledSize}}\n            \u003cbr\u003eInstall: \u003ccode\u003e{{.InstallCmd}}\u003c/code\u003e\n          \u003c/li\u003e\n        {{end}}\n      \u003c/ul\u003e\n    \u003c/div\u003e\n  {{end}}\n\n  \u003cfooter\u003e{{.FooterText}}\u003c/footer\u003e\n\u003c/body\u003e\n\u003c/html\u003e\n```\n\n---\n\n## Command Reference\n\n### Root Options\n\n* `--config \u003cpath\u003e` (optional path to `aetherpak.yaml`, defaults to check for `aetherpak.yaml` locally).\n* `--output-dir \u003cpath\u003e` (base directory for all output assets unless overridden).\n* `-v, --verbose` (enable verbose debugging statements).\n* `--json-log` (enable JSON formatted structured output logs).\n* `--plain` (disable colors, emojis, and fancy formatting; plain text output).\n* `--no-color` (alias for `--plain` to disable colors and fancy formatting).\n\n### Plumbing Commands\n\n#### `plan`\nComputes matrices for changed assets since a specific base SHA diff:\n```bash\naetherpak plan --base-sha \u003csha\u003e --workflow-path \u003cpath\u003e --output json\n```\nOptions:\n* `--override-branch \u003cbranch\u003e`: Overrides the Flatpak branch (release channel) for all planned apps in the matrix.\n* `--force \u003capp-id\u003e`: Rebuilds a specific app. Supports the Flatpak standard `app-id//branch` ref format (e.g. `org.example.App//beta`) to select that app and override its target branch.\n\n#### `build`\nWraps `flatpak-builder` sandbox compilation:\n```bash\naetherpak build --app-id org.example.App --manifest apps/manifest.json --arch x86_64 --linter-exception appstream-screenshot-missing --flatpak-remote flathub=https://dl.flathub.org/repo/flathub.flatpakrepo --flatpak-dep flathub:org.gnome.Sdk//45\n```\nOptions:\n* `--app-id \u003capp-id\u003e`: target application ID. Supports the Flatpak standard `app-id//branch` ref format (e.g. `org.example.App//beta`) to build that app and override its target branch.\n* `--flatpak-remote \u003cname\u003e=\u003curl\u003e`: Repeatable flag to register Flatpak remotes before compiling.\n* `--flatpak-dep \u003cremote\u003e:\u003cref\u003e`: Repeatable flag to install Flatpak dependencies (runtimes, SDK extensions) before compiling.\n* `--no-install-deps`: Disable automatic injection of `--install-deps-from` flags when running `flatpak-builder`.\n* `--no-flathub`: Disable automatic injection of the `flathub` remote as a dependency source.\n\n#### `import`\nIngests prebuilt bundles (`.flatpak`) and rebinds channels:\n```bash\naetherpak import --app-id org.example.App --bundle-url https://... --bundle-sha256 \u003chex\u003e\n```\nOptions:\n* `--app-id \u003capp-id\u003e`: target application ID. Supports the Flatpak standard `app-id//branch` ref format (e.g. `org.example.App//beta`) to override its target branch.\n\n#### `push-oci`\nConverts repo branch to OCI image layer and pushes:\n```bash\naetherpak push-oci --app-id org.example.App --registry ghcr.io --oci-repository my-org/my-app\n```\nOptions:\n* `--app-id \u003capp-id\u003e`: target application ID. Supports the Flatpak standard `app-id//branch` ref format (e.g. `org.example.App//beta`) to filter repository refs or override its target branch.\n* `--gpg-key \u003cpath\u003e`: Local path to GPG private key used to sign image manifests.\n* `--no-sign`: Disable GPG signing entirely (bypasses GPG signature step).\n* `--allow-unsigned`: Allow pushing unsigned images if signing keys are missing.\n* `--dry-run`: Simulate pushing OCI image without writing to remote registry or records.\n\n#### `build-site`\nDownloads old static index, merges recent cell records, and regenerates index listings:\n```bash\naetherpak build-site --pages-url https://flatpak.my-org.com --site-dir _site --reconcile --index-template templates/custom_index.html\n```\nOptions:\n* `--gpg-key \u003cpath\u003e`: Local path to GPG private key used to export GPG public keys.\n* `--no-sign`: Disable GPG signing and metadata export entirely.\n* `--allow-unsigned`: Allow building unsigned index if GPG keys are missing.\n\n#### `resolve-channel`\nResolves the flatpak channel name from git ref metadata:\n```bash\naetherpak resolve-channel --ref-type tag --ref-name v1.0.0\n```\n\n#### `inspect-repo`\nResolves the app-id, arch, and branch channel from an existing OSTree repository metadata:\n```bash\naetherpak inspect-repo --repo-path repo\n```\n\n#### `config`\nGets, sets, or displays configuration parameter settings:\n```bash\n# Get a configuration value\naetherpak config get remote_name\naetherpak config get branding.logo_url\n\n# Set a configuration value\naetherpak config set remote_name custom-remote\naetherpak config set branding.logo_url https://new-logo.png\n\n# Show resolved configuration and active overrides\naetherpak config show\n```\n\n\n### Porcelain Commands\n\n#### `add`\nCreates or modifies an `aetherpak.yaml` by adding one application from a local\nmanifest, a remote bundle URL (downloaded and fingerprinted), or a git\nrepository (added as a submodule, initialised recursively). Runs an interactive\nwizard on a TTY; otherwise reads flags. A colored diff is shown before changes\nare written unless `--confirm`/`-y` is given.\n```bash\n# Local manifest (app id detected from the manifest)\naetherpak add --manifest org.example.App.yaml\n\n# Bundle URL (downloaded + fingerprinted; SHA-256 recorded)\naetherpak add --bundle-url https://example.com/app.flatpak --app-id org.example.App\n\n# Git repository added as a submodule\naetherpak add --git https://example.com/repo.git\n\n# Skip the diff confirmation\naetherpak add --manifest org.example.App.yaml -y\n```\nOptions:\n* `--manifest \u003cpath\u003e` / `--bundle-url \u003curl\u003e` / `--git \u003curl\u003e`: the source (exactly one in non-interactive mode).\n* `--git-manifest \u003cpath\u003e`: manifest path within the git repo (auto-detected if omitted).\n* `--submodule-path \u003cpath\u003e`: submodule destination (default `manifests/\u003creponame\u003e`).\n* `--app-id`, `--branch` (Flatpak release channel, default `stable`), `--arch` (repeatable, defaults to the host architecture): overrides; `app-id` is derived from the manifest when omitted (only the bundle source requires `--app-id`).\n* `--bundle-sha256 \u003chex\u003e`: expected bundle checksum (verified; computed when omitted).\n* Build options (manifest/git sources only): `--install-deps-from-flathub` (default `true`, appends `--install-deps-from=flathub`), `--run-linter`, `--ccache`, and `--builder-arg \u003carg\u003e` (repeatable, free-form).\n* `-y`, `--confirm`: skip the diff confirmation prompt.\n\nThe app id is read from the manifest — you are never prompted for it when it can be detected; a manifest that is found but lacks an id is reported as an error. The target config is resolved from `--config`/`AETHERPAK_CONFIG`, else an existing `aetherpak.yaml`/`aetherpak.yml` in the working directory, else a new `aetherpak.yaml` is created.\n\n#### `publish`\nChains compilation/importer and OCI push sequentially in-memory for target application(s):\n```bash\n# Config-driven publish\naetherpak publish --app-id org.example.App --registry ghcr.io\n\n# One-off publish from local manifest\naetherpak publish --manifest apps/manifest.json --arch x86_64\n\n# One-off publish from Flatpak bundle (URL or local path)\naetherpak publish --bundle https://example.com/app.flatpak\n```\nOptions:\n* `--app-id \u003cid\u003e`: target application ID. Supports the Flatpak standard `app-id//branch` ref format (e.g. `org.example.App//beta`) to override its target branch.\n* `--manifest \u003cpath\u003e`: path to a local Flatpak manifest file (one-off publish, bypasses config).\n* `--bundle \u003curl|path\u003e`: Flatpak bundle URL or path to import and publish (one-off publish, bypasses config).\n* `--confirm`: skip interactive confirmation prompt when importing bundles.\n* `--arch \u003carch\u003e`: target CPU architecture (defaults to host architecture).\n* `--gpg-key \u003cpath\u003e`: Local path to GPG private key.\n* `--no-sign`: Disable GPG signing entirely.\n* `--allow-unsigned`: Allow publishing unsigned images if GPG keys are missing.\n* `--linter-exceptions-file \u003cpath\u003e`: Local path to linter exceptions file (JSON).\n* `--linter-exception \u003crule\u003e`: Repeatable flag to specify linter exceptions to ignore.\n* `--dry-run`: Simulate publishing without writing to remote registry or records.\n\n#### `release`\nCoordinates the entire lifecycle: runs matrix planner, compiles/imports changed records concurrently, pushes artifacts, and builds site index layouts:\n```bash\naetherpak release --base-sha \u003csha\u003e --workers 4 --index-template templates/custom_index.html\n```\nOptions:\n* `--gpg-key \u003cpath\u003e`: Local path to GPG private key.\n* `--no-sign`: Disable GPG signing entirely.\n* `--allow-unsigned`: Allow releasing unsigned images/index if GPG keys are missing.\n* `--linter-exceptions-file \u003cpath\u003e`: Local path to linter exceptions file (JSON).\n* `--linter-exception \u003crule\u003e`: Repeatable flag to specify linter exceptions to ignore.\n* `--flatpak-remote \u003cname\u003e=\u003curl\u003e`: Repeatable flag to register Flatpak remotes before compiling.\n* `--flatpak-dep \u003cremote\u003e:\u003cref\u003e`: Repeatable flag to install Flatpak dependencies before compiling.\n* `--dry-run`: Simulate release process without writing to remote registry, records, or site directories.\n\n#### `status`\nValidates that required system dependencies are available, checks configuration files, and decrypts/verifies GPG keys:\n```bash\naetherpak status\n```\nOptions:\n* `--gpg-key \u003cpath\u003e`: Local path to GPG private key block(s) or file(s) to verify signing.\n* `--gpg-key-passphrase \u003cpassphrase\u003e`: GPG key passphrase to test decryption.\n* `--json`: Outputs raw diagnostics status as JSON for script parsing.\n\n#### `preview`\nGenerates and serves a local landing page template preview using customizable dummy mock data or a live production index:\n```bash\n# Serve preview locally on port 8080 (default)\naetherpak preview\n\n# Serve preview on port 9000 with a custom template\naetherpak preview --port 9000 --template templates/custom.html\n\n# Generate static preview pages without serving (useful for CI/CD test site generation)\naetherpak preview --no-serve --apps=single --gpg=false\n```\nOptions:\n* `--template, -t \u003cpath\u003e`: Local path to custom HTML repository index template (overrides configuration template).\n* `--default-template`: Force using the default embedded landing page template, ignoring configuration/env settings.\n* `--live`: Fetch live production index data instead of generating dummy data.\n* `--live-url \u003curl\u003e`: Live Pages URL to download the index from (implicitly enables `--live`).\n* `--gpg`: Enable GPG signing simulation for dummy data (defaults to `true`).\n* `--apps \u003csingle|multiple\u003e`: Simulate single or multiple applications in dummy data (defaults to `multiple`).\n* `--site-dir \u003cpath\u003e`: Destination directory for preview assets (defaults to `_preview`).\n* `--no-serve`: Do not start a local HTTP server to preview the site (defaults to `false`).\n* `--port \u003cport\u003e`: Port for local HTTP server (defaults to `8080`).\n\n#### `clean`\nClears builder compiler caches, state directories, template preview files, production site outputs, build-site records, and local OSTree repositories.\nRequires confirmation unless `--yes`, `-y`, or `--confirm` is specified.\n```bash\n# Clean all temporary files (prompts for confirmation if interactive)\naetherpak clean\n\n# Clean all temporary files without prompt (useful for CI)\naetherpak clean --yes\n\n# Clean only compiler caches (ccache) and state directories\naetherpak clean --ccache --state --yes\n```\nOptions:\n* `--yes, -y`: Skip confirmation prompt.\n* `--confirm`: Skip confirmation prompt (deprecated alias for `--yes`).\n* `--ccache`: Clean only builder compiler caches (`.ccache`).\n* `--state`: Clean only builder state directories (`.state`).\n* `--preview`: Clean only template preview directories (`_preview`).\n* `--site`: Clean only production site build outputs (`_site`).\n* `--records`: Clean only build-site input/output records (`records`).\n* `--repo`: Clean only local OSTree repositories (`repo`).\n* `--ccache-dir \u003cpath\u003e`: Custom ccache directory path (defaults to `.ccache`).\n* `--state-dir \u003cpath\u003e`: Custom builder state directory path (defaults to `.state`).\n* `--preview-dir \u003cpath\u003e`: Custom preview site directory path (defaults to `_preview`).\n* `--site-dir \u003cpath\u003e`: Custom production site directory path (defaults to `_site`).\n* `--records-dir \u003cpath\u003e`: Custom records directory path (defaults to `records`).\n* `--repo-path \u003cpath\u003e`: Custom OSTree repository path (defaults to `repo`).\n\n---\n\n## Development\n\nGuidelines on compilation setup, local prerequisites, test harness drivers, and coding styles are documented in [CONTRIBUTING.md](CONTRIBUTING.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faetherpak%2Fcli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faetherpak%2Fcli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faetherpak%2Fcli/lists"}