How to use BlackCat: the complete noob guide
This guide takes you from "I have a computer" to "the agent is running
in my terminal" with nothing assumed. Every step has a time estimate, the
exact commands to type, and what you should see before you move on. Total
for a first run: about 45 minutes, most of it waiting on downloads and
a card payment.
If you only read one line: the finished command is
blackcat --yolo tui
Everything below is how you get there.
See also: README.md (usage reference),
AGENTS.md (agent rules),
docs/DEFINITION_OF_DONE.md (delivery
checklist).
| Step | What | Time |
|---|---|---|
| 1 | Check/install Python 3.11+ | 5 min |
| 2 | Clone the repository | 2 min |
| 3 | Create the .venv environment |
2 min |
| 4 | Editable install, including the TUI extra | 5 min |
| 5 | Verify the install (offline, no key needed) | 1 min |
| 6 | Register a DeepSeek API account | 5 min |
| 7 | Create an API key | 2 min |
| 8 | Top up the balance (from $2, ~$3 real cost) | 10 min |
| 9 | Put the key in .env |
2 min |
| 10 | Live smoke test against the real API | 1 min |
| 11 | Start the app | 1 min |
| 12 | Understand the one-model rule | 2 min |
TL;DR: the whole thing in one block
For people who have done this before and just want the commands. Do not
start here if anything is unfamiliar; the sections below explain each line
and every failure mode.
python3 -m venv .venv
source .venv/bin/activate
pip install -e '.[tui]'
# put DEEPSEEK_API_KEY=sk-... in .env (see step 9)
blackcat --version
blackcat prompt "Reply with exactly: live test ok"
blackcat --yolo tui
Windows PowerShell: .venv\Scripts\activate and pip install -e ".[tui]".
Step 0: What this thing actually is (2 min, read once)
BlackCat is an agent: a chat program that does not just talk, it works.
It reads files, edits them, runs tests and shell commands, searches the web,
fetches pages, and keeps a task list across a long session. It talks to
DeepSeek's API (or OpenRouter, or a free offline echo provider used for
testing).
It ships two faces:
| Face | Command | What it is |
|---|---|---|
| CLI | blackcat chat / blackcat prompt "..." |
Plain terminal chat, logs on stderr, answer on stdout |
| TUI | blackcat tui / blackcat --yolo tui |
Full-screen harness: animated tool cards, diffs, costs, session rail |
Both are the same program, one binary named blackcat, with a subcommand
per face.
File extension note: the guide is written for Linux/macOS. Windows works
too; the only differences are the activate line and the quote style, both
called out where they matter.
Step 1: Check your Python (5 min)
What you need: Python 3.11 or newer, and the venv module that
ships with it. Nothing else: no database, no Node, no Docker.
Check what you have:
python3 -V
You want Python 3.11.x, 3.12.x, 3.13.x, or 3.14.x.
- Already 3.11+? Go to step 2. This took 10 seconds.
- Too old, or
command not found? Install it:- Debian/Ubuntu:
sudo apt update && sudo apt install python3 python3-venv python3-pip - Fedora:
sudo dnf install python3 python3-pip - macOS (Homebrew):
brew install python@3.12 - Windows: install from the official python.org installer and tick
"Add python.exe to PATH" on the first screen. Then usepython
instead ofpython3for the rest of this guide.
- Debian/Ubuntu:
On Debian/Ubuntu the python3-venv package is not optional: without it
python3 -m venv fails with "ensurepip is not available". If you see
that message, install the package and retry.
Checkpoint: python3 -V prints 3.11 or higher.
Step 2: Clone the repository (2 min)
The project lives at https://molodetz.nl/repos/blackcat. That URL is the
repository root: README.md, pyproject.toml, the blackcat/ package and
tests/ all sit directly inside it.
git clone https://molodetz.nl/repos/blackcat
cd blackcat
If git is missing, install it (sudo apt install git /
brew install git / git-scm.com for Windows), or download the archive from
the same URL and unpack it; you just need the folder.
You are in the right place when ls shows README.md, pyproject.toml
and a blackcat directory. Stay in this directory for every following
step; the .venv and .env you are about to create belong here.
Checkpoint: pwd ends in /blackcat, and ls README.md succeeds.
Step 3: Create the environment .venv (2 min)
Never install this into your system Python. Every dependency goes into a
private folder called .venv, inside the repository. The name matters:
the Makefile and every command in this guide expect exactly .venv, at
the repository root.
python3 -m venv .venv
That creates .venv/ with its own private python, pip, and site
packages. It is already listed in .gitignore, so it will never be
committed.
Now activate it. This is the step people forget, and every "command
not found" later traces back to it:
source .venv/bin/activate # Linux / macOS
.venv\Scripts\activate # Windows PowerShell
Your prompt now starts with (.venv). That prefix is your proof the
environment is live.
If source complains the file does not exist, you are in the wrong
directory: cd back to blackcat. If PowerShell refuses with "running
scripts is disabled", run once:
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned.
Checkpoint: your prompt shows (.venv), and which python points
inside .venv/bin/.
Step 4: Editable install, with the TUI extra (5 min)
Two words to understand before typing anything:
- Editable (
-e) means the installed package is a pointer to this
folder, not a copy. You editblackcat/cli.pyand the next run uses
your edit. This is what you want inside a repository. [tui]is an extra: an optional dependency group. The core needs
onlyaiohttpandstealthii; the full-screen harness additionally
needstextual, which lives in thetuiextra. Install it now; adding
it later is a second install and a second round of confusion.
Install with both:
pip install -e '.[tui]'
Windows PowerShell needs double quotes (single quotes are literal there):
pip install -e ".[tui]"
Prefer one command that does step 3 and 4 for you? From the repository
root:
make setup
That creates .venv and runs the same editable install with the TUI and
dev extras. (make help lists every target.)
What you should see: pip resolving aiohttp, stealthii (from its git
URL) and textual, then a final install line naming the same packages:
Successfully installed aiohttp-3.14.5 blackcat-1.0.1 stealthii-0.1.0 textual-8.2.8 ...
(Exact version numbers drift; the names are what matter.)
Expect 1-3 minutes; stealthii pulls a git dependency and Textual has a
few dependencies of its own. If pip cannot reach the git URL, you are
behind a firewall: set HTTPS_PROXY and retry rather than hand-installing
pieces.
Want the test and lint tooling as well? Use pip install -e '.[tui,dev]'.
Not needed to run the app.
Step 5: Verify the install, still offline (1 min)
No API key needed for any of this.
blackcat --version
Expected: blackcat 1.0.1 (or a newer version), the project name and the
version you installed.
Now a real round trip through the agent loop, using the offline echo
provider:
blackcat --provider echo prompt "hi"
Expected tail end of the output:
echo: hi
If instead you get blackcat: command not found, the environment is not
active (step 3) or the install did not happen (step 4). The fix is always:
source .venv/bin/activate && pip install -e '.[tui]'
Optional but useful: confirm the test suite is healthy on your machine:
python -m unittest discover -s tests
About 2 minutes, ~450 tests, no network required. Some TUI tests skip
cleanly if the extra is missing; you installed it, so they should run.
Checkpoint: echo: hi appears. The program works; only the API key is
missing.
Step 6: Register a DeepSeek API account (5 min)
The API and the consumer chat app are different products with different
sign-ups. You want the developer platform, not chat.deepseek.com. You do
not need the chat app at all.
- Open https://platform.deepseek.com in a browser.
- Choose Sign up (or Log in if you already have an account). You can
register with an email address and password, or with a Google account. - If you used email: open the verification mail and click the link. It
normally lands within a minute; check spam if it does not, and do not
request a second one immediately or the first link may be invalidated. - You land on the console: a sidebar with API keys, Top up,
Billing, Usage.
Notes worth knowing now:
- Signing in with Google and signing up with a password can create two
different accounts. Pick one method and stick to it, or your key and
your balance will end up on different accounts, the single most common
"my top-up vanished" cause. - An API key is free to create. Calls are what cost money, and they are
deducted from a prepaid balance you add in step 8. - New accounts sometimes receive a small granted balance. It is spent
before your own money and it can expire. Do not plan around it.
Checkpoint: you can see the console with API keys and Top up in
the sidebar.
Step 7: Create the API key (2 min)
- In the console, click API keys.
- Click Create new API key.
- Give it a name that tells you where it lives later:
blackcat-laptop
is better thankey1. - Copy the key immediately. It looks like
sk-followed by a long random
string, and it is shown only once. If you lose it, delete it and
create a new one; that is normal and costs nothing. - Treat it like a password: anyone with it can spend your balance. Do not
paste it into chat, screenshots, issues, or a commit.
You can create several keys (laptop, server, CI) and revoke each one
independently. That is the right way to rotate a leaked key: delete it,
create a new one, update .env.
Checkpoint: you have an sk-... string on your clipboard.
Step 8: Top up the balance, from $2 and about $3 in practice (10 min)
DeepSeek is prepaid. Calls fail with a 402 Insufficient Balance
until there is money on the account, so this step is not optional.
- In the console, open Top up (sometimes under Billing).
- Enter the amount. The minimum is $2. That is the smallest usable
deposit, and it is genuinely enough to evaluate this agent. - Pick a payment method: bank card (Visa/Mastercard), PayPal,
Alipay, or WeChat Pay. - Submit once, then check Billing for the record and the new balance.
Why you should budget $3, not $2
The amount you type is not the amount that leaves your card. DeepSeek adds
a 6% charge (VAT/handling) on top, and your bank or PayPal may add its
own fee:
| Top-up | Charged to the card |
|---|---|
| $2 | $2.12 |
| $5 | $5.30 |
| $10 | $10.60 |
| $20 | $21.20 |
So: $2 is the deposit, roughly $3 is the money you should have
available. The extra stays as balance; nothing is wasted. It simply
gives the payment room to clear instead of bouncing for being twelve cents
short. Payments that fail usually fail exactly there: the card holds the
amount you typed, but not amount × 1.06.
Other things that save you a support ticket:
- Many banks block cross-border charges to Hong Kong/China merchants by
default. If a card is declined, call it in the banking app before
retrying five times. - Topped-up balance does not expire. Granted (free) balance can.
- Unused balance can be refunded from Billing → Refunds for online
payments, minus handling fees; money already spent is not refundable. - Check the balance any time with
GET /user/balance, or just watch the
console's Usage page.
What $2 buys
deepseek-flash pricing at the time of writing, per 1M tokens:
| Off-peak | Peak | |
|---|---|---|
| Input, cache hit | $0.003 | $0.006 |
| Input, cache miss | $0.15 | $0.30 |
| Output | $0.60 | $1.20 |
Peak hours are 01:00-04:00 and 06:00-10:00 UTC on weekdays; everything
else, including weekends, is off-peak at half price. Web search and page
fetch are $0.75 per 1,000 successful requests. In practical terms $2 is
millions of tokens of ordinary agent work, a comfortable first pot.
Checkpoint: Billing shows a positive balance.
Step 9: Give the key to the app in .env (2 min)
The app reads its key from, in order:
--api-key sk-...on the command line,- the
DEEPSEEK_API_KEYenvironment variable (BLACKCAT_API_KEYalso
works;OPENROUTER_API_KEYfor the OpenRouter provider), - a
.envfile in the current working directory.
Option 3 is the sane default for a repository checkout: it survives
reboots, does not pollute your shell history, and is already git-ignored.
Create it in the repository root:
echo 'DEEPSEEK_API_KEY=sk-your-key-here' > .env
Or open .env in an editor and put this single line in it:
DEEPSEEK_API_KEY=sk-your-key-here
Rules that matter:
- No spaces around
=, no quotes around the value, one variable per line. - The file must be
.envin the directory you run the command from.
BLACKCAT_ENV_FILE=/path/to/other.envoverrides that. - Verify git will ignore it:
git status --shortmust not list.env.
If it does, stop and fix.gitignorebefore committing anything.
Checkpoint: cat .env shows your key and git status does not mention
it.
Step 10: Live smoke test (1 min)
First, one plain call to prove the key, the balance and the network all
agree:
blackcat prompt "Reply with exactly: live test ok"
Expected:
live test ok
Then confirm which model the provider is actually serving:
blackcat models
Expected: a list containing deepseek-flash, the model this
agent drives.
If the answer is 401, the key is wrong or truncated (re-copy it; watch
for a trailing newline). If it is 402, the balance is empty (step 8) or
the top-up went to a different account (step 6).
Checkpoint: the model answers. You are done with setup.
Step 11: Start the app (1 min)
Here it is:
blackcat --yolo tui
The full-screen harness opens: a transcript pane, a session rail showing
touched files and live cost, tabs for Diff/Costs/Report/Models/Help, a
command palette on Ctrl+P, slash commands like /costs, /diff,
/repo, /scholar, and three themes.
What --yolo does, precisely: it skips every tool-approval prompt and
disables the file-tools sandbox, so the agent may write files and run shell
commands without asking, anywhere on disk. That is the right default for
your own machine on a task you started. It is the wrong flag on a
production box. Without it, every mutating tool call renders an approval
card you accept or reject, which is the safer way to learn the app.
Other ways in:
blackcat tui # same, but asks before mutating anything
blackcat tui "fix the failing tests" # one-shot: quits when that turn is done
blackcat --yolo tui "build the whole app" # one-shot, hands-free
blackcat chat # plain terminal chat instead
blackcat --yolo --session app.json chat # resumable session, saves after each prompt
First-session tips:
- Ask for something small and verifiable: "summarise README.md in five
bullets", then "run the test suite and tell me what fails". - Type
/coststo see what the session has spent so far. Ctrl+Ccancels the current turn;Ctrl+Q(or the quit command) exits.- Long jobs: pass
--session work.jsonand you can close the terminal and
resume later with the transcript, summary and todo list intact.
Checkpoint: the TUI is on screen. You are using the agent.
Step 11b: Run it in a container (5 min, optional)
If you would rather not install Python and Textual on the host, or you want
the agent in a box that still writes to your directory:
blackcat dockerize
It checks for podman first, then docker, builds a small image once (a
minute or two, dependencies included), and opens the same TUI. Your
current directory is mounted at /app, so everything the agent writes
lands in your checkout, and .env is picked up because it is simply
there.
blackcat dockerize --shell # look around inside
blackcat dockerize -- --provider echo tui # no API key needed
blackcat dockerize --build-only # just prepare the image
blackcat dockerize --stop # remove the container
blackcat dockerize --rm-image # remove container and image
The first run creates dockerized/ with the Dockerfile and a Makefile; if
you edit those, add --force only when you want them reset. Nothing is
copied into the image, so source edits take effect on the next start with
no rebuild. Use --runtime docker (or
BLACKCAT_CONTAINER_RUNTIME=docker) when you want docker explicitly.
When neither engine is installed or running, the command does not fail:
it falls back to a rootless sandbox (bwrap, then unshare, then
proot) and finally to the host interpreter (local), running the same
checkout and the same default command with no image build. local
always works and needs no installs. Pin one with --runtime unshare,
and add --dry-run to print the exact fallback command first.
One warning, identical to --yolo on the host: the agent can rewrite the
mounted checkout, including .env. Use --path /tmp/sandbox with a copy
when that matters.
Checkpoint: the TUI opens from the container and a prompt answers.
Step 12: The one-model rule, only the latest deepseek-flash (2 min)
This agent is built, tested and priced against deepseek-flash
(DeepSeek-V4.1-Flash, model id deepseek-flash, version
DeepSeek-V4.1-Flash-1017). It is already the default, so you never have to
pass --model.
What that means in practice:
- Only the latest
deepseek-flashis compatible. Its 1M-token context
is what the compaction budget assumes, its native vision is what
--imageuses, and its tool-calling behaviour is what the agent's
recovery logic targets. - Do not point
--modelat legacy names.deepseek-chat,
deepseek-reasoneranddeepseek-v4-flashare retired aliases. Some
still resolve, but they are served by the current Flash model anyway, so
pinning them buys nothing and breaks assumptions. deepseek-v4-prois not the model for this agent. It exists, it is
faster on paper for some reasoning work, and it has no vision support
and different pricing, so image prompts and the tuned tool loop are not
covered by it.- Check what you are actually talking to with
blackcat models, and if you
ever see a response mentioning an older model, your key or base URL is
pointing somewhere you did not intend.
The only other supported providers are --provider openrouter (any model
OpenRouter routes to) and --provider echo (offline, for testing). The
DeepSeek path expects Flash.
Troubleshooting, in the order things usually break
| Symptom | Cause | Fix |
|---|---|---|
blackcat: command not found |
.venv not active, or install skipped |
source .venv/bin/activate && pip install -e '.[tui]' |
No module named textual when starting tui |
Core installed without the extra | pip install -e '.[tui]' |
ensurepip is not available |
Debian/Ubuntu without python3-venv |
sudo apt install python3-venv, delete .venv, redo step 3 |
401 Unauthorized |
Wrong/expired key, stray whitespace in .env |
Re-copy the key, re-create the line, blackcat models to test |
402 Insufficient Balance |
No balance, or top-up on another account | Top up (min $2) on the account that owns the key |
| Top-up declined | Card holds $2 but the charge is $2.12 | Load ~$3, or pay via PayPal, retry once |
RuntimeError: no API key |
.env in the wrong directory |
Run from the repo root or set BLACKCAT_ENV_FILE |
| Tests skip in bulk | TUI extra absent | pip install -e '.[tui,dev]' |
| Tool call printed as raw markup | Known provider-side DSML leak | Leave recovery on (default); it is repaired automatically |
Still stuck? Run the same command with -v for DEBUG logs on stderr, or
send them to a file with --log-file blackcat.log: the TUI silences
terminal logging on purpose so it cannot corrupt the screen.
Cheat sheet
# setup (once)
python3 -m venv .venv && source .venv/bin/activate
pip install -e '.[tui]'
echo 'DEEPSEEK_API_KEY=sk-...' > .env
# or, the shorthand
make setup
# verify
blackcat --version
blackcat --provider echo prompt "hi" # offline
blackcat models # expect deepseek-flash
blackcat prompt "Reply with exactly: live test ok"
# use
blackcat --yolo tui # the app
blackcat tui # same, with approvals
blackcat tui "fix the failing tests" # one-shot
blackcat chat # plain CLI chat
blackcat --yolo --session app.json chat # resumable
# maintain
make test # unittest suite
make lint # ruff
make reinstall # clean editable reinstall if entry points go missing
Timing recap: 5 minutes of Python, 7 minutes of clone and install, 20
minutes of account and payment, 3 minutes of verification, and you are
running. The remaining time is the agent doing your work.
Cleaning up (2 min)
Nothing hides outside the repository. To remove everything:
deactivate # leave the environment
rm -rf .venv .env # from the repo root
Your API key still exists in the console: revoke it under API keys if
you are done with the account entirely. Unused balance can be refunded
from Billing → Refunds.