| 1 | # Installing Codewhale |
| 2 | |
| 3 | This page covers every supported install path and the most common |
| 4 | "it didn't install" failures, including **Linux ARM64** and other less |
| 5 | common platforms. |
| 6 | |
| 7 | If you just want the short version, see the |
| 8 | [main README](../README.md#install) or |
| 9 | [简体中文 README](../README.zh-CN.md#安装). |
| 10 | |
| 11 | This branch describes the **v0.9.4 source candidate**. Install commands that use |
| 12 | `latest` resolve to the latest published package or GitHub Release, which may |
| 13 | trail the source candidate. A candidate is not a published install until the |
| 14 | matching package, tag, checksums, and release assets exist. |
| 15 | |
| 16 | On macOS and Linux, the website installer is the shortest install/update path: |
| 17 | |
| 18 | ```bash |
| 19 | curl -fsSL https://codewhale.net/install.sh | sh |
| 20 | ``` |
| 21 | |
| 22 | It downloads the matching `codewhale`, `codew`, and `codewhale-tui` release binaries, |
| 23 | verifies them against `codewhale-artifacts-sha256.txt`, installs to |
| 24 | `~/.local/bin` by default, and exposes the `codew` convenience command. |
| 25 | |
| 26 | --- |
| 27 | |
| 28 | ## 1. Supported platforms |
| 29 | |
| 30 | Published Codewhale releases ship matched `codewhale`, `codew`, and |
| 31 | `codewhale-tui` prebuilt binaries for their supported platform/architecture |
| 32 | combinations. The table below is the intended v0.9.4 candidate matrix; |
| 33 | Android/Termux is preview pending real-device QA. Linux ARM64 is available from |
| 34 | v0.8.8 onward. Linux RISC-V prebuilts are temporarily paused because the locked |
| 35 | `rquickjs-sys` dependency does not ship `riscv64gc-unknown-linux-gnu` bindings. |
| 36 | |
| 37 | | Platform | Architecture | npm install | `cargo install` | GitHub release asset | |
| 38 | | ------------ | ------------ | :---------: | :-------------: | ----------------------------------------------------- | |
| 39 | | Linux | x64 (x86_64) | ✅ | ✅ | `codewhale-linux-x64`, `codew-linux-x64`, `codewhale-tui-linux-x64` | |
| 40 | | Linux | arm64 | ✅ | ✅ | `codewhale-linux-arm64`, `codew-linux-arm64`, `codewhale-tui-linux-arm64` | |
| 41 | | Android / Termux | arm64 (aarch64) | ⚠️⁴ preview | ⚠️⁴ preview | `codewhale-android-arm64.tar.gz` preview archive when published | |
| 42 | | Linux | riscv64 | ❌¹ | ❌³ | temporarily unsupported until upstream bindings land | |
| 43 | | macOS | x64 | ✅ | ✅ | `codewhale-macos-x64`, `codew-macos-x64`, `codewhale-tui-macos-x64` | |
| 44 | | macOS | arm64 (M-series) | ✅ | ✅ | `codewhale-macos-arm64`, `codew-macos-arm64`, `codewhale-tui-macos-arm64` | |
| 45 | | Windows | x64 | ✅ | ✅ | `codewhale-windows-x64.exe`, `codew-windows-x64.exe`, `codewhale-tui-windows-x64.exe` | |
| 46 | | Windows | arm64 | ✅ | ✅ | `codewhale-windows-arm64.exe`, `codew-windows-arm64.exe`, `codewhale-tui-windows-arm64.exe` | |
| 47 | | Linux x64 on musl (Alpine) | ✅ (static) | ✅ | ✅ | static `codewhale-tui-linux-x64` (musl) asset | |
| 48 | | Other Linux (musl non-x64, other arches) | — | ❌¹ | ✅² | build from source | |
| 49 | | FreeBSD / OpenBSD | — | ❌ | ✅² | build from source | |
| 50 | |
| 51 | ¹ The npm package will exit with a clear error and point you here. |
| 52 | ² Provided your toolchain can compile a recent Rust workspace; see |
| 53 | [Build from source](#7-build-from-source) below. |
| 54 | ³ RISC-V source builds currently need upstream `rquickjs-sys` RISC-V bindings or |
| 55 | a bindgen-enabled dependency build. |
| 56 | ⁴ The v0.9.4 source-candidate npm wrapper recognizes Android arm64 and resolves |
| 57 | the matching `codewhale`, `codew`, and `codewhale-tui` Android assets. npm |
| 58 | installation works only for a package version whose GitHub Release publishes |
| 59 | those matching assets. The Android/Termux path remains preview-only until the |
| 60 | real-device compile, startup, approval, file-tool, and update checks tracked |
| 61 | in #4236 and #4242 are complete. |
| 62 | |
| 63 | Android / Termux is not the same target as Linux arm64. Do not install the |
| 64 | GNU libc `codewhale-linux-arm64` archive in Termux; use the Termux-specific |
| 65 | Android archive when a release or release candidate publishes one, or build |
| 66 | from source inside Termux. |
| 67 | |
| 68 | The Linux **x64** release assets have been **static (musl) builds** since v0.8.65. |
| 69 | They have no glibc dependency and run on any x86_64 Linux, including Ubuntu |
| 70 | 22.04, Debian stable, RHEL/CentOS, and Alpine/musl. SQLite is bundled into the |
| 71 | binary through `rusqlite`, so no separate `libsqlite3` runtime package is needed. |
| 72 | |
| 73 | The Linux **arm64** release assets are still GNU libc (glibc) builds. They |
| 74 | dynamically link normal Linux runtime libraries such as `libdbus-1` and `libc`. |
| 75 | The v0.9.4 candidate build runs on Ubuntu 24.04, so it can require `GLIBC_2.39`. |
| 76 | |
| 77 | ### Linux glibc floor (arm64) |
| 78 | |
| 79 | This floor applies only to the **GNU libc** arm64 asset. The static x64 (musl) |
| 80 | asset has no `GLIBC_*` symbols, so it passes the install preflight and runs on |
| 81 | older systems without error. The v0.9.4 candidate GNU arm64 asset is built on |
| 82 | Ubuntu 24.04 and can require `GLIBC_2.39`. Ubuntu 22.04 ships glibc |
| 83 | 2.35, so those arm64 binaries fail with errors such as: |
| 84 | |
| 85 | ```text |
| 86 | version `GLIBC_2.39' not found |
| 87 | ``` |
| 88 | |
| 89 | The npm wrapper, `codewhale update`, and the Unix archive installer preflight |
| 90 | Linux GNU binaries before installing them and point older systems to Cargo/source |
| 91 | builds. If you are on Ubuntu 22.04 arm64, Debian stable, RHEL/CentOS, or another |
| 92 | older GNU base for a non-x64 asset, use: |
| 93 | |
| 94 | ```bash |
| 95 | cargo install codewhale-cli --locked |
| 96 | cargo install codewhale-tui --locked |
| 97 | ``` |
| 98 | |
| 99 | Future release engineering may add static (musl) arm64 assets so the glibc floor |
| 100 | goes away entirely; until then, x64 is static and arm64 users on older distros |
| 101 | should build from source. |
| 102 | |
| 103 | > **Linux ARM64 note (v0.8.7 and earlier).** v0.8.7 and earlier do **not** |
| 104 | > publish a Linux ARM64 prebuilt; users on HarmonyOS thin-and-light, Asahi |
| 105 | > Linux, Raspberry Pi, AWS Graviton, etc. saw `Unsupported architecture: arm64` |
| 106 | > from `npm i -g codewhale`. v0.8.8 publishes both `codewhale-linux-arm64` |
| 107 | > and `codewhale-tui-linux-arm64`, so a plain `npm i -g codewhale` works |
| 108 | > on any glibc-based ARM64 Linux. If you're stuck on v0.8.7, jump to |
| 109 | > [Build from source](#7-build-from-source) — `cargo install` works fine. |
| 110 | > For HarmonyOS PC and OpenHarmony cross-build setup, see |
| 111 | > [HarmonyOS and OpenHarmony](HarmonyOS.md). |
| 112 | |
| 113 | ### Android / Termux arm64 |
| 114 | |
| 115 | Termux runs on Android's Bionic libc and uses `$PREFIX` as its Unix prefix, so |
| 116 | it needs a Termux-specific Android arm64 archive. The Linux arm64 release asset |
| 117 | is a GNU libc build for normal Linux distributions and should not be used on |
| 118 | Android. |
| 119 | |
| 120 | Install the minimum archive/runtime tools first: |
| 121 | |
| 122 | ```bash |
| 123 | pkg update |
| 124 | pkg install -y ca-certificates curl tar gzip coreutils |
| 125 | ``` |
| 126 | |
| 127 | When the release includes `codewhale-android-arm64.tar.gz`, install it with the |
| 128 | archive's bundled installer. Passing `PREFIX="$PREFIX"` matters: the installer |
| 129 | defaults to `~/.local`, while Termux users normally expect commands under |
| 130 | `$PREFIX/bin`. |
| 131 | |
| 132 | ```bash |
| 133 | cd "$HOME" |
| 134 | curl -L -O https://github.com/Hmbown/CodeWhale/releases/latest/download/codewhale-android-arm64.tar.gz |
| 135 | curl -L -O https://github.com/Hmbown/CodeWhale/releases/latest/download/codewhale-bundles-sha256.txt |
| 136 | sha256sum -c codewhale-bundles-sha256.txt --ignore-missing |
| 137 | |
| 138 | tar xzf codewhale-android-arm64.tar.gz |
| 139 | cd codewhale-android-arm64 |
| 140 | PREFIX="$PREFIX" ./install.sh |
| 141 | hash -r |
| 142 | ``` |
| 143 | |
| 144 | If you are validating from source or building a release candidate locally, |
| 145 | install the build packages before running Cargo: |
| 146 | |
| 147 | ```bash |
| 148 | pkg install -y rust clang pkg-config make git |
| 149 | cargo install codewhale-cli --locked |
| 150 | cargo install codewhale-tui --locked |
| 151 | ``` |
| 152 | |
| 153 | The normal first-run setup path is implemented, but its Android interaction is |
| 154 | still part of the preview QA above. Prefer provider environment variables for |
| 155 | temporary credentials. `codewhale auth set` is available, but the Termux build |
| 156 | has no supported OS keyring integration and falls back to file-backed secrets |
| 157 | by writing `~/.codewhale/config.toml` and mirroring keys to |
| 158 | `~/.codewhale/secrets/secrets.json`. Both are plaintext files protected by |
| 159 | `0600` permissions and are not encrypted at rest. |
| 160 | |
| 161 | ```bash |
| 162 | codewhale auth set --provider deepseek |
| 163 | codewhale auth status |
| 164 | codewhale doctor |
| 165 | ``` |
| 166 | |
| 167 | Maintainers should use this repeatable smoke checklist for a Termux / Android |
| 168 | arm64 release candidate: |
| 169 | |
| 170 | ```bash |
| 171 | command -v codewhale codew codewhale-tui |
| 172 | test -x "$PREFIX/bin/codewhale" |
| 173 | test -x "$PREFIX/bin/codew" |
| 174 | test -x "$PREFIX/bin/codewhale-tui" |
| 175 | |
| 176 | codewhale --version |
| 177 | codewhale doctor |
| 178 | codewhale exec --auto "run pwd" |
| 179 | codewhale-tui --version |
| 180 | ``` |
| 181 | |
| 182 | Known limitations: |
| 183 | |
| 184 | - Commands inherit Android's per-app UID, SELinux, and seccomp protections and |
| 185 | any permissions granted to Termux. Codewhale's opt-in bubblewrap |
| 186 | child-process sandbox is Linux-only and is not built on Android, so approved |
| 187 | commands receive no Codewhale-specific filesystem narrowing. |
| 188 | - The Termux build has no supported Android Keystore or desktop Secret Service |
| 189 | integration. Use `codewhale auth status` to confirm the active source and |
| 190 | prefer provider environment variables when file-backed plaintext storage is |
| 191 | not acceptable. |
| 192 | - Terminal rendering varies by Android terminal app. The TUI always owns the |
| 193 | alternate screen. If a terminal app cannot render the full-screen TUI, |
| 194 | use `codewhale exec` for headless runs instead. |
| 195 | |
| 196 | --- |
| 197 | |
| 198 | ## 2. Download safety and checksums |
| 199 | |
| 200 | Official release binaries are published only from |
| 201 | `https://github.com/Hmbown/CodeWhale/releases` and the npm package named |
| 202 | `codewhale`. Do not install release assets from look-alike repositories, |
| 203 | archives, or search-result mirrors unless you deliberately trust that mirror. |
| 204 | |
| 205 | Every GitHub release includes checksum manifests. Use |
| 206 | `codewhale-artifacts-sha256.txt` for bare binaries and |
| 207 | `codewhale-bundles-sha256.txt` for `.tar.gz` / `.zip` platform archives. If you |
| 208 | download binaries manually, verify them before running: |
| 209 | |
| 210 | ```bash |
| 211 | # Run from the directory containing the downloaded binaries. |
| 212 | curl -L -O https://github.com/Hmbown/CodeWhale/releases/latest/download/codewhale-artifacts-sha256.txt |
| 213 | sha256sum -c codewhale-artifacts-sha256.txt --ignore-missing |
| 214 | ``` |
| 215 | |
| 216 | On macOS, use |
| 217 | `shasum -a 256 -c codewhale-artifacts-sha256.txt --ignore-missing` instead of |
| 218 | `sha256sum`. |
| 219 | |
| 220 | If antivirus software flags an official release binary, treat it as unresolved |
| 221 | until the exact artifact is identified. Please include all of the following in |
| 222 | the GitHub issue: |
| 223 | |
| 224 | - the release tag, for example `v0.8.36` |
| 225 | - the exact download URL |
| 226 | - the filename, for example `codewhale-linux-x64` |
| 227 | - the file SHA-256 from your machine |
| 228 | - the antivirus product name and detection name |
| 229 | |
| 230 | That lets maintainers distinguish a false positive on an official artifact from |
| 231 | a download sourced from an impersonating repository or mirror. |
| 232 | |
| 233 | --- |
| 234 | |
| 235 | ## 3. Install via npm |
| 236 | |
| 237 | npm is the recommended install path (Node 18+; wrapper available for v0.8.56 |
| 238 | and later). It installs the registry's latest published version, not an |
| 239 | unpublished source candidate. |
| 240 | |
| 241 | ```bash |
| 242 | npm install -g codewhale |
| 243 | codewhale --version # prints the published version that was installed |
| 244 | ``` |
| 245 | |
| 246 | `postinstall` downloads the matching three binaries from the GitHub |
| 247 | release, verifies a SHA-256 manifest, and exposes `codewhale`, `codew`, and |
| 248 | `codewhale-tui` on your `PATH`. |
| 249 | |
| 250 | Useful environment variables: |
| 251 | |
| 252 | | Variable | Purpose | |
| 253 | | ----------------------------------- | -------------------------------------------------------------------------------------- | |
| 254 | | `DEEPSEEK_TUI_VERSION` | Pin which release the wrapper downloads (defaults to `codewhaleBinaryVersion`) | |
| 255 | | `DEEPSEEK_VERSION` | Fallback alias, checked after `DEEPSEEK_TUI_VERSION` | |
| 256 | | `DEEPSEEK_TUI_GITHUB_REPO` | Point the downloader at a fork (`owner/repo`) | |
| 257 | | `DEEPSEEK_TUI_RELEASE_BASE_URL` | Override the download root (e.g. an internal mirror or release-asset proxy) | |
| 258 | | `DEEPSEEK_TUI_FORCE_DOWNLOAD=1` | Re-download even if a cached binary marker matches | |
| 259 | | `DEEPSEEK_TUI_DISABLE_INSTALL=1` | Skip the `postinstall` download entirely (CI smoke, vendored binaries) | |
| 260 | | `DEEPSEEK_TUI_OPTIONAL_INSTALL=1` | Don't fail `npm install` on download/extract errors — useful in CI matrices | |
| 261 | |
| 262 | These keep the `DEEPSEEK_*` spelling because the npm wrapper reads exactly |
| 263 | these names and no others (`npm/codewhale/scripts/install.js:88-90`). There is |
| 264 | no `CODEWHALE_VERSION` — setting it has no effect. (The `CODEWHALE_*` rename |
| 265 | applies to the runtime's own environment variables, not to the installer.) |
| 266 | |
| 267 | > **Slow npm download from mainland China?** If `npm install` itself is slow |
| 268 | > (not just the postinstall binary download), use an npm registry mirror: |
| 269 | > ```bash |
| 270 | > npm config set registry https://registry.npmmirror.com |
| 271 | > npm install -g codewhale |
| 272 | > ``` |
| 273 | > See also [Section 4](#4-install-via-cargo-any-tier-1-rust-target) if you |
| 274 | > prefer Cargo over npm. |
| 275 | |
| 276 | --- |
| 277 | |
| 278 | ## 4. Install via Cargo (any Tier-1 Rust target) |
| 279 | |
| 280 | If GitHub releases are slow, blocked, or you're on an unsupported architecture, |
| 281 | install from crates.io directly. Two Cargo packages are required: |
| 282 | `codewhale-cli` installs the `codewhale` and `codew` commands, while |
| 283 | `codewhale-tui` installs the `codewhale-tui` command used by the dispatcher. |
| 284 | |
| 285 | ```bash |
| 286 | # Requires Rust 1.88+ (https://rustup.rs) |
| 287 | cargo install codewhale-cli --locked # provides `codewhale` and `codew` |
| 288 | cargo install codewhale-tui --locked # provides `codewhale-tui` |
| 289 | codewhale --version |
| 290 | ``` |
| 291 | |
| 292 | > **Linux: install build-time dependencies first.** `cargo install` compiles |
| 293 | > from source, and on Linux the `codewhale-tui` crate links against |
| 294 | > `libdbus-1` (used by the D-Bus secret-service backend for credential |
| 295 | > storage). Install the required system packages before running `cargo install`: |
| 296 | > |
| 297 | > ```bash |
| 298 | > # Debian / Ubuntu |
| 299 | > sudo apt-get install -y build-essential pkg-config libdbus-1-dev |
| 300 | > |
| 301 | > # Fedora / RHEL |
| 302 | > sudo dnf install -y gcc make pkgconf-pkg-config dbus-devel |
| 303 | > ``` |
| 304 | > |
| 305 | > If you use the npm wrapper or download GitHub Release binaries, these |
| 306 | > build-time packages are **not** required — the prebuilt binary only |
| 307 | > needs the runtime library (`libdbus-1`), which is already present on |
| 308 | > most desktop Linux installs. |
| 309 | |
| 310 | ### China / mirror-friendly install |
| 311 | |
| 312 | When installing from mainland China, configure mirrors for both **rustup** |
| 313 | (the Rust toolchain installer) and **Cargo** (the package registry) to avoid |
| 314 | TLS timeouts and download failures. |
| 315 | |
| 316 | **Step 1: Install Rust via a rustup mirror** |
| 317 | |
| 318 | ```bash |
| 319 | # PowerShell |
| 320 | [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12 |
| 321 | (New-Object Net.WebClient).DownloadFile('https://win.rustup.rs/x86_64', 'rustup-init.exe') |
| 322 | |
| 323 | # git-bash / msys2 |
| 324 | export RUSTUP_DIST_SERVER=https://mirrors.tuna.tsinghua.edu.cn/rustup |
| 325 | export RUSTUP_UPDATE_ROOT=https://mirrors.tuna.tsinghua.edu.cn/rustup/rustup |
| 326 | ./rustup-init.exe -y --default-toolchain stable |
| 327 | |
| 328 | # Linux / macOS |
| 329 | export RUSTUP_DIST_SERVER=https://mirrors.tuna.tsinghua.edu.cn/rustup |
| 330 | export RUSTUP_UPDATE_ROOT=https://mirrors.tuna.tsinghua.edu.cn/rustup/rustup |
| 331 | curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --default-toolchain stable |
| 332 | ``` |
| 333 | |
| 334 | If the TUNA mirror is slow from your network, `rsproxy.cn` is another |
| 335 | rustup mirror option for Linux/macOS: |
| 336 | |
| 337 | ```bash |
| 338 | export RUSTUP_DIST_SERVER=https://rsproxy.cn |
| 339 | export RUSTUP_UPDATE_ROOT=https://rsproxy.cn/rustup |
| 340 | curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --default-toolchain stable |
| 341 | ``` |
| 342 | |
| 343 | The `RUSTUP_DIST_SERVER` and `RUSTUP_UPDATE_ROOT` environment variables must |
| 344 | be set **before** running rustup-init; the toolchain download otherwise hits |
| 345 | the same TLS handshake problem as the installer. |
| 346 | |
| 347 | **Step 2: Configure Cargo registry mirror** |
| 348 | |
| 349 | ```toml |
| 350 | # ~/.cargo/config.toml |
| 351 | [source.crates-io] |
| 352 | replace-with = "tuna" |
| 353 | |
| 354 | [source.tuna] |
| 355 | registry = "sparse+https://mirrors.tuna.tsinghua.edu.cn/crates.io-index/" |
| 356 | ``` |
| 357 | |
| 358 | `rsproxy`, Tencent COS, and Aliyun OSS mirrors work the same way; pick whichever |
| 359 | is fastest from your network. |
| 360 | |
| 361 | ## 5. Install via Nix |
| 362 | |
| 363 | **Try it** |
| 364 | |
| 365 | If you already have Nix with flake support, run: |
| 366 | |
| 367 | ```sh |
| 368 | nix run github:Hmbown/CodeWhale |
| 369 | ``` |
| 370 | |
| 371 | Nix builds `codewhale-tui` and then starts the `codewhale` dispatcher. Pass |
| 372 | arguments after `--`, for example: |
| 373 | |
| 374 | ```sh |
| 375 | nix run github:Hmbown/CodeWhale -- --help |
| 376 | ``` |
| 377 | |
| 378 | ### Flake |
| 379 | |
| 380 | Add inputs to `flake.nix`: |
| 381 | |
| 382 | ```nix |
| 383 | { |
| 384 | inputs = { |
| 385 | nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable"; |
| 386 | |
| 387 | codewhale-tui.url = "github:Hmbown/CodeWhale"; |
| 388 | codewhale-tui.inputs.nixpkgs.follows = "nixpkgs"; |
| 389 | }; |
| 390 | } |
| 391 | ``` |
| 392 | |
| 393 | Install into a NixOS module: |
| 394 | |
| 395 | ```nix |
| 396 | { |
| 397 | outputs = { self, nixpkgs, codewhale-tui }: |
| 398 | let |
| 399 | # replace system "x86_64-linux" with your system |
| 400 | system = "x86_64-linux"; |
| 401 | in |
| 402 | { |
| 403 | # change `yourhostname` to your actual hostname |
| 404 | nixosConfigurations.yourhostname = nixpkgs.lib.nixosSystem { |
| 405 | inherit system; |
| 406 | modules = [ |
| 407 | # ... |
| 408 | { |
| 409 | environment.systemPackages = [ codewhale-tui.packages.${system}.default ]; |
| 410 | } |
| 411 | ]; |
| 412 | }; |
| 413 | }; |
| 414 | } |
| 415 | ``` |
| 416 | |
| 417 | --- |
| 418 | |
| 419 | ## Homebrew (legacy tap) |
| 420 | |
| 421 | Homebrew currently ships only the legacy `deepseek-tui` tap, kept for |
| 422 | compatibility while the formula is renamed to `codewhale`. It installs the |
| 423 | same current-release binaries: |
| 424 | |
| 425 | ```bash |
| 426 | brew tap Hmbown/deepseek-tui |
| 427 | brew install deepseek-tui |
| 428 | ``` |
| 429 | |
| 430 | Update with `brew upgrade deepseek-tui`. There is no `codewhale` formula yet; |
| 431 | once the rename lands, this section will switch to it. |
| 432 | |
| 433 | --- |
| 434 | |
| 435 | ## 6. Manual download from GitHub Releases |
| 436 | |
| 437 | Each platform appears on the Releases page in **two forms** (this is intentional — see #3208): |
| 438 | the **bare binaries** (`codewhale-<platform>`, `codew-<platform>`, and |
| 439 | `codewhale-tui-<platform>`, no extension) and a **`.tar.gz` / `.zip` archive** |
| 440 | (`codewhale-<platform>.tar.gz`) that bundles the same commands plus an |
| 441 | `install.sh`. The npm wrapper and the in-app `codewhale update` download the |
| 442 | matched runtime binaries; the archive is the easiest manual install (see §5). |
| 443 | The steps below use the bare binaries directly. |
| 444 | |
| 445 | Grab the matching command set for your platform from the |
| 446 | [Releases page](https://github.com/Hmbown/CodeWhale/releases) and drop them |
| 447 | side by side into a directory on your `PATH` (e.g. `~/.local/bin`): |
| 448 | |
| 449 | ```bash |
| 450 | # Linux ARM64 example |
| 451 | mkdir -p ~/.local/bin |
| 452 | curl -L -o ~/.local/bin/codewhale \ |
| 453 | https://github.com/Hmbown/CodeWhale/releases/latest/download/codewhale-linux-arm64 |
| 454 | curl -L -o ~/.local/bin/codew \ |
| 455 | https://github.com/Hmbown/CodeWhale/releases/latest/download/codew-linux-arm64 |
| 456 | curl -L -o ~/.local/bin/codewhale-tui \ |
| 457 | https://github.com/Hmbown/CodeWhale/releases/latest/download/codewhale-tui-linux-arm64 |
| 458 | chmod +x ~/.local/bin/codewhale ~/.local/bin/codew ~/.local/bin/codewhale-tui |
| 459 | codewhale --version |
| 460 | ``` |
| 461 | |
| 462 | > **macOS Gatekeeper note.** If you downloaded the binaries with a browser, |
| 463 | > macOS may block them with "Apple cannot verify" warnings. Clear the quarantine |
| 464 | > attribute on all three binaries and retry: |
| 465 | > ```bash |
| 466 | > xattr -d com.apple.quarantine ~/.local/bin/codewhale ~/.local/bin/codew ~/.local/bin/codewhale-tui 2>/dev/null || true |
| 467 | > ``` |
| 468 | |
| 469 | Verify integrity against the per-release SHA-256 manifest: |
| 470 | |
| 471 | ```bash |
| 472 | curl -L -o /tmp/codewhale-artifacts-sha256.txt \ |
| 473 | https://github.com/Hmbown/CodeWhale/releases/latest/download/codewhale-artifacts-sha256.txt |
| 474 | ( cd ~/.local/bin && sha256sum -c /tmp/codewhale-artifacts-sha256.txt --ignore-missing ) |
| 475 | ``` |
| 476 | |
| 477 | (Use `shasum -a 256 -c /tmp/codewhale-artifacts-sha256.txt --ignore-missing` |
| 478 | instead of `sha256sum -c` on macOS.) |
| 479 | |
| 480 | ### Roll back to a previous release |
| 481 | |
| 482 | If a new release is bad on your machine, install the last known-good version |
| 483 | explicitly. Replace `X.Y.Z` with the version you want to restore. |
| 484 | |
| 485 | ```bash |
| 486 | # npm wrapper, only for versions that were published to npm |
| 487 | npm install -g codewhale@X.Y.Z |
| 488 | |
| 489 | # Cargo path: two packages provide codewhale + codew + codewhale-tui |
| 490 | cargo install codewhale-cli --version X.Y.Z --locked --force |
| 491 | cargo install codewhale-tui --version X.Y.Z --locked --force |
| 492 | ``` |
| 493 | |
| 494 | For manual installs, download the matched binaries or the platform archive from the |
| 495 | exact release tag and verify the matching checksum manifest from that same tag: |
| 496 | |
| 497 | ```bash |
| 498 | # individual binaries |
| 499 | curl -L -o codewhale-artifacts-sha256.txt \ |
| 500 | https://github.com/Hmbown/CodeWhale/releases/download/vX.Y.Z/codewhale-artifacts-sha256.txt |
| 501 | |
| 502 | # platform archives |
| 503 | curl -L -o codewhale-bundles-sha256.txt \ |
| 504 | https://github.com/Hmbown/CodeWhale/releases/download/vX.Y.Z/codewhale-bundles-sha256.txt |
| 505 | ``` |
| 506 | |
| 507 | Inside a Codewhale workspace, `/restore list [N]` lists side-git file snapshots |
| 508 | and `/restore <N>` restores files from the chosen snapshot. That workspace |
| 509 | rollback does not change your installed binary version and does not rewrite |
| 510 | conversation history. |
| 511 | |
| 512 | ### Windows Scoop |
| 513 | |
| 514 | The `codewhale` package is listed in Scoop's main bucket: |
| 515 | |
| 516 | ```powershell |
| 517 | scoop update |
| 518 | scoop install codewhale |
| 519 | codewhale --version |
| 520 | ``` |
| 521 | |
| 522 | Scoop manifests are maintained outside this repository's release workflow and |
| 523 | can lag GitHub/npm/Cargo releases. Use npm or manual GitHub release downloads |
| 524 | when you need the newest version immediately. |
| 525 | |
| 526 | ### Windows NSIS Installer |
| 527 | |
| 528 | A standalone NSIS-based installer is available starting with v0.8.50 for |
| 529 | Windows users who prefer a traditional double-click setup (no npm, no Scoop, no |
| 530 | Cargo required). |
| 531 | |
| 532 | The NSIS installer currently contains the Windows x64 binaries. Windows ARM64 |
| 533 | users should install through npm running under native ARM64 Node.js or download |
| 534 | `codewhale-windows-arm64.zip` from the same release; both paths then use native |
| 535 | ARM64 binaries. |
| 536 | |
| 537 | **Download** `CodeWhaleSetup.exe` from the |
| 538 | [Releases page](https://github.com/Hmbown/CodeWhale/releases/latest). |
| 539 | |
| 540 | **Install** by double-clicking the setup executable. The installer: |
| 541 | |
| 542 | - Installs `codewhale.exe`, `codew.exe`, and `codewhale-tui.exe` side-by-side into |
| 543 | `%LOCALAPPDATA%\Programs\CodeWhale\bin` |
| 544 | - Adds the install directory to the **current user** `PATH` |
| 545 | - Registers in Windows **Apps & Features** for easy uninstall |
| 546 | |
| 547 | **Silent install** (for IT admins, SCCM, Intune): |
| 548 | |
| 549 | ```powershell |
| 550 | CodeWhaleSetup.exe /S |
| 551 | ``` |
| 552 | |
| 553 | The installer is per-user and does not request elevation. Run silent installs in |
| 554 | the target user's context, or use a deployment tool that can run the installer |
| 555 | for each user profile that needs Codewhale. |
| 556 | |
| 557 | The release-built installer is currently unsigned and may trigger Windows |
| 558 | SmartScreen. Verify the SHA-256 checksum from `codewhale-artifacts-sha256.txt` |
| 559 | before deploying, and sign the installer in your internal deployment pipeline if |
| 560 | your environment requires signed application packages. |
| 561 | |
| 562 | **Build the installer yourself** (requires [NSIS](https://nsis.sourceforge.io)): |
| 563 | |
| 564 | ```powershell |
| 565 | cd scripts\installer |
| 566 | # Place codewhale.exe, codew.exe, and codewhale-tui.exe here, then: |
| 567 | makensis /DVERSION=<version> codewhale.nsi |
| 568 | ``` |
| 569 | |
| 570 | **Manual fallback** — if the installer is blocked by group policy, see the |
| 571 | [CLASSROOM_INSTALL.md](CLASSROOM_INSTALL.md) guide for step-by-step PowerShell |
| 572 | commands. |
| 573 | |
| 574 | > **Deploying to a classroom or lab?** See the full |
| 575 | > [Classroom Install Checklist](CLASSROOM_INSTALL.md) for silent install, |
| 576 | > API key provisioning, imaging notes, and troubleshooting. |
| 577 | |
| 578 | --- |
| 579 | |
| 580 | ## 7. Build from source |
| 581 | |
| 582 | This is the catch-all for platforms we don't ship, including musl non-x64, |
| 583 | LoongArch, FreeBSD, and pre-2024 ARM64 distros. Linux RISC-V currently also |
| 584 | needs upstream `rquickjs-sys` RISC-V bindings or a bindgen-enabled dependency |
| 585 | build before source builds are expected to work. |
| 586 | |
| 587 | ### Prerequisites |
| 588 | |
| 589 | - **Rust** 1.88 or later — install with [rustup](https://rustup.rs). |
| 590 | - **Linux build-time deps** (Debian/Ubuntu/openEuler/Kylin): |
| 591 | ```bash |
| 592 | sudo apt-get install -y build-essential pkg-config libdbus-1-dev |
| 593 | # openEuler / RHEL family: |
| 594 | # sudo dnf install -y gcc make pkgconf-pkg-config dbus-devel |
| 595 | ``` |
| 596 | - A working `cmake` is **not** required. |
| 597 | |
| 598 | ### Build and install |
| 599 | |
| 600 | ```bash |
| 601 | git clone https://github.com/Hmbown/CodeWhale.git |
| 602 | cd CodeWhale |
| 603 | |
| 604 | cargo install --path crates/cli --locked # provides `codewhale` and `codew` |
| 605 | cargo install --path crates/tui --locked # provides `codewhale-tui` |
| 606 | |
| 607 | codewhale --version |
| 608 | ``` |
| 609 | |
| 610 | The commands land in `~/.cargo/bin/` by default; make sure that directory is |
| 611 | on your `PATH`. |
| 612 | |
| 613 | ### Cross-compiling from x64 to ARM64 Linux |
| 614 | |
| 615 | If you want to build an ARM64 Linux binary on an x64 Linux host (e.g. for a |
| 616 | HarmonyOS / openEuler ARM64 thin-and-light), use |
| 617 | [`cross`](https://github.com/cross-rs/cross), which wraps the official Rust |
| 618 | cross-targets in a Docker container: |
| 619 | |
| 620 | ```bash |
| 621 | # Once |
| 622 | rustup target add aarch64-unknown-linux-gnu |
| 623 | cargo install cross --locked |
| 624 | |
| 625 | # Per build |
| 626 | cross build --release --target aarch64-unknown-linux-gnu -p codewhale-cli |
| 627 | cross build --release --target aarch64-unknown-linux-gnu -p codewhale-tui |
| 628 | ``` |
| 629 | |
| 630 | The resulting binaries land in |
| 631 | `target/aarch64-unknown-linux-gnu/release/codewhale` and |
| 632 | `target/aarch64-unknown-linux-gnu/release/codewhale-tui`. Copy the matched pair |
| 633 | to the ARM64 host (e.g. via `scp`) and `chmod +x` them. |
| 634 | |
| 635 | If you don't have Docker available, install the cross-linker directly and let |
| 636 | Cargo do the work: |
| 637 | |
| 638 | ```bash |
| 639 | sudo apt-get install -y gcc-aarch64-linux-gnu |
| 640 | rustup target add aarch64-unknown-linux-gnu |
| 641 | |
| 642 | cat >> ~/.cargo/config.toml <<'EOF' |
| 643 | [target.aarch64-unknown-linux-gnu] |
| 644 | linker = "aarch64-linux-gnu-gcc" |
| 645 | EOF |
| 646 | |
| 647 | cargo build --release --target aarch64-unknown-linux-gnu -p codewhale-cli |
| 648 | cargo build --release --target aarch64-unknown-linux-gnu -p codewhale-tui |
| 649 | ``` |
| 650 | |
| 651 | The same recipe works for `aarch64-unknown-linux-musl` if your distro is |
| 652 | musl-based. |
| 653 | |
| 654 | ### Windows build from source |
| 655 | |
| 656 | Building on Windows requires the **MSVC C toolchain** from |
| 657 | [Visual Studio Build Tools](https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2022) |
| 658 | (the free workload-selectable installer, not the full IDE). |
| 659 | |
| 660 | **Prerequisites (Windows)** |
| 661 | |
| 662 | 1. Install Visual Studio 2022 Build Tools — select the **"Desktop development |
| 663 | with C++"** workload. |
| 664 | 2. Install [Rust](https://rustup.rs) 1.88+ (see the |
| 665 | [China mirror instructions](#china--mirror-friendly-install) above if |
| 666 | downloading from mainland China). |
| 667 | 3. Install [Git for Windows](https://git-scm.com/download/win) (provides `git` |
| 668 | and the `git-bash` terminal). |
| 669 | |
| 670 | **Recommended terminals**: Windows Terminal, `git-bash`, or PowerShell. |
| 671 | `cmd.exe` works but has a small buffer and limited PATH behavior. |
| 672 | |
| 673 | **Setting up the MSVC environment** |
| 674 | |
| 675 | Visual Studio Build Tools install `cl.exe` to a versioned directory but do |
| 676 | **not** add it to `PATH` globally. You must set the environment manually or |
| 677 | use a Developer Command Prompt. The required variables are: |
| 678 | |
| 679 | ```powershell |
| 680 | # Adjust version numbers to match your installation |
| 681 | $msvc = "C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\VC\Tools\MSVC\14.44.35207" |
| 682 | $sdk = "C:\Program Files (x86)\Windows Kits\10" |
| 683 | $sdkv = "10.0.26100.0" |
| 684 | |
| 685 | $env:INCLUDE = "$msvc\include;$msvc\atlmfc\include;$sdk\Include\$sdkv\ucrt;$sdk\Include\$sdkv\um;$sdk\Include\$sdkv\shared" |
| 686 | $env:LIB = "$msvc\lib\x64;$msvc\atlmfc\lib\x64;$sdk\Lib\$sdkv\ucrt\x64;$sdk\Lib\$sdkv\um\x64" |
| 687 | $env:LIBPATH = "$msvc\lib\x64;$msvc\atlmfc\lib\x64" |
| 688 | $env:CC = "$msvc\bin\Hostx64\x64\cl.exe" |
| 689 | $env:CXX = "$msvc\bin\Hostx64\x64\cl.exe" |
| 690 | $env:PATH = "$msvc\bin\Hostx64\x64;$env:PATH" |
| 691 | ``` |
| 692 | |
| 693 | Alternatively, open a **"Developer Command Prompt for VS 2022"** (available |
| 694 | from the Start Menu after installing Build Tools), which runs `vcvars64.bat` |
| 695 | to configure all of the above automatically. Then add `cargo` to `PATH` inside |
| 696 | that session and run `cargo build` from the project root. |
| 697 | |
| 698 | **Cargo registry mirror** — on Windows the mirror config goes to |
| 699 | `%USERPROFILE%\.cargo\config.toml`. See [Step 2 above](#china--mirror-friendly-install). |
| 700 | |
| 701 | **Build** |
| 702 | |
| 703 | ```bash |
| 704 | git clone https://github.com/Hmbown/CodeWhale.git |
| 705 | cd CodeWhale |
| 706 | set CARGO_HTTP_CHECK_REVOKE=false # may be needed behind some Chinese ISPs |
| 707 | cargo build --release |
| 708 | ``` |
| 709 | |
| 710 | The binaries appear in `target\release\codewhale.exe`, |
| 711 | `target\release\codew.exe`, and `target\release\codewhale-tui.exe`. |
| 712 | |
| 713 | > Prefer not to build? Install via npm, Cargo, GitHub Releases, or the CNB |
| 714 | > mirror — see the sections above. |
| 715 | |
| 716 | --- |
| 717 | |
| 718 | ## 8. Troubleshooting |
| 719 | |
| 720 | ### `Unsupported architecture: arm64 on platform linux` |
| 721 | |
| 722 | You're on a release earlier than v0.8.8 that doesn't publish Linux ARM64 |
| 723 | binaries. Either upgrade (`npm i -g codewhale@latest`) or use |
| 724 | `cargo install` per [Section 4](#4-install-via-cargo-any-tier-1-rust-target). |
| 725 | |
| 726 | ### `MISSING_COMPANION_BINARY` at runtime |
| 727 | |
| 728 | The dispatcher (`codewhale`) requires the TUI runtime (`codewhale-tui`) to be on |
| 729 | the same `PATH`. If you installed only one crate via `cargo install`, install |
| 730 | both: |
| 731 | |
| 732 | ```bash |
| 733 | cargo install codewhale-cli --locked |
| 734 | cargo install codewhale-tui --locked |
| 735 | ``` |
| 736 | |
| 737 | ### `codewhale update` reports `no asset found for platform codewhale-linux-aarch64` |
| 738 | |
| 739 | This is [#503](https://github.com/Hmbown/CodeWhale/issues/503) in v0.8.7 — |
| 740 | the self-updater used Rust's `aarch64`/`x86_64` arch names instead of the |
| 741 | release artifact's `arm64`/`x64`. Workaround until v0.8.8: |
| 742 | |
| 743 | ```bash |
| 744 | npm i -g codewhale@latest |
| 745 | # or |
| 746 | cargo install codewhale-cli --locked |
| 747 | ``` |
| 748 | |
| 749 | ### npm download is slow or times out from mainland China |
| 750 | |
| 751 | Set `CODEWHALE_RELEASE_BASE_URL` to a mirrored release-asset directory |
| 752 | (rsproxy, TUNA, Tencent COS, Aliyun OSS), or skip npm entirely and use the |
| 753 | Cargo mirror setup in [Section 4](#4-install-via-cargo-any-tier-1-rust-target). |
| 754 | The legacy `DEEPSEEK_TUI_RELEASE_BASE_URL` name is still accepted. |
| 755 | |
| 756 | ### `codewhale update` is blocked by GitHub from mainland China |
| 757 | |
| 758 | `codewhale update` normally contacts GitHub Releases for metadata and binary |
| 759 | assets. On networks where GitHub is blocked or unreliable, use the CNB source |
| 760 | mirror instead and install both Cargo packages from the release tag. Together, |
| 761 | they provide the `codewhale`, `codew`, and `codewhale-tui` commands: |
| 762 | |
| 763 | To check the latest release without downloading or replacing binaries, run |
| 764 | `codewhale update --check`. |
| 765 | |
| 766 | ```bash |
| 767 | cargo install --git https://cnb.cool/codewhale.net/codewhale --tag vX.Y.Z codewhale-cli --locked --force |
| 768 | cargo install --git https://cnb.cool/codewhale.net/codewhale --tag vX.Y.Z codewhale-tui --locked --force |
| 769 | ``` |
| 770 | |
| 771 | If you operate a binary asset mirror, `codewhale update` can use it directly: |
| 772 | |
| 773 | ```bash |
| 774 | CODEWHALE_RELEASE_BASE_URL=https://your-mirror.example.com/CodeWhale/vX.Y.Z/ \ |
| 775 | DEEPSEEK_TUI_VERSION=X.Y.Z \ |
| 776 | codewhale update |
| 777 | ``` |
| 778 | |
| 779 | The mirror directory must contain `codewhale-artifacts-sha256.txt` and the |
| 780 | platform binaries from the GitHub release. The legacy |
| 781 | `DEEPSEEK_TUI_RELEASE_BASE_URL` mirror variable remains supported as an alias. |
| 782 | |
| 783 | ### Debian/Ubuntu: `feature edition2024 is required` from `cargo install` |
| 784 | |
| 785 | Some Debian/Ubuntu distro packages ship an older Cargo that cannot parse Rust |
| 786 | 2024 crates. For example, Cargo 1.75.0 on Ubuntu 24.04 fails before building |
| 787 | with: |
| 788 | |
| 789 | ```text |
| 790 | feature `edition2024` is required |
| 791 | The package requires the Cargo feature called `edition2024`, but that feature |
| 792 | is not stabilized in this version of Cargo |
| 793 | ``` |
| 794 | |
| 795 | Install current stable Rust through rustup, then rerun the two Cargo package |
| 796 | install commands from [Section 4](#4-install-via-cargo-any-tier-1-rust-target). |
| 797 | Together they provide `codewhale`, `codew`, and `codewhale-tui`. For |
| 798 | mainland China networks, this rsproxy-based sequence has been verified to work: |
| 799 | |
| 800 | ```bash |
| 801 | export RUSTUP_DIST_SERVER=https://rsproxy.cn |
| 802 | export RUSTUP_UPDATE_ROOT=https://rsproxy.cn/rustup |
| 803 | |
| 804 | curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y |
| 805 | source "$HOME/.cargo/env" |
| 806 | rustup default stable |
| 807 | cargo install codewhale-cli --locked |
| 808 | cargo install codewhale-tui --locked |
| 809 | ``` |
| 810 | |
| 811 | Afterward, `which cargo` should point to `~/.cargo/bin/cargo`, not |
| 812 | `/usr/bin/cargo`. |
| 813 | |
| 814 | ### Debian/Ubuntu: `error: linker 'cc' not found` while building |
| 815 | |
| 816 | Install the C toolchain: |
| 817 | |
| 818 | ```bash |
| 819 | sudo apt-get install -y build-essential pkg-config libdbus-1-dev |
| 820 | ``` |
| 821 | |
| 822 | ### WSL2 / Ubuntu: `dbus-1` or `pkg-config` not found while building |
| 823 | |
| 824 | WSL2 uses the same Linux source-build path as Ubuntu. If `cargo install |
| 825 | codewhale-tui --locked` fails while compiling the keyring or D-Bus secret |
| 826 | storage crates, install the Linux build dependencies inside the WSL distro, |
| 827 | then rerun the two Cargo package install commands. Together they install |
| 828 | `codewhale`, `codew`, and `codewhale-tui`: |
| 829 | |
| 830 | ```bash |
| 831 | sudo apt-get update |
| 832 | sudo apt-get install -y build-essential pkg-config libdbus-1-dev |
| 833 | cargo install codewhale-cli --locked |
| 834 | cargo install codewhale-tui --locked |
| 835 | ``` |
| 836 | |
| 837 | The prebuilt npm/GitHub binaries do not need these build-time packages; they |
| 838 | only apply when WSL2 is compiling Codewhale from source. |
| 839 | |
| 840 | ### Wrapper installs but `codewhale` isn't found |
| 841 | |
| 842 | `npm i -g` installs into `$(npm prefix -g)/bin`; make sure that directory is on |
| 843 | your shell's `PATH`. With nvm: `nvm use --lts && hash -r`. |
| 844 | |
| 845 | ### Windows: `TLS handshake eof` or `CRYPT_E_REVOCATION_OFFLINE` from `rustup-init` |
| 846 | |
| 847 | The TLS handshake to `static.rust-lang.org` fails from behind the GFW or |
| 848 | certain Chinese ISPs. Set the rustup mirror environment variables **before** |
| 849 | running the installer: |
| 850 | |
| 851 | ```bash |
| 852 | # git-bash / msys2 |
| 853 | export RUSTUP_DIST_SERVER=https://mirrors.tuna.tsinghua.edu.cn/rustup |
| 854 | export RUSTUP_UPDATE_ROOT=https://mirrors.tuna.tsinghua.edu.cn/rustup/rustup |
| 855 | ./rustup-init.exe -y --default-toolchain stable |
| 856 | ``` |
| 857 | |
| 858 | If you see `CRYPT_E_REVOCATION_OFFLINE` from Cargo after Rust is installed, |
| 859 | also set `CARGO_HTTP_CHECK_REVOKE=false` during `cargo build`. |
| 860 | |
| 861 | ### Windows: MSVC compiler (`cl.exe`) not found during `cargo build` |
| 862 | |
| 863 | Visual Studio Build Tools do not add `cl.exe` to the global `PATH`. Either: |
| 864 | |
| 865 | 1. Open **"Developer Command Prompt for VS 2022"** from the Start Menu, add |
| 866 | `%USERPROFILE%\.cargo\bin` to `PATH` in that window, and run `cargo build` |
| 867 | from there; or |
| 868 | 2. Set the MSVC environment variables manually — see the |
| 869 | [Windows build from source](#windows-build-from-source) section for the |
| 870 | PowerShell snippet. |
| 871 | |
| 872 | Verify the compiler is reachable: `cl.exe /?` should print help text. |
| 873 | |
| 874 | ### Windows: `拒绝访问 (os error 5)` when Cargo executes build scripts |
| 875 | |
| 876 | Third-party antivirus software (Huorong, 360, Kaspersky, etc.) may block |
| 877 | Cargo from executing freshly-compiled build-script binaries |
| 878 | (e.g. `libsqlite3-sys`, `aws-lc-sys`, `instability`). The error is |
| 879 | path-agnostic — moving `target-dir` does not help. |
| 880 | |
| 881 | **Symptoms**: `could not execute process ... build-script-build (never executed)` |
| 882 | |
| 883 | **Workarounds** (pick one): |
| 884 | |
| 885 | 1. **Add the project's `target/` directory to your AV exclusions list.** |
| 886 | 2. **Close the antivirus software temporarily** during `cargo build`. |
| 887 | 3. **Use the GitHub Release installer/archive instead** — the release assets |
| 888 | ship prebuilt binaries and skip the Cargo build entirely |
| 889 | ([Section 6](#6-manual-download-from-github-releases)). |
| 890 | 4. **Use `cargo install codewhale-cli --locked`** from crates.io — this |
| 891 | changes the binary path, which some AV tools treat differently. |
| 892 | |
| 893 | To verify that the build-script binary itself is valid (not corrupted), locate |
| 894 | it under `target/debug/build/<crate>/build-script-build` and run it manually: |
| 895 | |
| 896 | ```bash |
| 897 | target/debug/build/libsqlite3-sys-*/build-script-build |
| 898 | # If this runs but panics with "NotPresent" (no C compiler), the binary is |
| 899 | # fine — the AV is blocking Cargo's process-spawning path specifically. |
| 900 | ``` |
| 901 | |
| 902 | ### npm binary download times out |
| 903 | |
| 904 | If `codewhale` waits several seconds and prints `connect ETIMEDOUT` or |
| 905 | `EAI_AGAIN` while fetching from `github.com`, the npm wrapper installed |
| 906 | successfully but the prebuilt binary download from GitHub Releases is blocked |
| 907 | or unreliable on your network. This download is separate from the npm registry |
| 908 | package download. |
| 909 | |
| 910 | Use one of these paths: |
| 911 | |
| 912 | 1. Set a proxy and retry: |
| 913 | |
| 914 | ```bash |
| 915 | export HTTPS_PROXY=http://your-proxy:port |
| 916 | codewhale |
| 917 | ``` |
| 918 | |
| 919 | 2. Mirror the release assets internally and set `DEEPSEEK_TUI_RELEASE_BASE_URL`: |
| 920 | |
| 921 | ```bash |
| 922 | export DEEPSEEK_TUI_RELEASE_BASE_URL=https://your-mirror.example.com/CodeWhale/ |
| 923 | codewhale |
| 924 | ``` |
| 925 | |
| 926 | The directory must contain `codewhale-artifacts-sha256.txt` and the platform |
| 927 | binaries from the GitHub release. |
| 928 | |
| 929 | 3. Install via Cargo, which builds locally and does not download GitHub release |
| 930 | assets. See [Section 4](#4-install-via-cargo-any-tier-1-rust-target). |
| 931 | |
| 932 | 4. Download all three matching `codewhale`, `codew`, and `codewhale-tui` |
| 933 | binaries from the [Releases page](https://github.com/Hmbown/CodeWhale/releases), |
| 934 | place them in a directory on `PATH`, and make them executable. See |
| 935 | [Section 6](#6-manual-download-from-github-releases). |
| 936 | |
| 937 | --- |
| 938 | |
| 939 | ## 9. Verifying your install |
| 940 | |
| 941 | ```bash |
| 942 | codewhale --version |
| 943 | codewhale doctor # checks API key, provider, runtime, and PATH integrity |
| 944 | codewhale doctor --json |
| 945 | ``` |
| 946 | |
| 947 | `doctor` exits non-zero if it finds a problem and prints structured remediation |
| 948 | hints. Paste the JSON output into a GitHub issue if you need help. |
| 949 |