Distribution & SEA Compilation
Relevant source files
The following files were used as context for generating this wiki page:
The putio-cli project is a standalone TypeScript package built for the put.io API. It is designed with an "agent-first" philosophy, prioritizing deterministic automation and machine-readable output. Distribution is handled through multiple channels, including the npm registry, Homebrew, and a custom shell installer that deploys prebuilt binaries. These binaries are generated as Single Executable Applications (SEA), allowing the CLI to run without a local Node.js installation on the consumer's machine.
Sources: CLAUDE.md:1-10, README.md:1-15, package.json:1-15
Build System & Environment
The project utilizes Node.js (version 24.14.0 or higher) and the Effect ecosystem for its core logic. The build process is orchestrated via vite-plus and custom scripts defined in package.json.
Core Development Commands
The build lifecycle includes several specialized commands for packing the library and preparing it for distribution:
| Command | Description | Source File |
|---|---|---|
npm run build | Executes vp pack to bundle the TypeScript source into ./dist. | package.json:34 |
npm run build:sea | Executes a custom script to generate Single Executable Applications. | package.json:35 |
npm run verify:sea | Runs verification checks on the generated SEA binaries. | package.json:42 |
npm run smoke:pack | Validates the integrity of the packed installation. | package.json:40 |
Sources: package.json:33-43, CONTRIBUTING.md:10-30
Single Executable Application (SEA) Compilation
The CLI leverages Node.js's native SEA capabilities to provide zero-dependency binaries. This process wraps the bundled JavaScript code and a Node.js runtime into a single executable file.
Compilation Workflow
The compilation process involves multiple stages, from initial TypeScript bundling to the final injection of the resource blob into a platform-specific executable.
This diagram illustrates the transformation of source code into a standalone binary.
Sources: package.json:35-42, CONTRIBUTING.md:25-30
SEA Dependencies
The project uses postject as a developer dependency to facilitate the injection of the cross-platform resource blob into the Node binary. The project is restricted to Node.js versions between 24.14.0 and 25 to ensure compatibility with the SEA implementation used.
Sources: package.json:54-60
Distribution Channels
The project supports three primary distribution methods to accommodate different user environments.
1. NPM Registry
The package is published as @putdotio/cli on the npm registry. It targets Node.js runtimes meeting the engines requirement.
- Package Name:
@putdotio/cli - Entry Points:
./dist/index.mjs(library) and./dist/bin.mjs(binary). - Global Install:
npm install --global @putdotio/cli
Sources: package.json:1-25, README.md:55-60
2. Homebrew
MacOS users can install the CLI via a dedicated tap:
brew tap putdotio/homebrew-tap && brew install putio-cli
Sources: README.md:30-35
3. Shell Installer (install.sh)
For users on macOS and Linux who do not wish to use npm or Homebrew, a standalone shell installer is provided. This script automates the detection, download, and verification of SEA binaries.
Platform Detection Logic
The installer identifies the system architecture and operating system to fetch the correct asset from GitHub Releases.
| OS (uname -s) | Arch (uname -m) | Platform ID | Architecture ID |
|---|---|---|---|
| Darwin | arm64 | darwin | arm64 |
| Linux | x86_64 / amd64 | linux | amd64 |
Sources: install.sh:20-38
Installation Workflow (install.sh)
The install.sh script follows a rigorous process to ensure secure installation of the SEA binary.
This sequence diagram shows the automated download and verification process performed by the installer.
Sources: install.sh:10-155
Security and Verification
The installer performs several security checks:
- Checksum Verification: Uses
shasum,sha256sum, oropensslto verify the downloaded asset against a.sha256manifest. - Permissions: Ensures the installation directory (
~/.local/binby default) is not group/world-writable unless explicitly allowed viaPUTIO_CLI_ALLOW_SHARED_INSTALL_DIR. - Pathing: Prompts the user to add the installation directory to their
PATHif it is missing.
Sources: install.sh:40-54, install.sh:92-126
Summary of Release Assets
Release assets follow a specific naming convention used by both the automated release process and the installer:
putio-cli-${VERSION}-${platform}-${architecture}.tar.gz
The binary name inside the package and the resulting command is always putio.