| 1 | # Installing Codewhale |
| 2 | |
| 3 | > 阅读简体中文版：[zh_hans/INSTALL.md](zh_hans/INSTALL.md) |
| 4 | |
| 5 | This page covers every supported install path and the most common |
| 6 | "it didn't install" failures, including **Linux ARM64** and other less |
| 7 | common platforms. |
| 8 | |
| 9 | If you just want the short version, see the |
| 10 | [main README](../README.md#install) or |
| 11 | [简体中文 README](../README.zh-CN.md#安装). |
| 12 | |
| 13 | This branch describes the **v0.10.0 source candidate**. Install commands that |
| 14 | use `latest` resolve to the latest published package or GitHub Release, which |
| 15 | may trail the source candidate. A candidate is not a published install until |
| 16 | the matching package, tag, checksums, and release assets exist. |
| 17 | |
| 18 | Computer Use is included in the current source and becomes available after |
| 19 | plugin review and enablement. Its CLI server needs **Node.js 20 or newer on |
| 20 | PATH**. npm installations already use Node; the Homebrew formula declares it |
| 21 | as a dependency. Cargo and direct binary users can install it from |
| 22 | [Node.js](https://nodejs.org/) and restart Codewhale. macOS builds include the |
| 23 | native helper, so no separate Computer Use app or compiler is needed. OS |
| 24 | Accessibility and Screen Recording permissions remain under your control. |
| 25 | |
| 26 | ## Recommended: official GitHub Releases |
| 27 | |
| 28 | For a new macOS or Linux install: |
| 29 | |
| 30 | ```bash |
| 31 | curl -fsSL https://codewhale.net/install.sh | sh |
| 32 | ``` |
| 33 | |
| 34 | It downloads the matching `codewhale` and `codew` release binaries, |
| 35 | verifies them against `codewhale-artifacts-sha256.txt`, installs to |
| 36 | `~/.local/bin` by default, and exposes the `codew` convenience command. |
| 37 | It does not use npm or compile with Cargo. The source installer refuses different |
| 38 | existing files, symlink destinations, managed directories, and automatic `sudo`. |
| 39 | Use a writable, empty user directory for a fresh install. |
| 40 | |
| 41 | For Windows, choose the matching installer or portable archive from |
| 42 | [official GitHub Releases](https://github.com/Hmbown/CodeWhale/releases/latest). |
| 43 | |
| 44 | For an existing direct binary install: |
| 45 | |
| 46 | ```bash |
| 47 | codewhale update --check |
| 48 | codewhale update |
| 49 | ``` |
| 50 | |
| 51 | The command prints the executable it will change. GitHub is tried first; Linux |
| 52 | x64 can fall back to the first-party CNB mirror only if GitHub's manifest fails |
| 53 | or cannot cover the platform. Each manifest request has a 10-second timeout |
| 54 | and at most three attempts. Explicit mirror settings remain supported. `CODEWHALE_VERSION` pins the mirror |
| 55 | version; `DEEPSEEK_TUI_VERSION` and `DEEPSEEK_VERSION` remain legacy aliases. The |
| 56 | manifest and binary must come from the same source, and checksum failure never |
| 57 | permits replacement. An explicit version or mirror cannot bypass the version |
| 58 | check: a newer development build is kept, even when it is newer than public |
| 59 | latest. Use a separate directory for deliberate rollback. |
| 60 | |
| 61 | ### Migrating from npm, Cargo, or another installation |
| 62 | |
| 63 | Package managers continue to own their files. `codewhale update` gives migration |
| 64 | instructions for npm, Cargo, Homebrew, and Omarchy instead of overwriting them. |
| 65 | Known system/package directories are also protected. A `CODEWHALE_INSTALL_METHOD=binary` |
| 66 | override cannot bypass a recognized managed path. |
| 67 | |
| 68 | Create a fresh destination when `~/.local/bin` is occupied or a sibling command |
| 69 | has different bytes. This leaves every existing installation in place: |
| 70 | |
| 71 | ```bash |
| 72 | mkdir -p "$HOME/.local" |
| 73 | codewhale_install_dir="$(mktemp -d "$HOME/.local/codewhale-release.XXXXXX")" |
| 74 | curl -fsSL https://codewhale.net/install.sh | CODEWHALE_INSTALL_DIR="$codewhale_install_dir" sh |
| 75 | "$codewhale_install_dir/codewhale" --version |
| 76 | export PATH="$codewhale_install_dir:$PATH" |
| 77 | hash -r |
| 78 | command -v codewhale codew |
| 79 | "$codewhale_install_dir/codewhale" update --check |
| 80 | ``` |
| 81 | |
| 82 | After verifying the version and command paths, keep that directory first in your |
| 83 | shell profile. In PowerShell, use `Get-Command codewhale, codew -All` to inspect |
| 84 | resolution; run the selected executable using its full path. A successful update |
| 85 | only changes its own install directory, so another earlier PATH entry can still |
| 86 | launch an older copy. |
| 87 | |
| 88 | Modern matched `codewhale`, `codew`, and compatibility copies update from the |
| 89 | same verified bytes. Symlinks to the running binary are preserved. A different |
| 90 | or unrelated sibling is named in the error and left untouched; no sibling is |
| 91 | executed merely to guess its owner. Use the fresh-directory migration above |
| 92 | for older installs with separate dispatcher/TUI binaries. |
| 93 | |
| 94 | To retain a secondary package-managed install, use its manager: |
| 95 | |
| 96 | ```bash |
| 97 | npm install -g codewhale@latest |
| 98 | # or |
| 99 | cargo install codewhale-cli --locked --force |
| 100 | ``` |
| 101 | |
| 102 | Homebrew uses `brew upgrade codewhale`; Omarchy uses `omarchy update`. These |
| 103 | commands update their own copies, so verify PATH again afterward. |
| 104 | |
| 105 | --- |
| 106 | |
| 107 | ## 1. Supported platforms |
| 108 | |
| 109 | The [latest stable release](https://github.com/Hmbown/CodeWhale/releases/latest) |
| 110 | publishes Linux x64/arm64, macOS x64/arm64, Windows x64/arm64, and Android arm64 |
| 111 | assets. Artifact presence is distinct from platform qualification. |
| 112 | The table below describes the current source tree's platform and secondary |
| 113 | packaging support; `latest` installation still selects the published release. |
| 114 | Android/Termux is preview pending real-device QA. Linux ARM64 is available from |
| 115 | v0.8.8 onward. Linux RISC-V prebuilts are temporarily paused because the locked |
| 116 | `rquickjs-sys` dependency does not ship `riscv64gc-unknown-linux-gnu` bindings. |
| 117 | |
| 118 | | Platform | Architecture | GitHub release asset | npm install | `cargo install` | |
| 119 | | ------------ | ------------ | ----------------------------------------------------- | :---------: | :-------------: | |
| 120 | | Linux | x64 (x86_64) | `codewhale-linux-x64`, `codew-linux-x64` | ✅ | ✅ | |
| 121 | | Linux | arm64 | `codewhale-linux-arm64`, `codew-linux-arm64` | ✅ | ✅ | |
| 122 | | Android / Termux | arm64 (aarch64) | `codewhale-android-arm64.tar.gz` (published in v0.9.12; device support is preview) | ⚠️⁴ preview | ⚠️⁴ preview | |
| 123 | | Linux | riscv64 | temporarily unsupported until upstream bindings land | ❌¹ | ❌³ | |
| 124 | | macOS | x64 | `codewhale-macos-x64`, `codew-macos-x64` | ✅ | ✅ | |
| 125 | | macOS | arm64 (M-series) | `codewhale-macos-arm64`, `codew-macos-arm64` | ✅ | ✅ | |
| 126 | | Windows | x64 | `codewhale-windows-x64.exe`, `codew-windows-x64.exe` | ✅ | ✅ | |
| 127 | | Windows | arm64 | `codewhale-windows-arm64.exe`, `codew-windows-arm64.exe` | ✅ | ✅ | |
| 128 | | Linux x64 or arm64 on musl (Alpine) | native arch | matching static Linux asset | ✅ (static) | ✅ | |
| 129 | | Other Linux (musl on other arches) | — | build from source | ❌¹ | ✅² | |
| 130 | | FreeBSD 14+ / OpenBSD | x64, arm64 | `cargo install codewhale-cli --locked` (no prebuilt; see § FreeBSD) | ❌ | ✅² | |
| 131 | |
| 132 | ¹ The npm package will exit with a clear error and point you here. |
| 133 | ² Provided your toolchain can compile a recent Rust workspace; see |
| 134 | [Build from source](#7-build-from-source) below. |
| 135 | ³ RISC-V source builds currently need upstream `rquickjs-sys` RISC-V bindings or |
| 136 | a bindgen-enabled dependency build. |
| 137 | ⁴ The current npm wrapper recognizes Android arm64 and resolves |
| 138 | the matching `codewhale` and `codew` Android assets. npm |
| 139 | installation works only for a package version whose GitHub Release publishes |
| 140 | those matching assets. The Android/Termux path remains preview-only until the |
| 141 | real-device compile, startup, approval, file-tool, and update checks tracked |
| 142 | in #4236 and #4242 are complete. |
| 143 | |
| 144 | Android / Termux is not the same target as Linux arm64. Do not install the |
| 145 | Linux `codewhale-linux-arm64` archive in Termux; use the Termux-specific |
| 146 | Android archive when a release or release candidate publishes one, or build |
| 147 | from source inside Termux. |
| 148 | |
| 149 | The current Linux **x64 and arm64** assets are **static musl builds**. |
| 150 | The x64 release path has used musl since v0.8.65; v0.9.6 extends the same build |
| 151 | and static-launch check to arm64. These binaries have no glibc dependency and |
| 152 | run on their matching architecture across Ubuntu, Debian, RHEL/CentOS, and |
| 153 | Alpine/musl. SQLite is bundled through `rusqlite`, so no separate `libsqlite3` |
| 154 | runtime package is needed. |
| 155 | |
| 156 | ### Linux ARM64 portability |
| 157 | |
| 158 | Linux arm64 assets before v0.9.6 were GNU libc builds and could inherit the |
| 159 | Ubuntu 24.04 build host's `GLIBC_2.39` floor. Ubuntu 22.04 ships glibc 2.35, so |
| 160 | those older arm64 binaries can fail with errors such as: |
| 161 | |
| 162 | ```text |
| 163 | version `GLIBC_2.39' not found |
| 164 | ``` |
| 165 | |
| 166 | The npm wrapper, `codewhale update`, and the Unix archive installer retain their |
| 167 | GNU-binary preflight for older releases. The current arm64 build instead uses |
| 168 | `aarch64-unknown-linux-musl`, so it has no `GLIBC_*` floor. If you are installing |
| 169 | an earlier release on an older arm64 distribution, use: |
| 170 | |
| 171 | ```bash |
| 172 | cargo install codewhale-cli --locked # installs `codewhale` |
| 173 | ``` |
| 174 | |
| 175 | > **Linux ARM64 note (v0.8.7 and earlier).** v0.8.7 and earlier do **not** |
| 176 | > publish a Linux ARM64 prebuilt; users on HarmonyOS thin-and-light, Asahi |
| 177 | > Linux, Raspberry Pi, AWS Graviton, etc. saw `Unsupported architecture: arm64` |
| 178 | > from `npm i -g codewhale`. v0.8.8 publishes `codewhale-linux-arm64`, so a plain `npm i -g codewhale` works |
| 179 | > on any glibc-based ARM64 Linux. If you're stuck on v0.8.7, jump to |
| 180 | > [Build from source](#7-build-from-source) — `cargo install` works fine. |
| 181 | > For HarmonyOS PC and OpenHarmony cross-build setup, see |
| 182 | > [HarmonyOS and OpenHarmony](HarmonyOS.md). |
| 183 | |
| 184 | ### Android / Termux arm64 |
| 185 | |
| 186 | Termux runs on Android's Bionic libc and uses `$PREFIX` as its Unix prefix, so |
| 187 | it needs a Termux-specific Android arm64 archive. The Linux arm64 release asset |
| 188 | targets standard Linux with musl; Android uses a distinct Rust target, so the |
| 189 | Linux asset should not be used there. |
| 190 | |
| 191 | Install the minimum archive/runtime tools first: |
| 192 | |
| 193 | ```bash |
| 194 | pkg update |
| 195 | pkg install -y ca-certificates curl tar gzip coreutils |
| 196 | ``` |
| 197 | |
| 198 | When the release includes `codewhale-android-arm64.tar.gz`, install it with the |
| 199 | archive's bundled installer. Passing `PREFIX="$PREFIX"` matters: the installer |
| 200 | defaults to `~/.local`, while Termux users normally expect commands under |
| 201 | `$PREFIX/bin`. |
| 202 | |
| 203 | ```bash |
| 204 | cd "$HOME" |
| 205 | curl -L -O https://github.com/Hmbown/CodeWhale/releases/latest/download/codewhale-android-arm64.tar.gz |
| 206 | curl -L -O https://github.com/Hmbown/CodeWhale/releases/latest/download/codewhale-bundles-sha256.txt |
| 207 | sha256sum -c codewhale-bundles-sha256.txt --ignore-missing |
| 208 | |
| 209 | tar xzf codewhale-android-arm64.tar.gz |
| 210 | cd codewhale-android-arm64 |
| 211 | PREFIX="$PREFIX" ./install.sh |
| 212 | hash -r |
| 213 | ``` |
| 214 | |
| 215 | If you are validating from source or building a release candidate locally, |
| 216 | install the build packages before running Cargo: |
| 217 | |
| 218 | ```bash |
| 219 | pkg install -y rust clang pkg-config make git |
| 220 | cargo install codewhale-cli --locked # installs `codewhale` |
| 221 | ``` |
| 222 | |
| 223 | The normal first-run setup path is implemented, but its Android interaction is |
| 224 | still part of the preview QA above. Prefer provider environment variables for |
| 225 | temporary credentials. `codewhale auth set` is available, but the Termux build |
| 226 | has no supported OS keyring integration and falls back to file-backed secrets |
| 227 | by writing `~/.codewhale/config.toml` and mirroring keys to |
| 228 | `~/.codewhale/secrets/secrets.json`. Both are plaintext files protected by |
| 229 | `0600` permissions and are not encrypted at rest. |
| 230 | |
| 231 | ```bash |
| 232 | codewhale auth set --provider deepseek |
| 233 | codewhale auth status |
| 234 | codewhale doctor |
| 235 | ``` |
| 236 | |
| 237 | Maintainers should use this repeatable smoke checklist for a Termux / Android |
| 238 | arm64 release candidate: |
| 239 | |
| 240 | ```bash |
| 241 | command -v codewhale codew |
| 242 | test -x "$PREFIX/bin/codewhale" |
| 243 | test -x "$PREFIX/bin/codew" |
| 244 | |
| 245 | codewhale --version |
| 246 | codewhale doctor |
| 247 | codewhale exec --auto "run pwd" |
| 248 | ``` |
| 249 | |
| 250 | Known limitations: |
| 251 | |
| 252 | - Commands inherit Android's per-app UID, SELinux, and seccomp protections and |
| 253 | any permissions granted to Termux. Codewhale's opt-in bubblewrap |
| 254 | child-process sandbox is Linux-only and is not built on Android, so approved |
| 255 | commands receive no Codewhale-specific filesystem narrowing. |
| 256 | - The Termux build has no supported Android Keystore or desktop Secret Service |
| 257 | integration. Use `codewhale auth status` to confirm the active source and |
| 258 | prefer provider environment variables when file-backed plaintext storage is |
| 259 | not acceptable. |
| 260 | - Terminal rendering varies by Android terminal app. The TUI always owns the |
| 261 | alternate screen. If a terminal app cannot render the full-screen TUI, |
| 262 | use `codewhale exec` for headless runs instead. |
| 263 | |
| 264 | --- |
| 265 | |
| 266 | ## 2. Download safety and checksums |
| 267 | |
| 268 | Official release binaries are published only from |
| 269 | `https://github.com/Hmbown/CodeWhale/releases` and the npm package named |
| 270 | `codewhale`. Do not install release assets from look-alike repositories, |
| 271 | archives, or search-result mirrors unless you deliberately trust that mirror. |
| 272 | |
| 273 | Every GitHub release includes checksum manifests. Use |
| 274 | `codewhale-artifacts-sha256.txt` for bare binaries and |
| 275 | `codewhale-bundles-sha256.txt` for `.tar.gz` / `.zip` platform archives. If you |
| 276 | download binaries manually, verify them before running: |
| 277 | |
| 278 | ```bash |
| 279 | # Run from the directory containing the downloaded binaries. |
| 280 | curl -L -O https://github.com/Hmbown/CodeWhale/releases/latest/download/codewhale-artifacts-sha256.txt |
| 281 | sha256sum -c codewhale-artifacts-sha256.txt --ignore-missing |
| 282 | ``` |
| 283 | |
| 284 | On macOS, use |
| 285 | `shasum -a 256 -c codewhale-artifacts-sha256.txt --ignore-missing` instead of |
| 286 | `sha256sum`. |
| 287 | |
| 288 | If antivirus software flags an official release binary, treat it as unresolved |
| 289 | until the exact artifact is identified. Please include all of the following in |
| 290 | the GitHub issue: |
| 291 | |
| 292 | - the release tag, for example `v0.8.36` |
| 293 | - the exact download URL |
| 294 | - the filename, for example `codewhale-linux-x64` |
| 295 | - the file SHA-256 from your machine |
| 296 | - the antivirus product name and detection name |
| 297 | |
| 298 | That lets maintainers distinguish a false positive on an official artifact from |
| 299 | a download sourced from an impersonating repository or mirror. |
| 300 | |
| 301 | --- |
| 302 | |
| 303 | ## 3. Install via npm |
| 304 | |
| 305 | npm is a secondary packaging option (Node 18+; wrapper available for v0.8.56 |
| 306 | and later). It installs the registry's latest published version, not an |
| 307 | unpublished source candidate. |
| 308 | |
| 309 | ```bash |
| 310 | npm install -g codewhale |
| 311 | codewhale --version # prints the published version that was installed |
| 312 | ``` |
| 313 | |
| 314 | `postinstall` downloads the matching `codewhale` and `codew` binaries, verifies |
| 315 | them against that source's SHA-256 manifest, and exposes `codewhale` and `codew` |
| 316 | on your `PATH`. |
| 317 | |
| 318 | On **Linux x64** (including OpenHarmony x64) the wrapper does **not** wait for |
| 319 | a slow GitHub binary download or a long failure timeout. Unless you set an |
| 320 | explicit release base URL or `CODEWHALE_USE_CNB_MIRROR=1`, it concurrently |
| 321 | fetches the small `codewhale-artifacts-sha256.txt` manifests from GitHub |
| 322 | Releases and the first-party CNB release for the exact package version, accepts |
| 323 | the first source whose HTTP response and manifest validate for the required |
| 324 | assets, cancels the other probe, and downloads the binaries only from that |
| 325 | locked source. CNB publishes Linux x64 only; other targets keep the GitHub-only |
| 326 | path. The selected source is printed in install progress and written to |
| 327 | `<binary>.source` next to the downloaded file. A checksum or source mismatch |
| 328 | fails closed. |
| 329 | |
| 330 | On Windows, run those commands from **Windows Terminal** rather than `cmd.exe` |
| 331 | so fonts and colors match the supported TUI. The GitHub Release also publishes |
| 332 | `codewhale.bat` next to the bare x64 exe; that launcher prefers `wt.exe` and |
| 333 | falls back to a direct launch when Windows Terminal is absent. |
| 334 | |
| 335 | Useful environment variables: |
| 336 | |
| 337 | | Variable | Purpose | |
| 338 | | ----------------------------------- | -------------------------------------------------------------------------------------- | |
| 339 | | `CODEWHALE_RELEASE_BASE_URL` | Override the download root. Skips the Linux x64 GitHub/CNB race. | |
| 340 | | `CODEWHALE_USE_CNB_MIRROR=1` | Force the CNB first-party mirror on Linux x64 / OpenHarmony x64. Other targets fail. | |
| 341 | | `CODEWHALE_VERSION` | Pin which release the wrapper downloads (defaults to `codewhaleBinaryVersion`). | |
| 342 | | `CODEWHALE_GITHUB_REPO` | Point the downloader at a fork (`owner/repo`). | |
| 343 | | `CODEWHALE_FORCE_DOWNLOAD=1` | Re-download even if a cached binary marker matches. | |
| 344 | | `CODEWHALE_DISABLE_INSTALL=1` | Skip the `postinstall` download entirely (CI smoke, vendored binaries). | |
| 345 | | `CODEWHALE_OPTIONAL_INSTALL=1` | Don't fail `npm install` on retryable download errors — useful in CI matrices. | |
| 346 | | `CODEWHALE_QUIET_INSTALL=1` | Suppress installer progress messages. | |
| 347 | | `CODEWHALE_DOWNLOAD_TIMEOUT_MS` | Override the total download budget in milliseconds. | |
| 348 | | `CODEWHALE_DOWNLOAD_STALL_MS` | Override the no-progress stall budget in milliseconds. | |
| 349 | |
| 350 | The corresponding `DEEPSEEK_TUI_*` and `DEEPSEEK_*` variables remain accepted |
| 351 | as legacy aliases, after the canonical `CODEWHALE_*` names. New automation and |
| 352 | support instructions should use only the Codewhale names. |
| 353 | |
| 354 | > **Slow npm download from mainland China?** If `npm install` itself is slow |
| 355 | > (not just the postinstall binary download), use an npm registry mirror: |
| 356 | > ```bash |
| 357 | > npm config set registry https://registry.npmmirror.com |
| 358 | > npm install -g codewhale |
| 359 | > ``` |
| 360 | > See also [Section 4](#4-install-via-cargo-any-tier-1-rust-target) if you |
| 361 | > prefer Cargo over npm. |
| 362 | |
| 363 | --- |
| 364 | |
| 365 | ## 4. Install via Cargo (any Tier-1 Rust target) |
| 366 | |
| 367 | Cargo is a secondary option for source builds or platforms without a release asset. |
| 368 | |
| 369 | If GitHub releases are slow, blocked, or you're on an unsupported architecture, |
| 370 | install from crates.io directly. One Cargo package is required: |
| 371 | `codewhale-cli` installs the `codewhale` command. npm and prebuilt releases also |
| 372 | expose `codew` as a convenience name for the same compiled runtime; Cargo does |
| 373 | not create that alias, so define a shell alias yourself if you want the shorter |
| 374 | name. |
| 375 | |
| 376 | ```bash |
| 377 | # Requires Rust 1.88+ (https://rustup.rs) |
| 378 | cargo install codewhale-cli --locked # installs `codewhale` |
| 379 | codewhale --version |
| 380 | ``` |
| 381 | |
| 382 | > **Linux: install build-time dependencies first.** `cargo install` compiles |
| 383 | > from source, and on Linux the `codewhale-cli` crate links against |
| 384 | > `libdbus-1` (used by the D-Bus secret-service backend for credential |
| 385 | > storage). Install the required system packages before running `cargo install`: |
| 386 | > |
| 387 | > ```bash |
| 388 | > # Debian / Ubuntu |
| 389 | > sudo apt-get install -y build-essential pkg-config libdbus-1-dev |
| 390 | > |
| 391 | > # Fedora / RHEL |
| 392 | > sudo dnf install -y gcc make pkgconf-pkg-config dbus-devel |
| 393 | > ``` |
| 394 | > |
| 395 | > If you use the npm wrapper or download GitHub Release binaries, these |
| 396 | > build-time packages are **not** required — the prebuilt binary only |
| 397 | > needs the runtime library (`libdbus-1`), which is already present on |
| 398 | > most desktop Linux installs. |
| 399 | |
| 400 | ### China / mirror-friendly install |
| 401 | |
| 402 | When installing from mainland China, configure mirrors for both **rustup** |
| 403 | (the Rust toolchain installer) and **Cargo** (the package registry) to avoid |
| 404 | TLS timeouts and download failures. |
| 405 | |
| 406 | **Step 1: Install Rust via a rustup mirror** |
| 407 | |
| 408 | ```bash |
| 409 | # PowerShell |
| 410 | [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12 |
| 411 | (New-Object Net.WebClient).DownloadFile('https://win.rustup.rs/x86_64', 'rustup-init.exe') |
| 412 | |
| 413 | # git-bash / msys2 |
| 414 | export RUSTUP_DIST_SERVER=https://mirrors.tuna.tsinghua.edu.cn/rustup |
| 415 | export RUSTUP_UPDATE_ROOT=https://mirrors.tuna.tsinghua.edu.cn/rustup/rustup |
| 416 | ./rustup-init.exe -y --default-toolchain stable |
| 417 | |
| 418 | # Linux / macOS |
| 419 | export RUSTUP_DIST_SERVER=https://mirrors.tuna.tsinghua.edu.cn/rustup |
| 420 | export RUSTUP_UPDATE_ROOT=https://mirrors.tuna.tsinghua.edu.cn/rustup/rustup |
| 421 | curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --default-toolchain stable |
| 422 | ``` |
| 423 | |
| 424 | If the TUNA mirror is slow from your network, `rsproxy.cn` is another |
| 425 | rustup mirror option for Linux/macOS: |
| 426 | |
| 427 | ```bash |
| 428 | export RUSTUP_DIST_SERVER=https://rsproxy.cn |
| 429 | export RUSTUP_UPDATE_ROOT=https://rsproxy.cn/rustup |
| 430 | curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --default-toolchain stable |
| 431 | ``` |
| 432 | |
| 433 | The `RUSTUP_DIST_SERVER` and `RUSTUP_UPDATE_ROOT` environment variables must |
| 434 | be set **before** running rustup-init; the toolchain download otherwise hits |
| 435 | the same TLS handshake problem as the installer. |
| 436 | |
| 437 | **Step 2: Configure Cargo registry mirror** |
| 438 | |
| 439 | ```toml |
| 440 | # ~/.cargo/config.toml |
| 441 | [source.crates-io] |
| 442 | replace-with = "tuna" |
| 443 | |
| 444 | [source.tuna] |
| 445 | registry = "sparse+https://mirrors.tuna.tsinghua.edu.cn/crates.io-index/" |
| 446 | ``` |
| 447 | |
| 448 | `rsproxy`, Tencent COS, and Aliyun OSS mirrors work the same way; pick whichever |
| 449 | is fastest from your network. |
| 450 | |
| 451 | ## 5. Install via Nix |
| 452 | |
| 453 | **Try it** |
| 454 | |
| 455 | If you already have Nix with flake support, run: |
| 456 | |
| 457 | ```sh |
| 458 | nix run github:Hmbown/CodeWhale |
| 459 | ``` |
| 460 | |
| 461 | Nix builds `codewhale` (single binary) and then starts the dispatcher. Pass |
| 462 | arguments after `--`, for example: |
| 463 | |
| 464 | ```sh |
| 465 | nix run github:Hmbown/CodeWhale -- --help |
| 466 | ``` |
| 467 | |
| 468 | ### Flake |
| 469 | |
| 470 | Add inputs to `flake.nix`: |
| 471 | |
| 472 | ```nix |
| 473 | { |
| 474 | inputs = { |
| 475 | nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable"; |
| 476 | |
| 477 | codewhale.url = "github:Hmbown/CodeWhale"; |
| 478 | codewhale.inputs.nixpkgs.follows = "nixpkgs"; |
| 479 | }; |
| 480 | } |
| 481 | ``` |
| 482 | |
| 483 | Install into a NixOS module: |
| 484 | |
| 485 | ```nix |
| 486 | { |
| 487 | outputs = { self, nixpkgs, codewhale }: |
| 488 | let |
| 489 | # replace system "x86_64-linux" with your system |
| 490 | system = "x86_64-linux"; |
| 491 | in |
| 492 | { |
| 493 | # change `yourhostname` to your actual hostname |
| 494 | nixosConfigurations.yourhostname = nixpkgs.lib.nixosSystem { |
| 495 | inherit system; |
| 496 | modules = [ |
| 497 | # ... |
| 498 | { |
| 499 | environment.systemPackages = [ codewhale.packages.${system}.default ]; |
| 500 | } |
| 501 | ]; |
| 502 | }; |
| 503 | }; |
| 504 | } |
| 505 | ``` |
| 506 | |
| 507 | --- |
| 508 | |
| 509 | ## Omarchy / AUR |
| 510 | |
| 511 | On Omarchy, install the prebuilt AUR package: |
| 512 | |
| 513 | ```bash |
| 514 | omarchy pkg aur add codewhale-bin |
| 515 | codewhale --version |
| 516 | ``` |
| 517 | |
| 518 | `codewhale-bin` packages the same checksum-pinned Linux release archives as the |
| 519 | other binary install paths and provides both `codewhale` and `codew`. It does |
| 520 | not carry a separate Codewhale version; the existing `codewhale-tui` |
| 521 | compatibility command remains an alias to the same runtime. Package updates |
| 522 | arrive through `omarchy update`; the in-app updater leaves the pacman-owned |
| 523 | binary to Omarchy. |
| 524 | |
| 525 | The AUR update follows the matching Codewhale tag and release assets, so it may |
| 526 | appear after the GitHub release while its generated `PKGBUILD` and `.SRCINFO` |
| 527 | are validated. Release-maintainer instructions live in |
| 528 | [`packaging/aur/README.md`](../packaging/aur/README.md). |
| 529 | |
| 530 | --- |
| 531 | |
| 532 | ## Homebrew |
| 533 | |
| 534 | The formula is `codewhale`. The tap GitHub repo is still |
| 535 | `Hmbown/homebrew-deepseek-tui` until it is renamed; `brew tap Hmbown/deepseek-tui` |
| 536 | keeps working either way. |
| 537 | |
| 538 | ```bash |
| 539 | brew tap Hmbown/deepseek-tui |
| 540 | brew install codewhale |
| 541 | ``` |
| 542 | |
| 543 | Update with `brew upgrade codewhale`. Existing Cellar installs under the |
| 544 | legacy `deepseek-tui` formula name can still run `brew upgrade deepseek-tui` |
| 545 | for one overlap release; new installs should use `codewhale`. |
| 546 | |
| 547 | --- |
| 548 | |
| 549 | ## 6. Manual download from GitHub Releases |
| 550 | |
| 551 | Each platform appears on the Releases page in **two forms** (this is intentional — see #3208): |
| 552 | the **bare binaries** (`codewhale-<platform>` and `codew-<platform>`, no extension) and a **`.tar.gz` / `.zip` archive** |
| 553 | (`codewhale-<platform>.tar.gz`) that bundles the same commands plus an |
| 554 | `install.sh`. The npm wrapper and the in-app `codewhale update` download the |
| 555 | matched runtime binaries; the archive is the easiest manual install (see §6). |
| 556 | For a new macOS/Linux install, prefer the checksum-verifying website installer |
| 557 | above. To install an archive manually, download it into a temporary directory, |
| 558 | verify the archive before extracting or running its installer, then use an empty |
| 559 | user prefix. For example, on Linux ARM64: |
| 560 | |
| 561 | ```bash |
| 562 | codewhale_archive_dir="$(mktemp -d)" |
| 563 | cd "$codewhale_archive_dir" |
| 564 | curl -fsSLO https://github.com/Hmbown/CodeWhale/releases/latest/download/codewhale-linux-arm64.tar.gz |
| 565 | curl -fsSLO https://github.com/Hmbown/CodeWhale/releases/latest/download/codewhale-bundles-sha256.txt |
| 566 | sha256sum -c codewhale-bundles-sha256.txt --ignore-missing |
| 567 | tar -xzf codewhale-linux-arm64.tar.gz |
| 568 | cd codewhale-linux-arm64 |
| 569 | ./install.sh |
| 570 | ``` |
| 571 | |
| 572 | On macOS, choose the matching macOS archive and use |
| 573 | `shasum -a 256 -c codewhale-bundles-sha256.txt --ignore-missing`. |
| 574 | The archive installer defaults to `~/.local/bin`; `PREFIX=/an/empty/user/prefix` |
| 575 | selects `/an/empty/user/prefix/bin`. Existing differing files are left intact; |
| 576 | use the updater or a fresh prefix. The website installer instead accepts |
| 577 | `CODEWHALE_INSTALL_DIR`, which names the command directory directly. |
| 578 | |
| 579 | ### Roll back to a previous release |
| 580 | |
| 581 | If a new release is bad on your machine, install the last known-good version |
| 582 | explicitly in a separate directory, verify it, then choose that directory on |
| 583 | PATH. `codewhale update` and the fresh-install scripts do not overwrite a newer |
| 584 | build with an older release. Replace `X.Y.Z` with the version you want to restore. |
| 585 | The following commands apply only to the secondary package-manager routes: |
| 586 | |
| 587 | ```bash |
| 588 | # npm wrapper, only for versions that were published to npm |
| 589 | npm install -g codewhale@X.Y.Z |
| 590 | |
| 591 | # Cargo path: one package installs codewhale |
| 592 | cargo install codewhale-cli --version X.Y.Z --locked --force |
| 593 | ``` |
| 594 | |
| 595 | For manual installs, download the matched binaries or the platform archive from the |
| 596 | exact release tag and verify the matching checksum manifest from that same tag: |
| 597 | |
| 598 | ```bash |
| 599 | # individual binaries |
| 600 | curl -L -o codewhale-artifacts-sha256.txt \ |
| 601 | https://github.com/Hmbown/CodeWhale/releases/download/vX.Y.Z/codewhale-artifacts-sha256.txt |
| 602 | |
| 603 | # platform archives |
| 604 | curl -L -o codewhale-bundles-sha256.txt \ |
| 605 | https://github.com/Hmbown/CodeWhale/releases/download/vX.Y.Z/codewhale-bundles-sha256.txt |
| 606 | ``` |
| 607 | |
| 608 | Inside a Codewhale workspace, `/restore list [N]` lists side-git file snapshots |
| 609 | and `/restore <N>` restores files from the chosen snapshot. That workspace |
| 610 | rollback does not change your installed binary version and does not rewrite |
| 611 | conversation history. |
| 612 | |
| 613 | ### Windows Scoop |
| 614 | |
| 615 | The `codewhale` package is listed in Scoop's main bucket: |
| 616 | |
| 617 | ```powershell |
| 618 | scoop update |
| 619 | scoop install codewhale |
| 620 | codewhale --version |
| 621 | ``` |
| 622 | |
| 623 | Scoop manifests are maintained outside this repository's release workflow and |
| 624 | can lag GitHub/npm/Cargo releases. Use npm or manual GitHub release downloads |
| 625 | when you need the newest version immediately. |
| 626 | |
| 627 | ### Windows winget (v0.9.5+) |
| 628 | |
| 629 | Codewhale publishes a winget manifest for `Hmbown.CodeWhale` (resolves #1561). |
| 630 | Winget installs only the `codewhale` + `codew` commands. GitHub Releases retain |
| 631 | byte-identical `codewhale-tui-*` filenames only for legacy updater compatibility; |
| 632 | they are not a third installed command. |
| 633 | |
| 634 | ```powershell |
| 635 | winget install Hmbown.CodeWhale |
| 636 | codewhale --version |
| 637 | ``` |
| 638 | |
| 639 | The manifest is at [`packaging/winget/Hmbown.CodeWhale.yaml`](../packaging/winget/Hmbown.CodeWhale.yaml) |
| 640 | (also mirrored at [`.winget/Hmbown.CodeWhale.yaml`](../.winget/Hmbown.CodeWhale.yaml)) and lists both |
| 641 | the NSIS installer (`CodeWhaleSetup.exe`, per-user, adds `%LOCALAPPDATA%\Programs\CodeWhale\bin` to the user PATH) |
| 642 | and the portable ZIP fallback (`codewhale-windows-x64.zip` / `codewhale-windows-arm64.zip`). winget |
| 643 | selects the matching architecture automatically; both install the single binary (`codewhale.exe` + `codew.exe`). |
| 644 | The zips also include `codewhale.bat`. Double-click that launcher (not the raw `.exe`) so the first |
| 645 | window is Windows Terminal when it is installed. |
| 646 | |
| 647 | Update via `winget upgrade Hmbown.CodeWhale` or `codewhale update`. The winget package is |
| 648 | maintained outside this repo's release workflow and can lag GitHub/npm/Cargo releases by one |
| 649 | validation cycle — use npm or the GitHub Release asset when you need the newest version immediately. |
| 650 | If `winget install` reports a hash mismatch, verify `codewhale-artifacts-sha256.txt` for the same |
| 651 | tag and regenerate the manifest via `packaging/winget/generate-winget-manifest.sh` (see |
| 652 | [`packaging/winget/README.md`](../packaging/winget/README.md)) before re-submitting to |
| 653 | [microsoft/winget-pkgs](https://github.com/microsoft/winget-pkgs). |
| 654 | |
| 655 | > **Windows ARM64 note.** The NSIS installer currently contains only the x64 binaries. |
| 656 | > Windows ARM64 users should install via `winget install Hmbown.CodeWhale` (ARM64 ZIP) or |
| 657 | > `npm install -g codewhale` under native ARM64 Node.js, or download |
| 658 | > `codewhale-windows-arm64.zip` directly — all paths install native ARM64 binaries. |
| 659 | |
| 660 | ### Windows NSIS Installer |
| 661 | |
| 662 | A standalone NSIS-based installer is available starting with v0.8.50 for |
| 663 | Windows users who prefer a traditional double-click setup (no npm, no Scoop, no |
| 664 | Cargo required). |
| 665 | |
| 666 | The NSIS installer currently contains the Windows x64 binaries. Windows ARM64 |
| 667 | users should install through npm running under native ARM64 Node.js or download |
| 668 | `codewhale-windows-arm64.zip` from the same release; both paths then use native |
| 669 | ARM64 binaries. |
| 670 | |
| 671 | **Download** `CodeWhaleSetup.exe` from the |
| 672 | [Releases page](https://github.com/Hmbown/CodeWhale/releases/latest). |
| 673 | |
| 674 | **Install** by double-clicking the setup executable. The installer: |
| 675 | |
| 676 | - Installs `codewhale.exe` and `codew.exe` side-by-side (single binary, no `codewhale-tui.exe`) into |
| 677 | `%LOCALAPPDATA%\Programs\CodeWhale\bin` |
| 678 | - Installs `codewhale.bat`, which prefers Windows Terminal (`wt.exe`) when it is on `PATH` and |
| 679 | otherwise launches the exe directly |
| 680 | - Creates a current-user Start Menu shortcut that opens that launcher, not the raw `.exe` |
| 681 | - Adds the install directory to the **current user** `PATH` |
| 682 | - Registers in Windows **Apps & Features** for easy uninstall |
| 683 | |
| 684 | Uninstall removes the binaries, `codewhale.bat`, the Start Menu shortcut, and the user `PATH` entry. |
| 685 | |
| 686 | **Silent install** (for IT admins, SCCM, Intune): |
| 687 | |
| 688 | ```powershell |
| 689 | CodeWhaleSetup.exe /S |
| 690 | ``` |
| 691 | |
| 692 | The installer is per-user and does not request elevation. Run silent installs in |
| 693 | the target user's context, or use a deployment tool that can run the installer |
| 694 | for each user profile that needs Codewhale. |
| 695 | |
| 696 | The release-built installer is currently unsigned and may trigger Windows |
| 697 | SmartScreen. Verify the SHA-256 checksum from `codewhale-artifacts-sha256.txt` |
| 698 | before deploying, and sign the installer in your internal deployment pipeline if |
| 699 | your environment requires signed application packages. |
| 700 | |
| 701 | **Build the installer yourself** (requires [NSIS](https://nsis.sourceforge.io)): |
| 702 | |
| 703 | ```powershell |
| 704 | cd scripts\installer |
| 705 | # Place codewhale.exe and codew.exe here (single binary, no codewhale-tui.exe), then: |
| 706 | makensis /DVERSION=<version> codewhale.nsi |
| 707 | ``` |
| 708 | |
| 709 | **Manual fallback** — if the installer is blocked by group policy, see the |
| 710 | [CLASSROOM_INSTALL.md](CLASSROOM_INSTALL.md) guide for step-by-step PowerShell |
| 711 | commands. |
| 712 | |
| 713 | > **Deploying to a classroom or lab?** See the full |
| 714 | > [Classroom Install Checklist](CLASSROOM_INSTALL.md) for silent install, |
| 715 | > API key provisioning, imaging notes, and troubleshooting. |
| 716 | |
| 717 | --- |
| 718 | |
| 719 | ## 7. Build from source |
| 720 | |
| 721 | This is the catch-all for platforms we don't ship, including musl non-x64, |
| 722 | LoongArch, FreeBSD, and pre-2024 ARM64 distros. Linux RISC-V currently also |
| 723 | needs upstream `rquickjs-sys` RISC-V bindings or a bindgen-enabled dependency |
| 724 | build before source builds are expected to work. |
| 725 | |
| 726 | ### Prerequisites |
| 727 | |
| 728 | - **Rust** 1.88 or later — install with [rustup](https://rustup.rs). |
| 729 | - **Linux build-time deps** (Debian/Ubuntu/openEuler/Kylin): |
| 730 | ```bash |
| 731 | sudo apt-get install -y build-essential pkg-config libdbus-1-dev |
| 732 | # openEuler / RHEL family: |
| 733 | # sudo dnf install -y gcc make pkgconf-pkg-config dbus-devel |
| 734 | ``` |
| 735 | - A working `cmake` is **not** required. |
| 736 | |
| 737 | ### Build and install |
| 738 | |
| 739 | ```bash |
| 740 | git clone https://github.com/Hmbown/CodeWhale.git |
| 741 | cd CodeWhale |
| 742 | |
| 743 | cargo install --path crates/cli --locked # installs `codewhale` |
| 744 | |
| 745 | codewhale --version |
| 746 | ``` |
| 747 | |
| 748 | The command lands in `~/.cargo/bin/` by default; make sure that directory is |
| 749 | on your `PATH`. |
| 750 | |
| 751 | ### FreeBSD 14+ source-build workaround (#1097) |
| 752 | |
| 753 | FreeBSD has no prebuilt GitHub Release asset — `npm install -g codewhale` intentionally |
| 754 | fails with `Unsupported platform: freebsd` and points to Cargo. Install from source: |
| 755 | |
| 756 | ```bash |
| 757 | pkg install -y rust pkgconf git |
| 758 | cargo install codewhale-cli --locked # installs `codewhale` |
| 759 | codewhale --version |
| 760 | codewhale doctor |
| 761 | ``` |
| 762 | |
| 763 | The `rquickjs` FreeBSD bindings are generated at build time via `bindgen` (see |
| 764 | `1582ba965`/`5eb0385e8`). No separate `pkg install codewhale` port exists yet — |
| 765 | a native port is tracked as the follow-up to #1097 under `packaging/freebsd/` |
| 766 | (contributions welcome). Validate with `cargo check --target x86_64-unknown-freebsd -p codewhale-cli --locked` |
| 767 | on the release branch; the 7×1 release matrix (Linux musl x64/arm64, |
| 768 | Android arm64, macOS x64/arm64, Windows x64/arm64) stays 7 targets — FreeBSD is a |
| 769 | source-build target, not a prebuilt asset. |
| 770 | |
| 771 | ### Cross-compiling from x64 to ARM64 Linux |
| 772 | |
| 773 | The release asset uses `aarch64-unknown-linux-musl` and is built on a native ARM |
| 774 | runner. If you want to build a GNU-linked ARM64 Linux binary on an x64 Linux |
| 775 | host (e.g. for a HarmonyOS / openEuler ARM64 thin-and-light), use |
| 776 | [`cross`](https://github.com/cross-rs/cross), which wraps the official Rust |
| 777 | cross-targets in a Docker container: |
| 778 | |
| 779 | ```bash |
| 780 | # Once |
| 781 | rustup target add aarch64-unknown-linux-gnu |
| 782 | cargo install cross --locked |
| 783 | |
| 784 | # Per build |
| 785 | cross build --release --target aarch64-unknown-linux-gnu -p codewhale-cli # single binary |
| 786 | ``` |
| 787 | |
| 788 | The resulting binary lands in |
| 789 | `target/aarch64-unknown-linux-gnu/release/codewhale`. Copy it to the ARM64 host |
| 790 | (e.g. via `scp`) and make it executable. This local GNU build is distinct from |
| 791 | the portable musl release asset; either executable can be copied under the |
| 792 | `codew` convenience name. |
| 793 | |
| 794 | If you don't have Docker available, install the cross-linker directly and let |
| 795 | Cargo do the work: |
| 796 | |
| 797 | ```bash |
| 798 | sudo apt-get install -y gcc-aarch64-linux-gnu |
| 799 | rustup target add aarch64-unknown-linux-gnu |
| 800 | |
| 801 | cat >> ~/.cargo/config.toml <<'EOF' |
| 802 | [target.aarch64-unknown-linux-gnu] |
| 803 | linker = "aarch64-linux-gnu-gcc" |
| 804 | EOF |
| 805 | |
| 806 | cargo build --release --target aarch64-unknown-linux-gnu -p codewhale-cli # single binary |
| 807 | ``` |
| 808 | |
| 809 | Producing `aarch64-unknown-linux-musl` while cross-compiling requires an |
| 810 | appropriate musl cross-linker. The release workflow avoids that extra moving |
| 811 | part by building and launching the musl binary on GitHub's native ARM runner. |
| 812 | |
| 813 | ### Windows build from source |
| 814 | |
| 815 | Building on Windows requires the **MSVC C toolchain** from |
| 816 | [Visual Studio Build Tools](https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2022) |
| 817 | (the free workload-selectable installer, not the full IDE). |
| 818 | |
| 819 | **Prerequisites (Windows)** |
| 820 | |
| 821 | 1. Install Visual Studio 2022 Build Tools — select the **"Desktop development |
| 822 | with C++"** workload. |
| 823 | 2. Install [Rust](https://rustup.rs) 1.88+ (see the |
| 824 | [China mirror instructions](#china--mirror-friendly-install) above if |
| 825 | downloading from mainland China). |
| 826 | 3. Install [Git for Windows](https://git-scm.com/download/win) (provides `git` |
| 827 | and the `git-bash` terminal). |
| 828 | |
| 829 | **Recommended terminals**: Windows Terminal, `git-bash`, or PowerShell. |
| 830 | `cmd.exe` works but has a small buffer and limited PATH behavior. |
| 831 | |
| 832 | **Setting up the MSVC environment** |
| 833 | |
| 834 | Visual Studio Build Tools install `cl.exe` to a versioned directory but do |
| 835 | **not** add it to `PATH` globally. You must set the environment manually or |
| 836 | use a Developer Command Prompt. The required variables are: |
| 837 | |
| 838 | ```powershell |
| 839 | # Adjust version numbers to match your installation |
| 840 | $msvc = "C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\VC\Tools\MSVC\14.44.35207" |
| 841 | $sdk = "C:\Program Files (x86)\Windows Kits\10" |
| 842 | $sdkv = "10.0.26100.0" |
| 843 | |
| 844 | $env:INCLUDE = "$msvc\include;$msvc\atlmfc\include;$sdk\Include\$sdkv\ucrt;$sdk\Include\$sdkv\um;$sdk\Include\$sdkv\shared" |
| 845 | $env:LIB = "$msvc\lib\x64;$msvc\atlmfc\lib\x64;$sdk\Lib\$sdkv\ucrt\x64;$sdk\Lib\$sdkv\um\x64" |
| 846 | $env:LIBPATH = "$msvc\lib\x64;$msvc\atlmfc\lib\x64" |
| 847 | $env:CC = "$msvc\bin\Hostx64\x64\cl.exe" |
| 848 | $env:CXX = "$msvc\bin\Hostx64\x64\cl.exe" |
| 849 | $env:PATH = "$msvc\bin\Hostx64\x64;$env:PATH" |
| 850 | ``` |
| 851 | |
| 852 | Alternatively, open a **"Developer Command Prompt for VS 2022"** (available |
| 853 | from the Start Menu after installing Build Tools), which runs `vcvars64.bat` |
| 854 | to configure all of the above automatically. Then add `cargo` to `PATH` inside |
| 855 | that session and run `cargo build` from the project root. |
| 856 | |
| 857 | **Cargo registry mirror** — on Windows the mirror config goes to |
| 858 | `%USERPROFILE%\.cargo\config.toml`. See [Step 2 above](#china--mirror-friendly-install). |
| 859 | |
| 860 | **Build** |
| 861 | |
| 862 | ```bash |
| 863 | git clone https://github.com/Hmbown/CodeWhale.git |
| 864 | cd CodeWhale |
| 865 | set CARGO_HTTP_CHECK_REVOKE=false # may be needed behind some Chinese ISPs |
| 866 | cargo build --release |
| 867 | ``` |
| 868 | |
| 869 | The Cargo-built binary appears at `target\release\codewhale.exe`. Release |
| 870 | packaging separately exposes the same executable as `codew.exe`. |
| 871 | |
| 872 | > Prefer not to build? Install via npm, Cargo, GitHub Releases, or the CNB |
| 873 | > mirror — see the sections above. |
| 874 | |
| 875 | --- |
| 876 | |
| 877 | ## 8. Shell completions |
| 878 | |
| 879 | Codewhale generates its own completion scripts. One command per shell; each |
| 880 | script completes **both** `codewhale` and the `codew` shorthand. |
| 881 | |
| 882 | ```bash |
| 883 | codewhale completion <bash|zsh|fish|powershell|elvish> |
| 884 | ``` |
| 885 | |
| 886 | `codewhale completions` is an accepted alias for the same command. |
| 887 | |
| 888 | The script is written to stdout, so installing it is a redirect to wherever |
| 889 | your shell loads completions from. |
| 890 | |
| 891 | **Bash** — needs the `bash-completion` package loaded by your shell: |
| 892 | |
| 893 | ```bash |
| 894 | mkdir -p ~/.local/share/bash-completion/completions |
| 895 | codewhale completion bash > ~/.local/share/bash-completion/completions/codewhale |
| 896 | ``` |
| 897 | |
| 898 | For the current shell only: `source <(codewhale completion bash)`. |
| 899 | |
| 900 | **Zsh** — the script's `#compdef` line already covers both command names: |
| 901 | |
| 902 | ```bash |
| 903 | mkdir -p ~/.zfunc |
| 904 | codewhale completion zsh > ~/.zfunc/_codewhale |
| 905 | ``` |
| 906 | |
| 907 | If `~/.zfunc` is not already on `fpath`, add this to `~/.zshrc`: |
| 908 | |
| 909 | ```zsh |
| 910 | fpath=(~/.zfunc $fpath) |
| 911 | autoload -Uz compinit && compinit |
| 912 | ``` |
| 913 | |
| 914 | **Fish**: |
| 915 | |
| 916 | ```fish |
| 917 | mkdir -p ~/.config/fish/completions |
| 918 | codewhale completion fish > ~/.config/fish/completions/codewhale.fish |
| 919 | ``` |
| 920 | |
| 921 | **PowerShell** — append to your profile so it loads in every session: |
| 922 | |
| 923 | ```powershell |
| 924 | New-Item -ItemType Directory -Force -Path (Split-Path -Parent $PROFILE) |
| 925 | codewhale completion powershell >> $PROFILE |
| 926 | ``` |
| 927 | |
| 928 | For the current session only: |
| 929 | |
| 930 | ```powershell |
| 931 | codewhale completion powershell | Out-String | Invoke-Expression |
| 932 | ``` |
| 933 | |
| 934 | **Elvish** — the script registers both command names: |
| 935 | |
| 936 | ```elvish |
| 937 | codewhale completion elvish >> ~/.config/elvish/rc.elv |
| 938 | ``` |
| 939 | |
| 940 | Regenerate the script after upgrading Codewhale — it is a snapshot of the |
| 941 | command surface at the version that produced it, not a live query. |
| 942 | |
| 943 | > Upgrading from v0.9.10 or earlier? Those releases emitted a script that |
| 944 | > registered the internal `codewhale-tui` executable, so nothing completed for |
| 945 | > `codewhale` or `codew` ([#5526](https://github.com/Hmbown/CodeWhale/issues/5526)). |
| 946 | > Delete the old file and regenerate it with the commands above. |
| 947 | |
| 948 | --- |
| 949 | |
| 950 | ## 9. Troubleshooting |
| 951 | |
| 952 | ### `Unsupported architecture: arm64 on platform linux` |
| 953 | |
| 954 | You're on a release earlier than v0.8.8 that doesn't publish Linux ARM64 |
| 955 | binaries. Use the GitHub installer in a fresh directory as described above, or use |
| 956 | `cargo install` per [Section 4](#4-install-via-cargo-any-tier-1-rust-target). |
| 957 | |
| 958 | ### `MISSING_COMPANION_BINARY` after upgrading an older install |
| 959 | |
| 960 | The current single binary runs the TUI in-process and does not require a |
| 961 | companion executable. This error identifies a stale pre-v0.9.5 dispatcher. |
| 962 | Use the fresh-directory GitHub migration above, then verify the selected |
| 963 | `codewhale` and `codew` paths. Do not download another separate runtime. |
| 964 | |
| 965 | ### `codewhale update` reports `no asset found for platform codewhale-linux-aarch64` |
| 966 | |
| 967 | Older updaters used Rust architecture names that did not match the published |
| 968 | asset names. Use the official installer in a fresh directory as described above, |
| 969 | then run the newly installed command by its full path. |
| 970 | |
| 971 | ### npm download is slow or times out from mainland China |
| 972 | |
| 973 | On Linux x64 the npm wrapper already probes GitHub Releases and the CNB |
| 974 | first-party checksum manifests in parallel and downloads binaries only from |
| 975 | the first source that validates. You do not need `CODEWHALE_USE_CNB_MIRROR=1` |
| 976 | for that automatic path. |
| 977 | |
| 978 | If both first-party sources fail, set `CODEWHALE_RELEASE_BASE_URL` to a |
| 979 | mirrored release-asset directory (rsproxy, TUNA, Tencent COS, Aliyun OSS), |
| 980 | or skip npm entirely and use the Cargo mirror setup in |
| 981 | [Section 4](#4-install-via-cargo-any-tier-1-rust-target). The legacy |
| 982 | `DEEPSEEK_TUI_RELEASE_BASE_URL` name is still accepted. `CODEWHALE_USE_CNB_MIRROR=1` |
| 983 | still forces CNB only on Linux x64 / OpenHarmony x64. |
| 984 | |
| 985 | ### `codewhale update` is blocked by GitHub from mainland China |
| 986 | |
| 987 | `codewhale update` prefers GitHub Releases. On supported Linux x64 targets, |
| 988 | a failed GitHub manifest permits the matching CNB manifest and binary fallback. |
| 989 | If GitHub metadata is also unreachable, explicitly select a known published CNB |
| 990 | version (`CODEWHALE_USE_CNB_MIRROR=1 CODEWHALE_VERSION=X.Y.Z codewhale update`) |
| 991 | or a binary mirror below. Existing newer builds are kept. |
| 992 | |
| 993 | Building from the CNB source mirror with Cargo is a secondary option. Cargo |
| 994 | installs its own `codewhale` command: |
| 995 | |
| 996 | To check the latest release without downloading or replacing binaries, run |
| 997 | `codewhale update --check`. |
| 998 | |
| 999 | ```bash |
| 1000 | cargo install --git https://cnb.cool/codewhale.net/codewhale --tag vX.Y.Z codewhale-cli --locked --force # single binary |
| 1001 | ``` |
| 1002 | |
| 1003 | If you operate a binary asset mirror, `codewhale update` can use it directly: |
| 1004 | |
| 1005 | ```bash |
| 1006 | CODEWHALE_RELEASE_BASE_URL=https://your-mirror.example.com/CodeWhale/vX.Y.Z/ \ |
| 1007 | CODEWHALE_VERSION=X.Y.Z \ |
| 1008 | codewhale update |
| 1009 | ``` |
| 1010 | |
| 1011 | The mirror directory must contain `codewhale-artifacts-sha256.txt` and the |
| 1012 | platform binaries from the GitHub release. The legacy |
| 1013 | `DEEPSEEK_TUI_RELEASE_BASE_URL` mirror variable remains supported as an alias. |
| 1014 | |
| 1015 | ### Debian/Ubuntu: `feature edition2024 is required` from `cargo install` |
| 1016 | |
| 1017 | Some Debian/Ubuntu distro packages ship an older Cargo that cannot parse Rust |
| 1018 | 2024 crates. For example, Cargo 1.75.0 on Ubuntu 24.04 fails before building |
| 1019 | with: |
| 1020 | |
| 1021 | ```text |
| 1022 | feature `edition2024` is required |
| 1023 | The package requires the Cargo feature called `edition2024`, but that feature |
| 1024 | is not stabilized in this version of Cargo |
| 1025 | ``` |
| 1026 | |
| 1027 | Install current stable Rust through rustup, then rerun the one Cargo package |
| 1028 | install command from [Section 4](#4-install-via-cargo-any-tier-1-rust-target). |
| 1029 | It installs `codewhale`. For |
| 1030 | mainland China networks, this rsproxy-based sequence has been verified to work: |
| 1031 | |
| 1032 | ```bash |
| 1033 | export RUSTUP_DIST_SERVER=https://rsproxy.cn |
| 1034 | export RUSTUP_UPDATE_ROOT=https://rsproxy.cn/rustup |
| 1035 | |
| 1036 | curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y |
| 1037 | source "$HOME/.cargo/env" |
| 1038 | rustup default stable |
| 1039 | cargo install codewhale-cli --locked # installs `codewhale` |
| 1040 | ``` |
| 1041 | |
| 1042 | Afterward, `which cargo` should point to `~/.cargo/bin/cargo`, not |
| 1043 | `/usr/bin/cargo`. |
| 1044 | |
| 1045 | ### Debian/Ubuntu: `error: linker 'cc' not found` while building |
| 1046 | |
| 1047 | Install the C toolchain: |
| 1048 | |
| 1049 | ```bash |
| 1050 | sudo apt-get install -y build-essential pkg-config libdbus-1-dev |
| 1051 | ``` |
| 1052 | |
| 1053 | ### WSL2 / Ubuntu: `dbus-1` or `pkg-config` not found while building |
| 1054 | |
| 1055 | WSL2 uses the same Linux source-build path as Ubuntu. If `cargo install |
| 1056 | codewhale-cli --locked` fails while compiling the keyring or D-Bus secret |
| 1057 | storage crates, install the Linux build dependencies inside the WSL distro, |
| 1058 | then rerun the one Cargo package install command. It installs `codewhale`: |
| 1059 | |
| 1060 | ```bash |
| 1061 | sudo apt-get update |
| 1062 | sudo apt-get install -y build-essential pkg-config libdbus-1-dev |
| 1063 | cargo install codewhale-cli --locked # installs `codewhale` |
| 1064 | ``` |
| 1065 | |
| 1066 | The prebuilt npm/GitHub binaries do not need these build-time packages; they |
| 1067 | only apply when WSL2 is compiling Codewhale from source. |
| 1068 | |
| 1069 | ### Wrapper installs but `codewhale` isn't found |
| 1070 | |
| 1071 | `npm i -g` installs into `$(npm prefix -g)/bin`; make sure that directory is on |
| 1072 | your shell's `PATH`. With nvm: `nvm use --lts && hash -r`. |
| 1073 | |
| 1074 | ### Windows: `TLS handshake eof` or `CRYPT_E_REVOCATION_OFFLINE` from `rustup-init` |
| 1075 | |
| 1076 | The TLS handshake to `static.rust-lang.org` fails from behind the GFW or |
| 1077 | certain Chinese ISPs. Set the rustup mirror environment variables **before** |
| 1078 | running the installer: |
| 1079 | |
| 1080 | ```bash |
| 1081 | # git-bash / msys2 |
| 1082 | export RUSTUP_DIST_SERVER=https://mirrors.tuna.tsinghua.edu.cn/rustup |
| 1083 | export RUSTUP_UPDATE_ROOT=https://mirrors.tuna.tsinghua.edu.cn/rustup/rustup |
| 1084 | ./rustup-init.exe -y --default-toolchain stable |
| 1085 | ``` |
| 1086 | |
| 1087 | If you see `CRYPT_E_REVOCATION_OFFLINE` from Cargo after Rust is installed, |
| 1088 | also set `CARGO_HTTP_CHECK_REVOKE=false` during `cargo build`. |
| 1089 | |
| 1090 | ### Windows: MSVC compiler (`cl.exe`) not found during `cargo build` |
| 1091 | |
| 1092 | Visual Studio Build Tools do not add `cl.exe` to the global `PATH`. Either: |
| 1093 | |
| 1094 | 1. Open **"Developer Command Prompt for VS 2022"** from the Start Menu, add |
| 1095 | `%USERPROFILE%\.cargo\bin` to `PATH` in that window, and run `cargo build` |
| 1096 | from there; or |
| 1097 | 2. Set the MSVC environment variables manually — see the |
| 1098 | [Windows build from source](#windows-build-from-source) section for the |
| 1099 | PowerShell snippet. |
| 1100 | |
| 1101 | Verify the compiler is reachable: `cl.exe /?` should print help text. |
| 1102 | |
| 1103 | ### Windows: `拒绝访问 (os error 5)` when Cargo executes build scripts |
| 1104 | |
| 1105 | Third-party antivirus software (Huorong, 360, Kaspersky, etc.) may block |
| 1106 | Cargo from executing freshly-compiled build-script binaries |
| 1107 | (e.g. `libsqlite3-sys`, `aws-lc-sys`, `instability`). The error is |
| 1108 | path-agnostic — moving `target-dir` does not help. |
| 1109 | |
| 1110 | **Symptoms**: `could not execute process ... build-script-build (never executed)` |
| 1111 | |
| 1112 | **Workarounds** (pick one): |
| 1113 | |
| 1114 | 1. **Add the project's `target/` directory to your AV exclusions list.** |
| 1115 | 2. **Close the antivirus software temporarily** during `cargo build`. |
| 1116 | 3. **Use the GitHub Release installer/archive instead** — the release assets |
| 1117 | ship prebuilt binaries and skip the Cargo build entirely |
| 1118 | ([Section 6](#6-manual-download-from-github-releases)). |
| 1119 | 4. **Use `cargo install codewhale-cli --locked`** from crates.io — this |
| 1120 | changes the binary path, which some AV tools treat differently. |
| 1121 | |
| 1122 | To verify that the build-script binary itself is valid (not corrupted), locate |
| 1123 | it under `target/debug/build/<crate>/build-script-build` and run it manually: |
| 1124 | |
| 1125 | ```bash |
| 1126 | target/debug/build/libsqlite3-sys-*/build-script-build |
| 1127 | # If this runs but panics with "NotPresent" (no C compiler), the binary is |
| 1128 | # fine — the AV is blocking Cargo's process-spawning path specifically. |
| 1129 | ``` |
| 1130 | |
| 1131 | ### npm binary download times out |
| 1132 | |
| 1133 | If `codewhale` waits several seconds and prints `connect ETIMEDOUT` or |
| 1134 | `EAI_AGAIN` while fetching from `github.com`, the npm wrapper installed |
| 1135 | successfully but the prebuilt binary download is blocked or unreliable on |
| 1136 | your network. This download is separate from the npm registry package |
| 1137 | download. On Linux x64 the wrapper first races the small GitHub and CNB |
| 1138 | checksum manifests and does not wait for a full GitHub binary to time out |
| 1139 | before using a valid CNB manifest. |
| 1140 | |
| 1141 | Use one of these paths: |
| 1142 | |
| 1143 | 1. Set a proxy and retry: |
| 1144 | |
| 1145 | ```bash |
| 1146 | export HTTPS_PROXY=http://your-proxy:port |
| 1147 | codewhale |
| 1148 | ``` |
| 1149 | |
| 1150 | 2. Mirror the release assets internally and set `CODEWHALE_RELEASE_BASE_URL`: |
| 1151 | |
| 1152 | ```bash |
| 1153 | export CODEWHALE_RELEASE_BASE_URL=https://your-mirror.example.com/CodeWhale/ |
| 1154 | codewhale |
| 1155 | ``` |
| 1156 | |
| 1157 | The directory must contain `codewhale-artifacts-sha256.txt` and the platform |
| 1158 | binaries from the GitHub release. |
| 1159 | |
| 1160 | 3. Install via Cargo, which builds locally and does not download GitHub release |
| 1161 | assets. See [Section 4](#4-install-via-cargo-any-tier-1-rust-target). |
| 1162 | |
| 1163 | 4. Download both matching `codewhale` and `codew` |
| 1164 | binaries from the [Releases page](https://github.com/Hmbown/CodeWhale/releases), |
| 1165 | place them in a directory on `PATH`, and make them executable. See |
| 1166 | [Section 6](#6-manual-download-from-github-releases). |
| 1167 | |
| 1168 | --- |
| 1169 | |
| 1170 | ## 10. Verifying your install |
| 1171 | |
| 1172 | ```bash |
| 1173 | codewhale --version |
| 1174 | codewhale doctor # checks API key, provider, runtime, and PATH integrity |
| 1175 | codewhale doctor --json |
| 1176 | ``` |
| 1177 | |
| 1178 | `doctor` exits non-zero if it finds a problem and prints structured remediation |
| 1179 | hints. Paste the JSON output into a GitHub issue if you need help. |
| 1180 |