> deepseek-cli

$ ds chat "explain this diff" --file changes.patch
The patch swaps the retry loop for exponential backoff, and stops
retrying 4xx responses – those would fail identically on a second try.
· flash · 3.2k in (87% cached) · 412 out (180 think) · ~$0.000178 · 2.1s

You do not need an API key to start

Most tools open with "get an API key". This one opens with an answer.

$ deepseek free
The free tier relays your prompts to DeepSeek through a gateway run by
this project. No account, no API key.

  gateway   https://freeseek.1lm.io
  model     deepseek-flash
  per day   30 requests · 60k input · 20k output tokens
  privacy   prompts are relayed, not stored; only token counts are recorded

Minting an anonymous token (20 bits of proof-of-work)…
  solved 20 bits in 0.4s (1.0M hashes)

Enrolled.

$ deepseek chat "why is the sky blue"
Sunlight is scattered by the atmosphere, and shorter wavelengths scatter
far more – Rayleigh scattering.
· flash · 93 in · 46 out (7 think) · ~$0.000026 · 1.56s

About a second of CPU stands in for the signup – a proof-of-work puzzle, which is the whole enrolment. No email, no card, no dashboard. There is a browser playground on the same free tier that shows you the equivalent command for whatever you set up in it.

A real API key always takes precedence, so this is a fallback for not having one rather than a way around having one. The gateway is in the repository and meant to be self-hostable; its design notes include the part most services leave out – why per-user quota is not what keeps it solvent, and what is.

Why this exists

Wrapping six HTTP endpoints is not interesting on its own. Two things are, and they are the reason this is not a shell function around curl.

• Multi-turn that does not 400

  With tools in play, DeepSeek rejects any request that fails to replay every assistant reasoning_content. Without tools it ignores the same field – so sending it just burns input tokens. Sessions get both halves right, and you never think about it.

• Cost you can actually see

  A cached input token is 50× cheaper than an uncached one. That split is invisible unless something reads prompt_cache_hit_tokens and does the arithmetic. This does, on every call, and keeps a local ledger.

• Four formats, one binary

  Send the same prompt through the OpenAI, Anthropic and Responses formats and see what differs. Useful when you are pointing Claude Code or Codex at DeepSeek and something behaves oddly.

• It carries the manual

  Every page of DeepSeek's API docs lives inside the binary, plus the FAQ that is otherwise locked in a JavaScript bundle. ds docs ask answers from them and cites the page – so the answer is checkable against a URL, not whatever a model remembers about an API that changes monthly.

• Built for scripts and agents

  stdout is data, stderr is status, --json is the API's own response body unwrapped. Exit codes separate bad key from no balance from rate limited. The contract.

Quick start

curl -sL https://github.com/thevibeworks/deepseek-cli/raw/main/install.sh | sh

export DEEPSEEK_API_KEY=sk-...
ds check                      # is everything reachable?
ds chat "why is the sky blue"

check calls all six endpoints once and reports which answered. It is the first thing to run when something is wrong and you do not yet know whether the problem is the key, the balance, the network, a proxy in between, or one specific endpoint.

https://api.deepseek.com

ok    GET /models                  141ms  deepseek-flash, deepseek-v4-pro
ok    GET /user/balance            126ms  18.48 CNY
ok    POST /chat/completions       651ms  5 in / 1 out
ok    POST /anthropic/v1/messages  590ms  5 in / 1 out
ok    POST /responses              595ms  5 in / 9 out
ok    POST /beta/completions       379ms  4 in / 1 out

all endpoints reachable

The API, explaining itself

The tool that talks to an API should be able to answer questions about it. This one carries DeepSeek's own documentation – 67 pages, about 85KB compressed – and asks DeepSeek to answer from it.

$ ds docs ask "when must I send reasoning_content back?"
Send reasoning_content back only when the model performed a tool call
during that turn. In that case it must be passed back in all subsequent
turns, or the API returns a 400 error (guides/thinking_mode).
answered from guides/thinking_mode, api/create-chat-completion · docs built in, fetched today
· flash · 5.3k in (39% cached) · 116 out · ~$0.000778 · 2.2s

Pages are selected locally and sent whole, with an instruction to answer only from them. The same pages lead every request, so the second question about an area hits the context cache – which is the cost feature on this site demonstrating itself. Search, read and the change log cost nothing and need no network:

ds docs search "context cache"
ds docs show guides/kv_cache
ds docs changelog              # what DeepSeek shipped, newest first
ds docs sync                   # refresh the snapshot

The commands

One per endpoint, named for what it does rather than for its path. Full reference on the commands page.

What it does not do

Worth knowing before you install it:

• It does not run tool calls. It prints the calls a model wants to make, which is what you need to develop a tool schema. Executing model-chosen commands is an agent runtime and a much larger set of safety questions.
• It is not a coding agent. No file editing, no repo awareness, no loop. It sends a request and shows you the response.
• Costs are estimates. Computed from DeepSeek's published USD rate card, not from your invoice. Token counts are exact, and they are what gets stored, so old calls can be repriced when the card changes.
• Text only. The CLI sends text. Since 2026-09-10 deepseek-flash also takes images through chat completions and Responses, and deepseek-v4-pro does not; the CLI has no flag that sends one.