Updated 2026-10-15
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 compiled `codewhale` and `codew` release binaries. The current application runs the TUI in-process. Cargo installs `codewhale-cli` with a current Rust toolchain; a separate `codewhale-tui` crate is no longer required.
Use one installation method. For Homebrew or another platform-specific path, follow the current upstream install guide rather than an older DeepSeek TUI command.
# Option 1: npm
npm install -g codewhale
# Option 2: Cargo (instead of npm)
cargo install codewhale-cli --locked
codewhale --versionSources
- 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 and executable from one supported 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.
These steps use an official DeepSeek API key. For this site's managed DeepSeek Coding Plan, use the delivered endpoint, key and supported model configuration together; do not point a plan key at api.deepseek.com. A successful direct-API test does not validate a gateway configuration. Review the plan setup before buying for this client.
Saved configuration can override a shell variable, so inspect the active source before rotating credentials. Use `auth status --provider deepseek` for the active key source. Plain `doctor` checks local configuration; `doctor --probe-api` tests the provider connection and can incur API usage charges. A successful offline check does not verify a key.
codewhale auth set --provider deepseek
codewhale auth status --provider deepseek
codewhale doctor --probe-api
# Environment-variable alternative
export DEEPSEEK_API_KEY="sk-..."
codewhale auth status --provider deepseek
codewhale doctor --probe-api
# 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 --provider deepseek
codewhale doctor --jsonSources
- 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, Work, or Operate mode
Plan mode is read-only and is the safest choice for an unfamiliar repository. Work mode is the normal coding workflow with approval gates. Operate also supports parallel or background coordination while retaining the active permission rules.
Select modes with `/mode`. Full Access is a separate permission setting, not a mode: it allows actions without approval prompts. Use it only in trusted repositories for bounded, reversible work, and review the diff and tests.
| Mode | Writes files | Runs commands | Approval |
|---|---|---|---|
| Plan | No | Read-only investigation | Read-only |
| Work | Yes | Yes | Active permission rules |
| Operate | Yes | Yes, including coordination | Active permission rules |
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`: an old dispatcher is still on PATH. Reinstall using one current supported method and verify the active executable; the current single binary needs no separate TUI runtime.
Authentication failure: run `codewhale auth status --provider deepseek`; clear an obsolete saved key or remove a stale `DEEPSEEK_API_KEY`, then open a new shell and run `doctor --probe-api` 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 --provider deepseek
codewhale doctor
codewhale doctor --jsonSources
- CodeWhale install troubleshooting - Primary source for current binaries, legacy dispatcher errors, PATH, checksums, 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 --provider deepseek`. It reports whether the active credential comes from saved configuration, the secret store, or `DEEPSEEK_API_KEY` without printing the secret.
Which mode should I use first?
Use Plan mode to inspect an unfamiliar repository, then Work mode for reviewed edits. Operate adds coordination; Full Access is a separate permission choice for trusted, bounded work.
A reliable DeepSeek TUI installation now has one clear path: install the current CodeWhale package, verify the active executable, 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.