# 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 ```bash blackcat --yolo tui ``` Everything below is how you get there. See also: [README.md](README.md) (usage reference), [AGENTS.md](AGENTS.md) (agent rules), [docs/DEFINITION_OF_DONE.md](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. ```bash 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: ```bash 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 use `python` instead of `python3` for the rest of this guide. 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. ```bash 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. ```bash 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: ```bash 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 edit `blackcat/cli.py` and 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 only `aiohttp` and `stealthii`; the full-screen harness additionally needs `textual`, which lives in the `tui` extra. Install it now; adding it later is a second install and a second round of confusion. Install with both: ```bash pip install -e '.[tui]' ``` Windows PowerShell needs double quotes (single quotes are literal there): ```powershell pip install -e ".[tui]" ``` Prefer one command that does step 3 and 4 for you? From the repository root: ```bash 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. ```bash 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: ```bash 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: ```bash source .venv/bin/activate && pip install -e '.[tui]' ``` Optional but useful: confirm the test suite is healthy on your machine: ```bash 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. 1. Open **https://platform.deepseek.com** in a browser. 2. 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. 3. 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. 4. 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) 1. In the console, click **API keys**. 2. Click **Create new API key**. 3. Give it a name that tells you where it lives later: `blackcat-laptop` is better than `key1`. 4. 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. 5. 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. 1. In the console, open **Top up** (sometimes under **Billing**). 2. Enter the amount. **The minimum is $2.** That is the smallest usable deposit, and it is genuinely enough to evaluate this agent. 3. Pick a payment method: **bank card (Visa/Mastercard)**, **PayPal**, **Alipay**, or **WeChat Pay**. 4. 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: 1. `--api-key sk-...` on the command line, 2. the `DEEPSEEK_API_KEY` environment variable (`BLACKCAT_API_KEY` also works; `OPENROUTER_API_KEY` for the OpenRouter provider), 3. a `.env` file 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: ```bash 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 `.env` **in the directory you run the command from**. `BLACKCAT_ENV_FILE=/path/to/other.env` overrides that. - Verify git will ignore it: `git status --short` must not list `.env`. If it does, stop and fix `.gitignore` before 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: ```bash blackcat prompt "Reply with exactly: live test ok" ``` Expected: ``` live test ok ``` Then confirm which model the provider is actually serving: ```bash 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: ```bash 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: ```bash 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 `/costs` to see what the session has spent so far. - `Ctrl+C` cancels the current turn; `Ctrl+Q` (or the quit command) exits. - Long jobs: pass `--session work.json` and 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: ```bash 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. ```bash 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-flash` is compatible.** Its 1M-token context is what the compaction budget assumes, its native vision is what `--image` uses, and its tool-calling behaviour is what the agent's recovery logic targets. - **Do not point `--model` at legacy names.** `deepseek-chat`, `deepseek-reasoner` and `deepseek-v4-flash` are 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-pro` is 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 ```bash # 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: ```bash 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**.