Updated 2026-07-14
Install DeepSeek TUI with the current CodeWhale command
DeepSeek TUI and CodeWhale are the same terminal coding-agent project. CodeWhale is the current upstream package and command name, so this guide uses it for fresh installations. The workflow here is intentionally operational: install one supported package, configure the DeepSeek API key, verify the binary and config source, start safely inside a repository, and diagnose failures. Use `/deepseek-tui` for the project rename, compatibility status, capabilities, and limitations.
1. Install the current CodeWhale command
For most Node.js users, the npm wrapper is the shortest path. It downloads the matching compiled `codewhale` dispatcher and `codewhale-tui` runtime; the agent itself does not run on Node.js. Cargo is the runtime-free alternative but requires both crates and a current Rust toolchain.
Use one installation method. Homebrew still carries the legacy `deepseek-tui` formula and is better treated as an existing-install compatibility path than the default for a new machine.
# npm: simplest current install
npm install -g codewhale
# Cargo: install the matched dispatcher and TUI runtime
cargo install codewhale-cli --locked
cargo install codewhale-tui --locked
codewhale --versionSources checked
- CodeWhale repository - Current upstream install summary and first-run commands.
- CodeWhale install guide - Platform archives, checksums, Docker, Cargo, npm, Homebrew, Nix, and mirror guidance.
2. Verify the binary and remove conflicting legacy installs
Check every matching command on `PATH` before configuration. A machine upgraded from DeepSeek TUI may still contain `deepseek`, `deepseek-tui`, or an older wrapper ahead of the current CodeWhale binary.
Keep the package, dispatcher, runtime, and config names from one release line. If npm and Cargo both installed CodeWhale, remove the one you do not intend to maintain, reopen the shell, and repeat the version check.
which -a codewhale
which -a deepseek 2>/dev/null || true
codewhale --version
npm -g ls codewhale 2>/dev/null || true
cargo install --list | grep -E "codewhale|deepseek" || true
codewhale doctor3. Configure the DeepSeek API key and endpoint
CodeWhale is an API client. Save a DeepSeek key with the auth command or expose `DEEPSEEK_API_KEY` in the shell that launches the agent. `auth status` reports the active source without printing the key.
Saved configuration can override a shell variable, so inspect the active source before rotating credentials. Run `doctor` immediately after setup; it checks the dispatcher/runtime pair, credential route, and provider connection before the agent edits a project.
codewhale auth set --provider deepseek
codewhale auth status
codewhale doctor
# Environment-variable alternative
export DEEPSEEK_API_KEY="sk-..."
codewhale doctor
# Remove a saved key before rotating it
codewhale auth clear --provider deepseek4. Confirm the active config directory
Fresh CodeWhale configuration belongs in `~/.codewhale/config.toml`. The project still reads legacy `~/.deepseek/config.toml` for migration, which can explain why an old key or endpoint appears after a fresh package install.
Project overrides live under the repository's `.codewhale` directory. Do not copy secret API keys into a project file or commit them to Git. When behavior is unexpected, compare both user-level paths and use `auth status` to confirm the credential source.
ls -la ~/.codewhale 2>/dev/null || true
ls -la ~/.deepseek 2>/dev/null || true
codewhale auth status
codewhale doctor --jsonSources checked
- CodeWhale user guide - First launch, configuration home, doctor checks, Docker, and safe repository use.
5. Start safely inside a project
Change into the repository you want the agent to inspect, run `codewhale`, and begin with a read-only exploration request. This keeps the working scope explicit and makes wrong assumptions visible before any file changes.
Use `codewhale doctor --json` when you need a machine-readable health report for an issue or wrapper. Do not begin with an unrestricted batch task until installation, credentials, and repository scope are confirmed.
cd /path/to/project
codewhale
# Example first request
# Explore this repository, explain its structure, and do not edit files.6. Choose Plan, Agent, or YOLO mode
Plan mode is read-only and is the safest choice for an unfamiliar repository. Agent mode proposes edits and commands for approval and is the normal daily workflow.
YOLO mode automatically approves tool calls. Reserve it for narrow, reversible tasks with a clean working tree and known tests. A fast mode does not remove the need to review the diff.
| Mode | Writes files | Runs commands | Approval |
|---|---|---|---|
| Plan | No | No | Read-only |
| Agent | Yes | Yes | Per action |
| YOLO | Yes | Yes | Automatic |
7. Troubleshoot command, auth, endpoint, and config failures
`codewhale: command not found`: reopen the shell, inspect `PATH`, and confirm that the package manager's binary directory is present.
`MISSING_COMPANION_BINARY`: reinstall with one supported method so the dispatcher and `codewhale-tui` runtime come from the same release.
Authentication failure: run `codewhale auth status`; clear an obsolete saved key or remove a stale `DEEPSEEK_API_KEY`, then open a new shell and run `doctor` again.
Unexpected endpoint or settings: inspect both `~/.codewhale` and legacy `~/.deepseek`. Keep only the configuration you intend to use after migration is verified.
which -a codewhale
codewhale --version
codewhale auth status
codewhale doctor
codewhale doctor --jsonSources checked
- CodeWhale install troubleshooting - Primary source for paired binaries, PATH, checksums, mirrors, and supported install paths.
FAQ
Are DeepSeek TUI and CodeWhale separate projects?
No. CodeWhale is the current upstream name for the same project. This guide uses current CodeWhale commands while `/deepseek-tui` explains the naming and compatibility history.
Should a fresh install use the deepseek command?
No. Start with the current `codewhale` command. Treat `deepseek`, `deepseek-tui`, and `.deepseek` as legacy compatibility names when diagnosing an older installation.
Does CodeWhale run DeepSeek V4 locally?
No. It runs the agent and tools locally but sends model requests to the DeepSeek API. Use `/local-deployment` for local model inference.
How do I see which API key CodeWhale is using?
Run `codewhale auth status`. It reports whether the active credential comes from saved configuration, keyring state, or `DEEPSEEK_API_KEY` without printing the secret.
Which mode should I use first?
Use Plan mode to inspect an unfamiliar repository, then Agent mode for reviewed edits. Use YOLO only for narrow, reversible work after the setup and tests are known.
A reliable DeepSeek TUI installation now has one clear path: install the current CodeWhale package, verify the matched binaries, configure one DeepSeek key source, confirm the active config home, and begin in a controlled work mode. Keep legacy DeepSeek TUI names inside migration and troubleshooting instead of mixing them into a fresh setup.
Related model comparisons
Continue from this guide into structured DeepSeek-first comparison pages with model tables, routing advice, and pricing context.