How to Install CodeWhale Globally via npm: Complete Setup Guide

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)
• 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:

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

2. Run the global install command:

npm install -g codewhale

3. Verify the installation:

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. When you run npm install -g codewhale, the wrapper executes npm/codewhale/scripts/install.js automatically.

The installer performs these operations:

• Version Resolution: Reads codewhaleBinaryVersion from 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 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
• 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

DEEPSEEK_TUI_VERSION=0.8.45 npm install -g codewhale

Example: Using an Internal Mirror

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

Example: Optional Install for CI

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:

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:

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:

npm install -g codewhale

Force re-download with specific version:

DEEPSEEK_TUI_VERSION=0.8.40 DEEPSEEK_TUI_FORCE_DOWNLOAD=1 npm install -g codewhale

Install via pnpm:

pnpm add -g codewhale

After installation, authenticate and start using CodeWhale:

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
• 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, 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. 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}