Metadata-Version: 2.5
Name: bin-upload
Version: 0.3.0
Summary: Publish binaries to npm, pypi, and github releases.
Author: Derek Worthen
Author-Email: worthend.derek@gmail.com
License-Expression: MIT
Requires-Python: >=3.11
Project-URL: source, https://github.com/dworthen/bin-upload
keywords: bin-upload,binary,pypi,npm,github,publish
Description-Content-Type: text/markdown

# Bin Upload

> Easily distribute binaries via npm, pypi, and GitHub releases.

`bin-upload` is a CLI tool built with [Bun](https://bun.sh) that packages and publishes pre-built binaries to multiple registries and platforms. It supports:

- **npm** — Publishes a main package that depends on platform-specific binary packages using [optionalDependencies](https://docs.npmjs.com/cli/v11/configuring-npm/package-json#optionaldependencies).
- **PyPI** — Builds wheel (`.whl`) packages for each platform-specific tag.
- **GitHub Releases** — Creates releases and uploads archive assets (`.tar.gz` or `.zip`).

[Full documentation](https://dworthen.github.io/bin-upload/).

## Installation

<!-- tabs:start -->

### **NPM**

```sh
# Globally
npm install -g @d-dev/bin-upload
# or as a package dep
npm install -D @d-dev/bin-upload
# or run with npx
npx @d-dev/bin-upload <command>
```

### **Python**

```sh
pip install bin-upload
# or with UV
uv tool install bin-upload
# or run with uvx
uvx bin-upload <command>
```

### **GitHub Releases**

Download the appropriate binary for your platform from the [releases page](https://github.com/dworthen/bin-upload/releases).

<!-- tabs:end -->

## Requirements

The following must be installed and available on your path.

- [npm](https://www.npmjs.com/): if publishing to npm
- [uv](https://docs.astral.sh/uv/): if publishing to pypi

## 1. Init

```sh
bin-upload init
```

This will walk you through an interactive prompt and generate a `bin-upload.config.yaml` file.

More on configuration [here](/configuration).

## 2. Pack

### Git flow

```
git add .
git commit -m "..."
git tag -a v1.0.0 -m "Release v1.0.0"
bin-upload pack
```

### Non-git flow

```sh
bin-upload pack -s npm.packageJson.version=1.0.0 -s pypi.metadata.Version=1.0.0
```

This will generate artifacts in `.bin-upload` that can be published to npm (tarballs), pypi (wheel), and GitHub (tarballs and zips).

More on the pack command, including how to test artifacts prior to publishing, can be viewed [here](/pack).

## 3. Publish

Create a `.env` file with the following tokens.

```
# NPM granular access token that bypasses 2FA
# https://docs.npmjs.com/about-access-tokens
NPM_TOKEN="YOUR NPM TOKEN"
# GitHub token with repository metadata read and
# contents write permissions
GITHUB_TOKEN="YOUR GITHUB TOKEN"
PYPI_TOKEN="YOUR PYPI TOKEN"
```

### Git flow

```
git push origin main --follow-tags
bin-upload publish
```

### Non-git flow

```sh
bin-upload publish
```

This publishes the artifacts generated by the `pack` command.

More on the publish command, including how to publish with GitHub actions, can be viewed [here](/publish).

## Verify

Once published, install from npm or PyPI and confirm:

```sh
# npm
npx YOUR_PACKAGE ...

# PyPI
uvx YOUR_PACKAE ...
```

[Full documentation](https://dworthen.github.io/bin-upload/).
