Publish CLI to package managers

[pewpewpotato]

Functional Specification: Publish CLI to Package Managers

Overview

The Nomos CLI should be installable through the major package managers that support Go binaries, allowing users to install, update, and manage the CLI using familiar tooling on their operating system. This removes the need for users to manually download and configure binaries, lowering the barrier to adoption and improving the day-to-day experience for existing users. The initial focus is on winget for Windows, with Homebrew (macOS/Linux) and a universal Linux format as follow-on targets.

Goals

• Winget (Windows) is the first-priority package manager target; the Nomos CLI must be listed and installable via winget install nomos.
• Users on macOS and Linux can install the Nomos CLI using Homebrew and a universal Linux format (e.g., Snap or a Homebrew-compatible tap) respectively.
• Installation via any supported package manager produces a working CLI that behaves identically to a manually downloaded binary.
• New releases of the Nomos CLI are made available in supported package managers by maintainers manually updating listings after each release; a short delay after publishing is acceptable.
• The steps required for maintainers to update each package manager listing after a release are clearly documented so the process can be repeated consistently.

Non-Goals

• Publishing to package managers that do not support Go binaries or that have prohibitively complex submission processes.
• Providing a graphical installer or setup wizard.
• Supporting package manager plugins, extensions, or ecosystem integrations beyond basic install/upgrade/uninstall.
• Backwards-compatibility shims or legacy version pinning beyond what the package manager natively supports.
• Distributing distro-specific package formats (.deb, .rpm, etc.); universal formats are sufficient.
• Automating the package manager publish step as part of CI/CD; manual updates by maintainers are acceptable.

User Stories

• As a Windows developer, I want to install the Nomos CLI with winget install nomos so that I can integrate it into my existing development workflow without manually managing binaries.
• As a macOS developer, I want to install the Nomos CLI with brew install nomos so that I can get started without manually downloading a binary.
• As a Linux developer, I want to install the Nomos CLI using a universal package format (e.g., Snap) so that updates are managed alongside my other tools without requiring distro-specific packages.
• As a Nomos user, I want to upgrade to the latest version by running my package manager's standard upgrade command so that I always have access to the newest features and fixes.
• As a CI/CD engineer, I want to install the Nomos CLI in a pipeline using a single package manager command so that I can automate Nomos compilation steps without managing binary downloads manually.
• As a maintainer, I want clear documentation on how to update each package manager listing after a release so that I can publish new versions consistently and without ambiguity.

Acceptance Criteria

1. The Nomos CLI is installable via winget on Windows; this is a required condition for the feature to be considered complete.
2. The Nomos CLI is installable via Homebrew on macOS and Linux (desirable, may follow in a subsequent iteration).
3. The Nomos CLI is installable via at least one universal Linux format such as Snap (desirable, may follow in a subsequent iteration).
4. Running the install command on any supported package manager results in the nomos binary being available on the user's PATH without additional manual configuration.
5. The installed CLI version matches the published release version and produces the correct output when nomos --version is run.
6. Users can upgrade the CLI to a newer release by running the package manager's standard upgrade command (e.g., winget upgrade nomos, brew upgrade nomos).
7. Users can uninstall the CLI cleanly using the package manager's standard uninstall command.
8. Maintainer documentation describes the exact steps to update each supported package manager listing after a new release is published.
9. Installation instructions in the project's README or documentation are updated to include package manager steps for all supported platforms.

Assumptions & Dependencies

• Existing release pipeline: Cross-platform pre-built binaries for common architectures (e.g., amd64, arm64) are already produced by the existing CI/CD pipeline as part of the release process; no new release infrastructure needs to be created.
• Winget first: Winget is the highest-priority target. Homebrew and universal Linux formats will follow but may be delivered in subsequent iterations.
• Universal Linux formats only: Distro-specific package formats (.deb, .rpm) are not required; a universal format such as Snap or a Homebrew tap is sufficient for Linux users.
• Manual maintenance: Maintainers will manually update package manager listings after each release. A short delay between a Nomos release and its availability in package managers is acceptable.
• No CI/CD automation for publishing: Automating the publish step through the existing CI/CD pipeline is explicitly out of scope for this specification.
• Versioned release tags: A stable, versioned tagging convention for releases is assumed to exist or will exist before package manager listings are created.

---

Originally described as: "We need to be able to publish the cli to the major package managers that supports go binaries."

Status

This specification is complete. Please add the ready-for-design label when you are satisfied with the requirements.

Generated by Feature Specification Refinement for issue #143

[github-actions]

Clarifying Questions

Here are some questions to help refine this specification further:

1. Which package managers are highest priority? For example, is Homebrew (macOS/Linux) the most important first target, or does the team want to ship all platforms simultaneously? Knowing the priority order will help scope the initial release of this feature.

2. How are new releases currently published? Is there an existing CI/CD pipeline that produces tagged release binaries, or does this feature also need to establish the release process? Understanding the current state will clarify what's already in place versus what needs to be built.

3. Who is responsible for maintaining the package manager listings over time? For some package managers (e.g., Homebrew taps, AUR), someone must keep the formula/manifest up to date after each release. Should this be automated through CI, handled manually by maintainers, or delegated to community contributors?

4. Are there specific Linux distributions or package formats that must be supported? For instance, is there a need for .deb/.rpm packages for enterprise/server environments, or is a universal format like Snap or a Homebrew-compatible tap sufficient for now?

5. What is the acceptable delay between a Nomos release and its availability in package managers? This affects whether the publish step needs to be fully automated or whether a manual update within a day or two is acceptable, which in turn influences the complexity of the solution.

Generated by Feature Specification Refinement for issue #143

[pewpewpotato]

1. Winget
2. In an existing CI/CD pipeline
3. Should be manual for now
4. Universal formats
5. Delay is acceptable for now

[github-actions]

Specification Updated

The functional specification has been revised to incorporate your answers to the clarifying questions. Here is a summary of what changed:

• Overview: Clarified that winget is the initial priority target, with Homebrew and Linux universal formats as follow-on.
• Goals: Winget listed as the first-priority target; updated to reflect that maintainers will manually update listings after each release (short delay acceptable); removed mention of automation.
• Non-Goals: Added explicit exclusions for distro-specific formats (.deb, .rpm) and CI/CD automation of the publish step.
• User Stories: Reordered to lead with the Windows/winget story; added a maintainer story covering the documentation of the release update process.
• Acceptance Criteria: Marked winget support as required; Homebrew and Linux universal format as desirable; added a criterion requiring maintainer documentation for the update process.
• Assumptions & Dependencies: Updated to reflect that the existing CI/CD pipeline already produces release binaries; clarified that publishing is a manual step; noted that distro-specific formats are out of scope.

All clarifying questions have been answered. The specification is now marked complete — please add the ready-for-design label when you are satisfied with the requirements.

Generated by Feature Specification Refinement for issue #143