codewhale/README.md

DeepSeek CLI

An unofficial terminal UI and CLI for the DeepSeek platform.

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:

# 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 build --release
# binary is at ./target/release/deepseek

Prebuilt binaries are also available on GitHub Releases.

2. Set your API key

Get a key from platform.deepseek.com, then:

export DEEPSEEK_API_KEY="sk-..."

Alternatively, run deepseek and the onboarding wizard will prompt you to enter and save the key.

3. Run

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

# Bootstrap MCP server config and skills templates
deepseek setup

# Verify your environment
deepseek doctor

Keyboard Shortcuts

Key	Action
Enter	Send message
Alt+Enter / Ctrl+J	Insert newline
Tab	Cycle modes (Plan / Agent / YOLO)
Esc	Cancel request / clear input
Ctrl+C	Cancel request or exit
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

Modes

Press Tab to cycle modes: Plan -> Agent -> YOLO -> Plan.

Mode	Description	Approvals
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

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 execute without TUI approval prompts, so only enable servers you trust.

Configuration

The TUI stores its config at ~/.deepseek/config.toml:

api_key = "sk-..."
default_text_model = "deepseek-reasoner"  # optional
allow_shell = false                       # optional
max_subagents = 3                         # optional (1-20)

Environment Variables

Variable	Purpose
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_MAX_SUBAGENTS.

See config.example.toml and docs/CONFIGURATION.md for the full reference.

Examples

# Interactive chat (default)
deepseek

# One-shot prompt (non-interactive, prints and exits)
deepseek -p "Explain the borrow checker in two sentences"

# 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

Troubleshooting

Problem	Fix
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
• Architecture
• Mode Comparison
• MCP Integration
• Contributing

Development

cargo build
cargo test
cargo clippy
cargo fmt

See CONTRIBUTING.md for detailed guidelines.

License

MIT

---

DeepSeek is a trademark of DeepSeek Inc. This is an unofficial, community-driven project.