# How the CodeWhale Binary Download Process Works: NPM Wrapper & GitHub Releases

> Understand the CodeWhale binary download process. Learn how the npm-wrapper fetches platform-specific artifacts from GitHub Releases, verifies checksums, and caches them on your machine.

- Repository: [Hunter Bown/CodeWhale](https://github.com/Hmbown/CodeWhale)
- Tags: internals
- Published: 2026-06-02

---

**The CodeWhale binary download process uses an npm-wrapper post-install script that automatically fetches platform-specific pre-built artifacts from GitHub Releases, verifies SHA-256 checksums, and caches them locally with support for retries, timeouts, and environment-variable overrides.**

The Hmbown/CodeWhale repository distributes its CLI through an npm wrapper that eliminates manual binary management. During installation, a post-install script automatically detects your platform, downloads the appropriate pre-built binary, and verifies its cryptographic hash before caching it for future use.

## Step 1: Determine the Target Asset

The download begins in [`npm/codewhale/scripts/artifacts.js`](https://github.com/Hmbown/CodeWhale/blob/main/npm/codewhale/scripts/artifacts.js), where the wrapper constructs the release URL. The script reads the desired version from the `DEEPSEEK_TUI_VERSION` environment variable or defaults to the package version. It builds a download base URL using the pattern `https://github.com/${repo}/releases/download/v${version}/`.

You can override the target repository by setting `DEEPSEEK_TUI_GITHUB_REPO`, allowing forks or mirrors to serve custom binaries.

## Step 2: Select the Platform-Specific Binary

In [`npm/codewhale/scripts/install.js`](https://github.com/Hmbown/CodeWhale/blob/main/npm/codewhale/scripts/install.js), the script inspects `process.platform` (`linux`, `darwin`, `win32`) and `process.arch` (`x64`, `arm64`) to select the correct filename. For example, Linux x64 systems receive `codewhale-linux-x64`, while Windows x64 receives `codewhale-windows-x64.exe`.

The same platform detection logic appears in [`web/components/install-binary.tsx`](https://github.com/Hmbown/CodeWhale/blob/main/web/components/install-binary.tsx), which generates the appropriate command lines for the project's documentation website.

## Step 3: Download the Checksum Manifest

Before fetching the binary itself, the script downloads [`codewhale-artifacts-sha256.txt`](https://github.com/Hmbown/CodeWhale/blob/main/codewhale-artifacts-sha256.txt) from the same GitHub Release (around line 1014 of [`install.js`](https://github.com/Hmbown/CodeWhale/blob/main/install.js)). This manifest contains the SHA-256 hash for every platform-specific asset, enabling integrity verification before the binary executes on your system.

## Step 4: Robust Binary Download with Retry Logic

The core `download(url, destination, options)` routine (lines 887-921 of [`install.js`](https://github.com/Hmbown/CodeWhale/blob/main/install.js)) implements a resilient HTTP client with several protective mechanisms:

- **Retry logic**: Automatically retries failed requests up to 5 times via `withRetry`
- **Timeout handling**: Configurable overall timeout via `downloadTimeoutMs`
- **Stall detection**: Aborts if no bytes are received for the duration specified by `downloadStallMs`
- **Progress reporting**: Displays friendly messages like "▸ downloading X (y / z MB)" during the transfer

## Step 5: Checksum Verification

After the file lands in a temporary `.download` file, the script computes its SHA-256 hash (lines 1057-1069 of [`install.js`](https://github.com/Hmbown/CodeWhale/blob/main/install.js)). It compares this computed hash against the entry from the downloaded manifest. If the hashes differ, the script discards the file and triggers another download attempt.

## Step 6: Cache and Atomic Move

Once verification succeeds, the binary moves atomically to `bin/downloads/<binary-name>`. The script creates a companion marker file (`*.sha256`) containing the expected hash. Subsequent installations check for this marker and **skip re-download** unless explicitly forced, significantly speeding up reinstalls and CI builds.

## Environment Variables for Customization

The download pipeline respects several environment variables that control behavior without modifying code:

- **`DEEPSEEK_TUI_DISABLE_INSTALL=1`**: Completely bypasses the post-install download. Essential for CI environments where binaries are pre-packed or vendored.
- **`DEEPSEEK_TUI_OPTIONAL_INSTALL=1`**: Converts download failures into warnings, allowing `npm install` to succeed even if the binary cannot be fetched.
- **`DEEPSEEK_TUI_FORCE_DOWNLOAD=1`**: Forces a fresh download even if a valid cached marker exists, useful when updating to a new patched release.
- **`DEEPSEEK_TUI_RELEASE_BASE_URL`**: Replaces the GitHub base URL with an internal mirror or proxy (e.g., `https://artifacts.internal.company.com/codewhale`).

These controls are documented in lines 1100-1120 of [`install.js`](https://github.com/Hmbown/CodeWhale/blob/main/install.js).

## Runtime Fallback and Manual Installation

If the CLI executes without a present binary, the same download machinery invokes automatically (lines 1170-1190 of [`install.js`](https://github.com/Hmbown/CodeWhale/blob/main/install.js)). This runtime fallback ensures users never need manual intervention.

Alternatively, bypass the wrapper entirely by downloading directly from GitHub Releases:

```bash
curl -L -O https://github.com/Hmbown/CodeWhale/releases/latest/download/codewhale-linux-x64
chmod +x codewhale-linux-x64 && ./codewhale-linux-x64 --help

```

These manual commands are documented in [`docs/INSTALL.md`](https://github.com/Hmbown/CodeWhale/blob/main/docs/INSTALL.md) under "Manual download from GitHub Releases".

## Common Installation Scenarios

**Standard global installation** triggers the automatic download:

```bash
npm install -g @codewhale/cli

# Binary downloads to ~/.codewhale/bin/downloads

```

**Force a fresh download** (ignore cache markers):

```bash
DEEPSEEK_TUI_FORCE_DOWNLOAD=1 npm install -g @codewhale/cli

```

**Skip download in CI** (use vendored binaries):

```bash
DEEPSEEK_TUI_DISABLE_INSTALL=1 npm ci

```

**Use an internal artifact mirror**:

```bash
DEEPSEEK_TUI_RELEASE_BASE_URL=https://artifacts.internal.company.com/codewhale npm install

```

## Key Source Files

- **[`npm/codewhale/scripts/install.js`](https://github.com/Hmbown/CodeWhale/blob/main/npm/codewhale/scripts/install.js)**: Core implementation containing URL construction, retry logic, timeout handling, and checksum verification.
- **[`npm/codewhale/scripts/artifacts.js`](https://github.com/Hmbown/CodeWhale/blob/main/npm/codewhale/scripts/artifacts.js)**: Helper functions for building release URLs and locating the local cache directory.
- **[`web/components/install-binary.tsx`](https://github.com/Hmbown/CodeWhale/blob/main/web/components/install-binary.tsx)**: React component that displays platform-specific download commands on the project website.
- **[`docs/INSTALL.md`](https://github.com/Hmbown/CodeWhale/blob/main/docs/INSTALL.md)**: Human-readable installation guide covering environment variables and manual download procedures.
- **[`npm/codewhale/README.md`](https://github.com/Hmbown/CodeWhale/blob/main/npm/codewhale/README.md)**: Summary of wrapper behavior and environment variable reference.

## Summary

- The **npm wrapper** automatically downloads platform-specific binaries from GitHub Releases during `npm install`.
- **SHA-256 checksums** are verified against a manifest before the binary executes or moves to its final location.
- **Retry logic** (up to 5 attempts), **timeout handling**, and **stall detection** ensure robust downloads across unreliable networks.
- **Environment variables** provide fine-grained control for CI pipelines, air-gapped environments, and custom mirrors without code changes.
- **Caching with marker files** prevents redundant downloads, while **runtime fallback** ensures the CLI self-heals if the binary is missing.

## Frequently Asked Questions

### What happens if the download fails during npm install?

If `DEEPSEEK_TUI_OPTIONAL_INSTALL` is unset, the installation fails with an error describing the HTTP failure or checksum mismatch. When `DEEPSEEK_TUI_OPTIONAL_INSTALL=1` is set, the script logs a warning and completes the npm install without the binary, allowing the application to attempt a runtime download later or operate in a limited capacity.

### How does CodeWhale determine which binary to download for my system?

The script examines Node.js `process.platform` and `process.arch` to map your system to one of the supported artifacts: `codewhale-linux-x64`, `codewhale-darwin-arm64`, `codewhale-windows-x64.exe`, etc. This logic lives in [`npm/codewhale/scripts/install.js`](https://github.com/Hmbown/CodeWhale/blob/main/npm/codewhale/scripts/install.js) and is shared with the documentation site's install component in [`web/components/install-binary.tsx`](https://github.com/Hmbown/CodeWhale/blob/main/web/components/install-binary.tsx).

### Can I use a private mirror instead of GitHub Releases?

Yes. Set the `DEEPSEEK_TUI_RELEASE_BASE_URL` environment variable to your internal mirror's base URL (e.g., `https://artifacts.company.com/codewhale`). The wrapper will append the version and filename to this base instead of `https://github.com/Hmbown/CodeWhale/releases/download/`. You can also override the repository path with `DEEPSEEK_TUI_GITHUB_REPO` if your mirror follows GitHub's URL structure.

### How do I verify the downloaded binary hasn't been tampered with?

The download process automatically verifies integrity by comparing the SHA-256 hash of the downloaded file against the entry in [`codewhale-artifacts-sha256.txt`](https://github.com/Hmbown/CodeWhale/blob/main/codewhale-artifacts-sha256.txt) fetched from the same release. If verification fails, the script deletes the corrupted file and retries the download. Manual verification is also possible by running `sha256sum codewhale-linux-x64` and comparing the output against the manifest hosted on the official release page.