# DeepSeek CLI
[](https://github.com/Hmbown/DeepSeek-TUI/actions/workflows/ci.yml)
[](https://crates.io/crates/deepseek-tui)
[](https://www.npmjs.com/package/@hmbown/deepseek-tui)
Unofficial terminal UI (TUI) + CLI for the [DeepSeek platform](https://platform.deepseek.com): chat with DeepSeek models and run an approval-gated tool-using agent.
Not affiliated with DeepSeek Inc.
## Quickstart
1. Get an API key from https://platform.deepseek.com
2. Install and run:
```bash
npm install -g @hmbown/deepseek-tui
export DEEPSEEK_API_KEY="YOUR_DEEPSEEK_API_KEY"
deepseek
```
3. Press `F1` or run `/help` for the in-app command list
4. If anything looks off, run `deepseek doctor`
## Install
### Prebuilt via npm/bun (recommended)
The npm package is a thin wrapper that downloads the platform-appropriate Rust binary from GitHub Releases.
```bash
# installs `deepseek`
npm install -g @hmbown/deepseek-tui
bun install -g @hmbown/deepseek-tui
```
### From crates.io (Rust)
```bash
cargo install deepseek-cli --locked
```
### Build from source
```bash
git clone https://github.com/Hmbown/DeepSeek-TUI.git
cd DeepSeek-TUI
cargo build --release
./target/release/deepseek --help
```
### Direct download
Download a prebuilt binary from https://github.com/Hmbown/DeepSeek-TUI/releases and put it on your `PATH` as `deepseek`.
## Configuration
On first run, the TUI can prompt for your API key and save it to `~/.deepseek/config.toml`. You can also create the file manually:
```toml
# ~/.deepseek/config.toml
api_key = "YOUR_DEEPSEEK_API_KEY" # must be non-empty
default_text_model = "deepseek-chat" # optional
allow_shell = false # optional
max_subagents = 3 # optional (1-5)
```
Useful environment variables:
- `DEEPSEEK_API_KEY` (overrides `api_key`)
- `DEEPSEEK_BASE_URL` (default: `https://api.deepseek.com`; China users may use `https://api.deepseeki.com`)
- `DEEPSEEK_PROFILE` (selects `[profiles.<name>]` from the config; errors if missing)
- `DEEPSEEK_CONFIG_PATH` (override config path)
- `DEEPSEEK_MCP_CONFIG`, `DEEPSEEK_SKILLS_DIR`, `DEEPSEEK_NOTES_PATH`, `DEEPSEEK_MEMORY_PATH`, `DEEPSEEK_ALLOW_SHELL`, `DEEPSEEK_MAX_SUBAGENTS`
See `config.example.toml` and `docs/CONFIGURATION.md` for a full reference.
## Modes
In the TUI, press `Tab` to cycle modes: **Normal → Plan → Agent → YOLO → RLM → Duo → Normal**.
- **Normal**: chat; asks before file writes or shell
- **Plan**: design-first prompting; same approvals as Normal
- **Agent**: multi-step tool use; asks before shell
- **YOLO**: enables shell + trust + auto-approves all tools (dangerous)
- **RLM**: externalized context + REPL helpers; auto-approves tools (best for large files)
- **Duo**: player-coach autocoding with iterative validation (based on g3 paper)
Approval behavior is mode-dependent, but you can also override it at runtime with `/set approval_mode auto|suggest|never`.
## Tools
DeepSeek CLI exposes tools to the model: file read/write/patching, shell execution, web search, sub-agents, and MCP servers.
- **Workspace boundary**: file tools are restricted to `--workspace` unless you enable `/trust` (YOLO enables trust automatically).
- **Approvals**: the TUI requests approval depending on mode and tool category (file writes, shell).
- **Web search**: `web_search` uses DuckDuckGo HTML results and is auto-approved.
- **Skills**: reusable workflows stored as `SKILL.md` directories (default: `~/.deepseek/skills`). Use `/skills` and `/skill <name>`.
- **MCP**: load external tool servers via `~/.deepseek/mcp.json` (supports `servers` and `mcpServers`). MCP tools currently execute without TUI approval prompts, so only enable servers you trust. See `docs/MCP.md`.
## RLM
RLM mode is designed for “too big for context” tasks: large files, whole-doc sweeps, and big pasted blocks.
- Auto-switch triggers: “largest file”, explicit “RLM”, large file requests, and large pastes.
- In **RLM mode**, `/load @path` loads a file into the external context store (outside RLM mode, `/load` loads a saved chat JSON).
- Use `/repl` to enter expression mode (e.g. `search(\"pattern\")`, `lines(1, 80)`).
- Power tools: `rlm_load`, `rlm_exec`, `rlm_status`, `rlm_query`.
`rlm_query` can be expensive: prefer batching and check `/status` if you're doing lots of sub-queries.
## Duo Mode
Duo mode implements the player-coach autocoding paradigm for iterative development with built-in validation:
- **Player**: implements requirements (builder role)
- **Coach**: validates implementation against requirements (critic role)
- Tools: `duo_init`, `duo_player`, `duo_coach`, `duo_advance`, `duo_status`
Workflow: `init → player → coach → advance → (repeat until approved)`
## Examples
```bash
deepseek # Interactive TUI
deepseek -p "Write a haiku" # One-shot prompt (prints and exits)
deepseek exec "Write a haiku" # One-shot prompt via subcommand
deepseek exec --auto "Fix lint errors" # Agentic exec with tool access + auto approvals
deepseek doctor # Diagnose config + API key
deepseek sessions --limit 50 # List sessions (~/.deepseek/sessions)
deepseek --resume latest # Resume most recent session
deepseek --resume <id-prefix> # Resume by ID/prefix
deepseek resume --last # Resume most recent session (subcommand)
deepseek fork --last # Fork most recent session
deepseek --workspace /path/to/project
deepseek --yolo # Start in YOLO mode (dangerous)
deepseek init # Generate a starter AGENTS.md
deepseek login --api-key YOUR_KEY
deepseek logout # Clear saved API key
deepseek review --staged # Review staged git changes
deepseek apply patch.diff # Apply a patch file
deepseek features list # Show feature flags and effective state
deepseek execpolicy check --rules my-policy.rules git status
deepseek mcp list # List MCP servers
deepseek mcp tools # List MCP tools
deepseek sandbox run -- ls -la # Run a command in the sandbox
```
Shell completions:
```bash
deepseek completions zsh > _deepseek
deepseek completions bash > deepseek.bash
deepseek completions fish > deepseek.fish
```
## Troubleshooting
- **No API key**: set `DEEPSEEK_API_KEY` or run `deepseek` and complete onboarding
- **Config not found**: check `~/.deepseek/config.toml` (or `DEEPSEEK_CONFIG_PATH`)
- **Wrong region / base URL**: set `DEEPSEEK_BASE_URL` to `https://api.deepseeki.com` (China)
- **Session issues**: run `deepseek sessions` and try `deepseek --resume latest`
- **MCP tools missing**: validate `~/.deepseek/mcp.json` (or `DEEPSEEK_MCP_CONFIG`) and restart
## Documentation
- `docs/README.md`
- `docs/CONFIGURATION.md`
- `docs/MCP.md`
- `docs/ARCHITECTURE.md`
- `CONTRIBUTING.md`
## Development
```bash
cargo build
cargo test
cargo fmt
cargo clippy
```
## License
MIT
---
DeepSeek is a trademark of DeepSeek Inc. This is an unofficial project.