CodeWhale First Run Setup: Installation, Authentication, and Verification Guide

Run npm install -g codewhale, execute codewhale in your project directory to generate ~/.codewhale/config.toml, set your API key with codewhale auth set --provider deepseek, and verify with codewhale doctor to complete the first run setup.

CodeWhale is an AI-augmented coding assistant shipped as two binaries—the dispatcher (codewhale) and the terminal UI runtime (codewhale-tui). This guide walks through the complete first run setup process, from binary installation to environment verification, as implemented in the Hmbown/CodeWhale repository.

Phase 1: Installing the CodeWhale Binaries

CodeWhale requires both the dispatcher and TUI runtime binaries available on your PATH. The dispatcher locates its TUI partner at runtime via a simple PATH lookup, and they must be version-matched according to docs/INSTALL.md.

Install via npm (Recommended)

The npm package pulls pre-built binaries and writes them to $(npm prefix -g)/bin. The post-install script enforces version matching via a SHA-256 manifest.

npm install -g codewhale
codewhale  # triggers the post-install download of the matching binaries

Install via Cargo

Build from source for any Tier-1 Rust target. This installs both components separately:

cargo install codewhale-cli --locked   # dispatcher

cargo install codewhale-tui --locked    # TUI runtime

Install via Docker

Run in an isolated container with persistent volumes for configuration:

docker volume create codewhale-home
docker run --rm -it \
  -e DEEPSEEK_API_KEY="$DEEPSEEK_API_KEY" \
  -v codewhale-home:/home/codewhale/.codewhale \
  -v "$PWD:/workspace" -w /workspace \
  ghcr.io/hmbown/codewhale:latest

Alternative methods including Homebrew, Nix, Windows installers, and manual download are documented in docs/INSTALL.md.

Phase 2: Bootstrapping the Runtime and Configuration

Navigate to your project directory and launch the dispatcher. On first run, CodeWhale reads or creates the runtime configuration.

cd /path/to/your/project
codewhale

The dispatcher performs the following initialization sequence defined in docs/GUIDE.md:

• Creates ~/.codewhale/config.toml if it does not exist
• Falls back to legacy ~/.deepseek/config.toml for backward compatibility

Configuration Hierarchy

The runtime resolves configuration using the following precedence order:

1. Environment variables (highest priority)
2. ~/.codewhale/config.toml (new standard location)
3. ~/.deepseek/config.toml (legacy location)

This layered approach allows temporary overrides without editing files.

Phase 3: Authentication and Provider Setup

CodeWhale defaults to the DeepSeek provider. You must supply a valid API key before initiating your first task.

Interactive Authentication

Run the auth command to persist credentials to the configuration file:

codewhale auth set --provider deepseek

Environment Variable Method

For CI pipelines or Docker containers, export the key before running:

export DEEPSEEK_API_KEY="your-key"
codewhale

Provider definitions and alternative endpoints are documented in docs/PROVIDERS.md. The same flow works for any OpenAI-compatible endpoint once the proper provider ID is set.

Phase 4: Verifying Your Installation

Run the health-check command to validate the binary pair, stored configuration, and provider credentials:

codewhale doctor           # human-readable report

codewhale doctor --json    # machine-readable JSON for issue filing

A successful verification confirms:

• Both codewhale and codewhale-tui are discoverable on PATH
• The stored API key is valid for the chosen provider
• No conflicting environment variables override the saved config

A non-zero exit code signals a problem that must be resolved before productive use, as noted in docs/INSTALL.md.

Understanding the Dispatcher-Runtime Architecture

The dispatcher spawns the TUI runtime via process execution. Key architectural constraints include:

• PATH Dependency: The dispatcher expects codewhale-tui available in the same PATH context
• Version Coupling: Binaries must be version-matched. The npm post-install script enforces this via SHA-256 checksums against a manifest
• Runtime Spawning: When you execute codewhale, it delegates terminal rendering to the codewhale-tui binary

After successful verification, you are ready to start your first task:

codewhale ask "What files define the CLI entry point?"

Summary

• CodeWhale consists of two binaries: the dispatcher (codewhale) and the TUI runtime (codewhale-tui), which must be version-matched and available on PATH
• Configuration resides in ~/.codewhale/config.toml, with fallback support for the legacy ~/.deepseek/config.toml location
• Authentication defaults to DeepSeek via codewhale auth set --provider deepseek or the DEEPSEEK_API_KEY environment variable
• Always verify your installation using codewhale doctor before starting productive work to ensure binary compatibility and valid credentials

Frequently Asked Questions

Where does CodeWhale store its configuration files?

CodeWhale stores runtime configuration in ~/.codewhale/config.toml. If this file does not exist on first launch, the dispatcher creates it automatically. For backward compatibility, CodeWhale will read from the legacy ~/.deepseek/config.toml location if the new path is empty, as documented in docs/GUIDE.md.

Can I use CodeWhale with OpenAI-compatible providers other than DeepSeek?

Yes. While DeepSeek is the default provider, you can configure any OpenAI-compatible endpoint by setting the appropriate provider ID via codewhale --provider <id> or the /provider command inside the TUI. Refer to docs/PROVIDERS.md for available provider IDs and their specific credential requirements.

How do I fix "binary not found" errors during first run?

Ensure both codewhale and codewhale-tui are installed and available on your PATH. If installing via npm, run codewhale once to trigger the post-install download of the TUI binary. For Cargo installations, verify that $HOME/.cargo/bin is in your PATH. Run codewhale doctor to diagnose specific binary discovery issues.

Is it safe to commit the ~/.codewhale/config.toml file to version control?

No. This file typically contains sensitive API keys and provider credentials. Keep it in your home directory and add it to your .gitignore if working within a repository. Use environment variables like DEEPSEEK_API_KEY for CI environments rather than committing the configuration file.

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