omnidist

Omnidist builds one Go CLI and packages its prebuilt binaries for npm, PyPI-compatible indexes through uv, and RubyGems. npm packages contain no postinstall downloader; installation uses platform-specific optional dependencies already present in registry tarballs.

Install or run

Consumers only need the package manager for the channel they use:

npx -y @omnidist/omnidist@latest --help
uvx omnidist --help
gem install omnidist && omnidist --help

Maintainers can also install from Go:

go install github.com/metalagman/omnidist/cmd/omnidist@latest

Maintainer prerequisites

You do not need tooling for backends absent from the selected set.

Safe quick start

Run this in an existing Go repository with one package main under cmd/*:

omnidist init
$EDITOR .omnidist/omnidist.yaml
omnidist build
omnidist stage
omnidist verify
omnidist publish --dry-run

init detects the command name and main package. If discovery is ambiguous, specify both explicitly:

omnidist init --name mytool --main ./cmd/mytool

It refuses to replace an existing config. omnidist init --force intentionally replaces that file and is destructive; review or back it up first.

The generated file uses profiles mode and stores artifacts beneath .omnidist/default/. Select which package ecosystems participate in aggregate commands and generated CI:

profiles:
  default:
    tool:
      name: mytool
      main: ./cmd/mytool
    version:
      source: git-tag
    targets:
      - os: linux
        arch: amd64
    build:
      ldflags: -s -w
      tags: []
      cgo: false
    distributions:
      npm:
        package: "@my-org/mytool"
      pypi:
        package: mytool

The npm and pypi sections select those two backends. Add or remove npm, pypi, and gem sections to define the canonical aggregate set. Existing files with a non-empty enabled-distributions selector remain readable, but every selected backend must have its own section. Aggregate commands always execute in npm → pypi → gem order. --only can narrow the configured set but cannot enable an unavailable backend; backend-specific commands also require an explicit section.

To offer both unscoped and scoped install names while publishing one shared platform package set, configure the unscoped package as primary, add the scoped name to aliases, and use the scoped base for platform packages:

distributions:
  npm:
    package: omnidist
    aliases:
      - "@omnidist/omnidist"
    platform-package: "@omnidist/omnidist"
    access: public

Users can then install either equivalent meta package:

npm install -g omnidist
npm install -g @omnidist/omnidist

Both meta packages reference platform packages such as @omnidist/omnidist-linux-x64; the binaries are not duplicated under each meta-package name. package is published first among meta packages, followed by aliases in configured order, after all unique platform packages. If aliases is omitted, Omnidist publishes only package. If platform-package is omitted or blank, it defaults to package, preserving existing package names. The configured npm identity must be allowed to publish every meta and platform name; trusted publishing must be configured for every generated package.

Release flow

omnidist build
omnidist stage
omnidist verify
omnidist publish --dry-run
omnidist publish

Aggregate publish preflights every selected backend before the first upload. This prevents locally detectable late-backend failures from causing an avoidable partial release. Registry uploads are still external and are not transactionally reversible: a network or registry failure after uploads begin can leave a partial release.

Generate backend-aware GitHub Actions after the config is final:

omnidist ci
# use --force only to intentionally replace the generated workflow

The workflow contains setup, credentials, and publish jobs only for selected backends, plus a GitHub Release job for the built binaries.

Reference

• Configuration reference — profiles, every YAML field, defaults, paths, and compatibility.
• Release runbook — credentials, first release, preflight, trusted publishing, and partial-release recovery.
• Targets and variants — Go target values and npm/wheel/gem mappings.
• Contributing — repository layout, tests, lint, and development workflow.

Commands

omnidist init [--force] [--name <name>] [--main <package>]
omnidist quickstart
omnidist build
omnidist stage [--dev] [--only npm,pypi,gem]
omnidist verify [--only npm,pypi,gem]
omnidist publish [--dry-run] [--only npm,pypi,gem]
omnidist ci [--force] [--dry-run]
omnidist npm stage|verify|publish|trust
omnidist pypi stage|verify|publish
omnidist gem stage|verify|publish

Global flags are --config, --profile, and --omnidist-root. Omnidist also loads .env; corresponding selectors are OMNIDIST_CONFIG, OMNIDIST_PROFILE, and OMNIDIST_OMNIDIST_ROOT.

Use omnidist <command> --help for backend-specific options. Earlier configuration, commands and environment variables remain supported; see legacy compatibility.

Common failures

• Version resolution: an exact SemVer tag is required for git-tag; file reads version.file; env reads OMNIDIST_VERSION; fixed requires version.fixed.
• Missing build version: run omnidist build before stage. Profiles store it at .omnidist/<profile>/dist/VERSION; legacy config uses .omnidist/dist/VERSION.
• Missing npm platform package: run omnidist npm verify and confirm the target matrix and equal versions.
• PyPI rejects +...: public PyPI/TestPyPI reject local version metadata; stage a publishable version.
• Trusted publish fails: local preflight cannot prove remote OIDC configuration. Confirm repository metadata, workflow filename/environment, id-token: write, and registry-side trusted publisher settings.