---
name: docat
description: Talk to and control a DoCat (a personal AI agent running on its own DCP instance at https://NAME.dcp.run) from the terminal with the docat CLI. Use it to ask the DoCat things, hand it work, pipe logs or files to it, set reminders, run shell commands in its instance, move files, and change its settings, keys, connectors and skills.
---

# docat: your DoCat from the terminal

A DoCat is an AI agent that lives in its own DCP instance (a sandboxed mini VPS) at `https://NAME.dcp.run`.
`docat` talks to it with the DoCat's password. Same binary as `dcp` (`dcp cat ...` works too).

Install: `curl -fsSL https://dcp.run/cli/install.sh | sh`

## When to use
- The person has a DoCat and wants it to do something, or wants to know what it did.
- You want a second agent with its own always-on server: web search, a browser, deploys, reminders by email.
- You need to run a command or read a file inside the DoCat's instance (`/data/work`).

## Sign in (once)
```sh
docat login https://jamie.dcp.run                 # asks for the password on a terminal
echo "$PW" | docat login jamie.dcp.run --password-stdin
```
Or set `DOCAT_URL` and `DOCAT_PASSWORD` (good for CI and agents). The password was emailed when the DoCat was made.

## The commands that matter
```sh
docat ask "what's the weather in Perth?"          # reply on stdout; the chat continues next time
cat build.log | docat ask "why does this fail?"   # piped stdin is attached as a fenced block
docat ask --file photo.jpg "what is this?"        # uploads and attaches (repeat --file)
docat ask --new "start a fresh chat about X"      # -s ID continues a given chat
docat show -n 6                                   # last messages of the current chat
docat tasks                                       # background tasks and their progress
docat remind "check the deploy and tell me" --in 2h    # also --at "2026-10-01 08:00", --cron "0 8 * * 1-5"
docat sh 'ls -la && df -h'                        # runs in /data/work, 20 s max, exits with its code
docat put report.csv data/report.csv              # upload into /data/work (10 MB max)
docat get data/report.csv -                       # download (- = stdout)
docat status                                      # version, models, running work, reminders
```
More: `docat chats`, `docat stop`, `docat drop TASK_ID`, `docat reminders`, `docat unremind ID`,
`docat approve ID [--deny|--always]`, `docat settings [get KEY | set K=V]`, `docat keys set openrouter -`,
`docat mcp add NAME URL`, `docat skills add FILE.md`, `docat chat` (interactive), `docat help CMD`.

## How ask behaves
- The DoCat usually answers at a "front desk" first and hands real work (web, files, deploys) to background
  tasks. `docat ask` waits for those tasks and prints their results after the first reply. `--no-wait` returns
  right away; check later with `docat tasks` and `docat show`. `--timeout 20m` caps the wait.
- Tools it used are listed on stderr as `· used web_search, fetch`. Only the reply goes to stdout.
- If a tool needs the person's OK, stderr shows `docat approve ID`. Ask the person before approving.
- On a terminal the reply streams word by word; in a pipe you get the final text only.

## Conventions
- `--json` on any command prints one JSON object (lists are wrapped, e.g. `{"sessions":[...]}`).
  `docat ask --json` gives `{"session","reply","steps","tasks","approvals"}`.
- Exit codes: 0 ok, 1 error, 2 usage, 3 not signed in or wrong password, 4 not found. `docat sh` exits with the
  command's own code.
- Errors print `error: ...` and a `hint:` with the next step.
- `--cat NAME` picks one of several DoCats (`docat cats`, `docat use NAME`).
- The current chat is remembered per DoCat, so a series of `docat ask` calls is one conversation.

## Gotchas
- The DoCat sleeps after 5 minutes idle; the first call wakes it and can take a few seconds.
- Keys (`docat keys set`) are stored encrypted by DCP, never in files. Pass `-` to read the key from stdin so it
  stays out of shell history. Never print the password or keys.
- Reminders need the DoCat to run on DCP. Repeating ones run at most once an hour. `--at` is your local time.
- Only files under `/data/work` can be moved with put/get.
- Do not make up results. If a task failed or is still running, say so and show `docat tasks`.