# DeepSeek CLI
An unofficial terminal UI and CLI for the [DeepSeek platform](https://platform.deepseek.com).
[](https://github.com/Hmbown/DeepSeek-TUI/actions/workflows/ci.yml)
[](https://crates.io/crates/deepseek-tui)
Chat with DeepSeek models directly from your terminal. The assistant can read and write files, run shell commands, search the web, manage tasks, and coordinate sub-agents — all with configurable approval gating.
**Not affiliated with DeepSeek Inc.**
## Getting Started
### 1. Install
Choose one of:
```bash
# From crates.io (requires Rust 1.85+)
cargo install deepseek-tui --locked
# Or build from source
git clone https://github.com/Hmbown/DeepSeek-TUI.git
cd DeepSeek-TUI
cargo install --path . --locked
# installs `deepseek` to ~/.cargo/bin (ensure it is on your PATH)
```
Prebuilt binaries are also available on [GitHub Releases](https://github.com/Hmbown/DeepSeek-TUI/releases).
### 2. Set your API key
Get a key from [platform.deepseek.com](https://platform.deepseek.com), then:
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-v3.2" # optional
allow_shell = false # optional
max_subagents = 3 # optional (1‑20)
```
Alternatively, run `deepseek` and the onboarding wizard will prompt you to enter and save the key.
### 3. Run
```bash
deepseek
```
On first launch the TUI opens in **Agent** mode. Press **Tab** to switch modes, **F1** or type `/help` to see all commands, and **Esc** to cancel a running request.
### 4. Optional setup
```bash
# Bootstrap MCP server config and skills templates
deepseek setup
# Verify your environment
deepseek doctor
```
## Keyboard Shortcuts
| `Enter` | Send message |
| `Alt+Enter` / `Ctrl+J` | Insert newline |
| `Tab` | Autocomplete slash command (or cycle modes) |
| `Esc` | Cancel request / clear input |
| `Ctrl+C` | Cancel request or exit |
| `Ctrl+K` | Open command palette |
| `Ctrl+R` | Search past sessions |
| `F1` or `Ctrl+/` | Toggle help overlay |
| `PageUp` / `PageDown` | Scroll transcript |
| `Alt+Up` / `Alt+Down` | Scroll transcript (small) |
| `l` (empty input) | Open last message in pager |
| `v` (empty input) | Open selected/latest tool details |
## Modes
Press `Tab` to cycle modes: **Plan -> Agent -> YOLO -> Plan**.
| **Plan** | Design-first prompting; produces a plan before implementing | Manual for writes and shell |
| **Agent** | Multi-step autonomous tool use | Auto-approve file writes, manual for shell |
| **YOLO** | Full auto-approve (use with caution) | All tools auto-approved |
Normal mode is also available (chat-only with manual approval for everything) and can be selected via `Esc` from Agent mode or `/set mode normal`.
Override approval behavior at runtime: `/set approval_mode auto|suggest|never`.
## Tools
The model has access to 25+ tools across these categories:
### File Operations
- `list_dir` / `read_file` / `write_file` / `edit_file` — basic file I/O within the workspace
- `apply_patch` — apply unified diffs with fuzzy matching
- `grep_files` / `file_search` — search files by regex or name
### Shell Execution
- `exec_shell` — run commands with timeout support and background execution
- `exec_shell_wait` / `exec_shell_interact` — wait on or send input to running commands
### Web
- `web.run` — multi-command browser (search / open / click / find / screenshot / image_query) with citation support
- `web_search` — quick DuckDuckGo search when citations are not needed
### Task Management
- `todo_write` — create and track task lists with status
- `update_plan` — structured implementation plans
- `note` — persistent cross-session notes
- `/task add|list|show|cancel` — persistent background task queue with timeline visibility
### Sub-Agents
- `agent_spawn` / `agent_swarm` — launch background agents or dependency-aware swarms
- `agent_result` / `agent_list` / `agent_cancel` — manage running agents
### Structured Data
- `weather` / `finance` / `sports` / `time` / `calculator`
### Interaction
- `request_user_input` — ask the user structured or multiple-choice questions
- `multi_tool_use.parallel` — execute multiple read-only tools in parallel
All file tools respect the `--workspace` boundary unless `/trust` is enabled (YOLO enables trust automatically). MCP tools now use the same approval pipeline as built-in tools; only trusted MCP servers should be configured.
## Configuration
The TUI stores its config at `~/.deepseek/config.toml`:
```toml
api_key = "sk-..."
default_text_model = "deepseek-v3.2" # optional
allow_shell = false # optional
max_subagents = 3 # optional (1-20)
```
Any valid DeepSeek model ID is accepted for `default_text_model` (for example, future IDs such as `deepseek-v4-mini` once available).
### Environment Variables
| `DEEPSEEK_API_KEY` | API key (overrides config file) |
| `DEEPSEEK_BASE_URL` | API endpoint (default: `https://api.deepseek.com`) |
| `DEEPSEEK_PROFILE` | Select a `[profiles.<name>]` section from config |
| `DEEPSEEK_CONFIG_PATH` | Override config file location |
Additional overrides: `DEEPSEEK_MCP_CONFIG`, `DEEPSEEK_SKILLS_DIR`, `DEEPSEEK_NOTES_PATH`, `DEEPSEEK_MEMORY_PATH`, `DEEPSEEK_ALLOW_SHELL`, `DEEPSEEK_APPROVAL_POLICY`, `DEEPSEEK_SANDBOX_MODE`, `DEEPSEEK_MAX_SUBAGENTS`, `DEEPSEEK_ALLOW_INSECURE_HTTP`.
Optional local audit log (off by default): set `DEEPSEEK_TOOL_AUDIT_LOG=/path/to/audit.jsonl` to record tool approval decisions and tool outcomes as JSONL events.
See `config.example.toml` and `docs/CONFIGURATION.md` for the full reference.
## Examples
```bash
# Interactive chat (default)
deepseek
# One-shot prompt (non-interactive, prints and exits)
deepseek -p "Explain the borrow checker in two sentences"
# List models from the configured API endpoint
deepseek models
# Agentic execution with auto-approve
deepseek exec --auto "Fix all clippy warnings in this project"
# Resume latest session
deepseek --continue
# Work on a specific project directory
deepseek --workspace /path/to/project
# Review staged git changes
deepseek review --staged
# List saved sessions
deepseek sessions --limit 50
# Shell completions
deepseek completions zsh > _deepseek
deepseek completions bash > deepseek.bash
deepseek completions fish > deepseek.fish
# Runtime API server (localhost by default)
deepseek serve --http --host 127.0.0.1 --port 7878
# MCP stdio server mode
deepseek serve --mcp
```
## Runtime API (HTTP/SSE)
`deepseek serve --http` starts a local runtime API for external clients.
Default bind: `127.0.0.1:7878`
Core endpoints:
- `GET /health`
- `GET /v1/sessions`
- `POST /v1/stream` (backward-compatible single-turn SSE wrapper)
- `POST /v1/threads`
- `GET /v1/threads`
- `GET /v1/threads/{id}`
- `POST /v1/threads/{id}/resume`
- `POST /v1/threads/{id}/fork`
- `POST /v1/threads/{id}/turns`
- `POST /v1/threads/{id}/turns/{turn_id}/steer`
- `POST /v1/threads/{id}/turns/{turn_id}/interrupt`
- `POST /v1/threads/{id}/compact`
- `GET /v1/threads/{id}/events` (SSE replay/live, optional `since_seq`)
- `GET /v1/tasks`
- `POST /v1/tasks`
- `GET /v1/tasks/{id}`
- `POST /v1/tasks/{id}/cancel`
Runtime semantics:
- explicit durable Thread/Turn/Item lifecycle with IDs and statuses
- multi-turn continuity on the same thread
- one active turn per thread (overlap rejected with `409`)
- interrupt transitions to terminal `interrupted` only after cleanup
- steer support for active turns
- compaction surfaced as first-class lifecycle items (`auto` + `manual`)
- replayable per-thread event timeline for API/TUI clients
Task queue semantics:
- durable task storage under `~/.deepseek/tasks` (override with `DEEPSEEK_TASKS_DIR`)
- restart-safe recovery (in-progress tasks are re-queued on startup)
- bounded worker pool via `deepseek serve --http --workers <1-8>`
- task execution linked to runtime thread/turn timelines
Security caveat:
- this server is local-first and assumes trusted local access
- no built-in auth/TLS/multi-user isolation
- do not expose it directly to untrusted networks without your own auth/proxy controls
## Troubleshooting
| No API key | Set `DEEPSEEK_API_KEY` or run `deepseek` to complete onboarding |
| Config not found | Check `~/.deepseek/config.toml` (or `DEEPSEEK_CONFIG_PATH`) |
| Wrong region | Set `DEEPSEEK_BASE_URL` to `https://api.deepseeki.com` (China) |
| Session issues | Run `deepseek sessions` then `deepseek --resume latest` |
| Skills missing | Run `deepseek setup --skills` (add `--local` for workspace-local) |
| MCP tools missing | Run `deepseek mcp init`, then restart |
| Sandbox errors (macOS) | Run `deepseek doctor` to confirm sandbox availability |
## Documentation
- [Configuration Reference](docs/CONFIGURATION.md)
- [Architecture](docs/ARCHITECTURE.md)
- [Mode Comparison](docs/MODES.md)
- [MCP Integration](docs/MCP.md)
- [Runtime API](docs/RUNTIME_API.md)
- [Operations Runbook](docs/OPERATIONS_RUNBOOK.md)
- [Contributing](CONTRIBUTING.md)
## Development
```bash
cargo build
cargo test
cargo clippy
cargo fmt
```
See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
## License
MIT
---
DeepSeek is a trademark of DeepSeek Inc. This is an unofficial, community-driven project.