# How to Install CodeWhale Globally via npm: Complete Setup Guide

> Install CodeWhale globally with npm using a simple command. Our guide ensures a smooth setup by automatically downloading necessary binaries for your platform. Get started now.

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

---

**Run `npm install -g codewhale` to install CodeWhale globally, which automatically downloads the correct pre-built binaries for your platform during the post-install phase.**

CodeWhale distributes a lightweight **npm wrapper** that handles binary distribution through the npm registry. When you install CodeWhale globally via npm, the package pulls platform-specific executables from GitHub Releases and exposes the `codewhale` and `codewhale-tui` commands on your system `PATH`. This approach ensures you always receive the correct architecture without manual download steps.

## Prerequisites

Before installing CodeWhale globally via npm, ensure your environment meets these requirements:

- **Node.js** version 18 or higher (the installer validates this immediately in [`npm/codewhale/scripts/install.js`](https://github.com/Hmbown/CodeWhale/blob/main/npm/codewhale/scripts/install.js))
- **npm**, **pnpm**, or **yarn** package manager
- Internet access to download pre-built binaries from GitHub Releases (or your configured mirror)

## Step-by-Step Installation

Follow these steps to install CodeWhale globally using npm:

1. **Verify Node.js version**:

```bash
node --version  # Must output v18.x.x or higher

```

2. **Run the global install command**:

```bash
npm install -g codewhale

```

3. **Verify the installation**:

```bash
codewhale --version   # Displays installed version

codewhale doctor      # Runs health check on PATH and configuration

```

The installation completes when the `codewhale` and `codewhale-tui` executables appear in your global npm bin directory (typically `$(npm prefix -g)/bin`).

## How the npm Installation Works

The global installation process relies on a **postinstall hook** defined in [`npm/codewhale/package.json`](https://github.com/Hmbown/CodeWhale/blob/main/npm/codewhale/package.json). When you run `npm install -g codewhale`, the wrapper executes [`npm/codewhale/scripts/install.js`](https://github.com/Hmbown/CodeWhale/blob/main/npm/codewhale/scripts/install.js) automatically.

The installer performs these operations:

- **Version Resolution**: Reads `codewhaleBinaryVersion` from [`npm/codewhale/package.json`](https://github.com/Hmbown/CodeWhale/blob/main/npm/codewhale/package.json) to determine which release to fetch
- **Platform Detection**: Identifies your operating system and architecture to select the correct binary
- **Download with Retry**: Uses exponential back-off and stall detection to download `codewhale` and `codewhale-tui` from GitHub Releases
- **Checksum Verification**: Validates SHA-256 hashes against [`codewhale-artifacts-sha256.txt`](https://github.com/Hmbown/CodeWhale/blob/main/codewhale-artifacts-sha256.txt) from the same release
- **Proxy Support**: Respects `HTTPS_PROXY`, `HTTP_PROXY`, and `NO_PROXY` environment variables
- **Installation**: Writes binaries to the global npm bin directory and sets executable permissions

## Environment Variables for Custom Installation

The npm wrapper supports several environment variables to customize the installation behavior when you install CodeWhale globally via npm:

- **`DEEPSEEK_TUI_VERSION`**: Pin a specific release version instead of using the default in [`package.json`](https://github.com/Hmbown/CodeWhale/blob/main/package.json)
- **`DEEPSEEK_TUI_GITHUB_REPO`**: Use a fork or mirror repository (format: `owner/repo`)
- **`DEEPSEEK_TUI_RELEASE_BASE_URL`**: Download binaries from an internal mirror instead of GitHub
- **`DEEPSEEK_TUI_FORCE_DOWNLOAD`**: Set to `1` to force re-download even if cached binaries exist
- **`DEEPSEEK_TUI_OPTIONAL_INSTALL`**: Set to `1` to convert download failures into warnings (useful for CI pipelines where downloads happen on first runtime instead)

### Example: Pinning a Specific Version

```bash
DEEPSEEK_TUI_VERSION=0.8.45 npm install -g codewhale

```

### Example: Using an Internal Mirror

```bash
DEEPSEEK_TUI_RELEASE_BASE_URL=https://mirror.example.com/CodeWhale npm install -g codewhale

```

### Example: Optional Install for CI

```bash
DEEPSEEK_TUI_OPTIONAL_INSTALL=1 npm install -g codewhale

```

## Proxy Configuration and Regional Mirrors

If you operate behind a corporate firewall or in regions with restricted GitHub access, configure proxy settings before you install CodeWhale globally via npm:

**Standard proxy variables**:

```bash
export HTTPS_PROXY=http://proxy.example.com:8080
export HTTP_PROXY=http://proxy.example.com:8080
export NO_PROXY=localhost,127.0.0.1
npm install -g codewhale

```

**For users in mainland China**, switch to the npmmirror registry to speed up the initial npm package download:

```bash
npm config set registry https://registry.npmmirror.com
npm install -g codewhale

```

## Common Installation Patterns

Here are complete code examples for different scenarios when you install CodeWhale globally via npm:

**Standard global installation**:

```bash
npm install -g codewhale

```

**Force re-download with specific version**:

```bash
DEEPSEEK_TUI_VERSION=0.8.40 DEEPSEEK_TUI_FORCE_DOWNLOAD=1 npm install -g codewhale

```

**Install via pnpm**:

```bash
pnpm add -g codewhale

```

After installation, authenticate and start using CodeWhale:

```bash
codewhale login --api-key $DEEPSEEK_API_KEY
codewhale models
codewhale "def hello():\n    print('hi')"

```

## Summary

- **Install CodeWhale globally via npm** using `npm install -g codewhale`, which triggers the `postinstall` script in [`npm/codewhale/scripts/install.js`](https://github.com/Hmbown/CodeWhale/blob/main/npm/codewhale/scripts/install.js)
- The wrapper requires **Node.js ≥ 18** and downloads verified binaries from GitHub Releases during installation
- Use **`DEEPSEEK_TUI_*` environment variables** to customize versions, mirrors, proxy settings, and download behavior
- The installer validates binaries using **SHA-256 checksums** and supports exponential backoff retries for unreliable networks
- Set **`DEEPSEEK_TUI_OPTIONAL_INSTALL=1`** for CI environments to defer binary downloads to runtime

## Frequently Asked Questions

### What Node.js version is required to install CodeWhale globally via npm?

CodeWhale requires **Node.js 18 or higher**. The installer checks your Node version immediately when the `postinstall` script runs in [`npm/codewhale/scripts/install.js`](https://github.com/Hmbown/CodeWhale/blob/main/npm/codewhale/scripts/install.js), aborting early with a clear error message if your runtime is outdated.

### Where does the npm installer download the CodeWhale binaries from?

By default, the installer pulls pre-built binaries from the **GitHub Releases** page of the `Hmbown/CodeWhale` repository. The specific release version is determined by the `codewhaleBinaryVersion` field in [`npm/codewhale/package.json`](https://github.com/Hmbown/CodeWhale/blob/main/npm/codewhale/package.json). You can override this source using the `DEEPSEEK_TUI_GITHUB_REPO` or `DEEPSEEK_TUI_RELEASE_BASE_URL` environment variables.

### How do I force a re-download of the binaries when installing CodeWhale via npm?

Set the `DEEPSEEK_TUI_FORCE_DOWNLOAD` environment variable to `1` before running the install command. This forces the [`install.js`](https://github.com/Hmbown/CodeWhale/blob/main/install.js) script to download fresh binaries even if valid cached versions exist in your global npm directory, ensuring you receive the latest build.

### Can I install CodeWhale via npm without downloading binaries immediately?

Yes. Set `DEEPSEEK_TUI_OPTIONAL_INSTALL=1` before installation. This converts download failures into non-fatal warnings during `npm install`, allowing the package to install without binaries. The actual download then occurs automatically on the first execution of `codewhale` or `codewhale-tui`, making this ideal for CI pipelines with restricted build-time network access.