---
name: donebear
description: Operates the Done Bear CLI for command discovery, auth and workspace preflight, task and project workflows, and automation-friendly JSON execution. Validates flags against live help when `spec` drifts and uses safe patterns for state-changing commands. Use when the user asks to run `donebear`, manage Done Bear tasks, projects, workspaces, API keys, or Things imports, inspect `donebear spec` or `donebear context`, or automate Done Bear from the terminal. Hosted MCP: https://mcp.donebear.com/mcp.
---

# Done Bear

Operate `donebear` with a try-first, recover-on-failure workflow. Prefer `--json` for agent parsing.

Done Bear is also available as a hosted MCP server at `https://mcp.donebear.com/mcp`.

Product docs for agents start at `https://donebear.com/llms.txt`, the map of every page. Any donebear.com page has a markdown copy at its URL plus `.md`; follow the map rather than guessing a path.

## Reference Files

| File                                 | Read when                                                        |
| ------------------------------------ | ---------------------------------------------------------------- |
| `references/preflight-and-safety.md` | Auth or workspace errors occur, or before destructive writes     |
| `references/core-recipes.md`         | Running uncommon flows (imports, API keys, workspace management) |
| `references/live-validation.md`      | A command fails unexpectedly or `spec` and runtime disagree      |

## Quick Reference

Use these directly. No `spec` lookup needed.

| Action            | Command                                                                |
| ----------------- | ---------------------------------------------------------------------- |
| Add a task        | `donebear task add "Title" --when today --json`                        |
| List tasks        | `donebear task list --json`                                            |
| List by view      | `donebear task list --view today --json`                               |
| What was finished | `donebear task list --view logbook --json`                             |
| Today's tasks     | `donebear today --json`                                                |
| Complete a task   | `donebear task done <id> --json`                                       |
| Edit a task       | `donebear task edit <id> --title "New" --deadline <YYYY-MM-DD> --json` |
| Read comments     | `donebear comment <id> --json`                                         |
| Comment on a task | `donebear comment add <id> "Text" --json`                              |
| Search            | `donebear search "query" --json`                                       |
| Add project       | `donebear project add "Name" --json`                                   |
| Workspace context | `donebear context --json`                                              |

### `task add` flags

`--when <view>` (inbox|anytime|today|upcoming|someday, default: today, or anytime with `--deadline`, or inbox with `--project`/`--team`), `--deadline <YYYY-MM-DD>`, `-d, --description <text>` (use `--description -` to read from piped stdin), `--project <key-or-id>`, `--team <key-or-id>`, `--workspace <id-or-slug>`.

### `task edit` flags

`--title <text>`, `--when <view>`, `--deadline <date>`, `--clear-deadline`, `--description <text>`, `--clear-description`, `--project <key-or-id>`, `--clear-project`, `--team <key-or-id>`, `--clear-team`.

### `comment` flags

`donebear comment <id>` lists a task's thread oldest first; `comment add <id> <body>`, `comment edit <id> <comment-id> --body <text>`, `comment remove <id> <comment-id>`. Comment ids accept a prefix. A comment is visible to the whole workspace and notifies nobody. Only its author can edit one; removal is permanent (comments have no Trash).

### `task list` flags

`--state <open|done|archived|all>` (default: open), `--view <inbox|anytime|today|upcoming|someday|logbook|trash>`, `--search <query>`, `--limit <n>` (default: 20).

`--view logbook` and `--view trash` widen the state for you, so they read completed and archived tasks whatever `--state` says. Do not pair `--state done` with a bucket view: a completed task's view is logbook, so `--state done --view today` matches nothing. Rows carry the completion date, so what was finished today or this week reads off that rather than the ordering. `--when` on `task add` and `task edit` takes the five bucket views only; `task done` and `task archive` are what move a task to the Logbook or Trash. The iOS and web apps can keep completed to-dos on Today until a day roll or Log Completed (Settings → Preferences → Logging); the CLI still treats every completed task as logbook.

## Intent Map

| Intent                     | Commands                                                                                                                  | Notes                                  |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |
| Discover the CLI           | `donebear spec`, `donebear spec <command> [subcommand]`                                                                   | No auth required                       |
| Learn the concepts         | `donebear guide`, `donebear guide <topic>`                                                                                | No auth required; `guide agents` first |
| Orient the current account | `donebear auth status`, `donebear whoami`, `donebear context`                                                             | `context --markdown` is prompt-ready   |
| Read and triage work       | `task list`, `task show`, `today`, `search`, `history`                                                                    | Prefer `--json` for parsing            |
| Back up or take data out   | `donebear export`                                                                                                         | Read-only; redirect stdout to a file   |
| Change state               | `task add/edit/done`, `project add/edit/done`, `workspace use`                                                            | Trust `--json` output for confirmation |
| Discuss a task             | `comment`, `comment add`, `comment edit`                                                                                  | Workspace-visible; notifies nobody     |
| Risky operations           | `auth logout`, `task archive`, `project archive`, `comment remove`, `api-key revoke`, `import things` without `--dry-run` | Require explicit user intent           |

## Safety Tiers

- `GREEN (execute directly):` `spec`, `guide`, `auth status`, `whoami`, `workspace list/current`, `context`, `task list/show/read/random`, `today`, `search`, `project list/show`, `label list/show`, `team list/show`, `comment`, `history`, `api-key list`, `export`.
- `YELLOW (announce then execute):` `auth login`, `auth signup`, `workspace use/create/join/invite`, `task add/edit/append/prepend/done/reopen/checklist`, `comment add/edit`, `project add/edit/done/unarchive`, `api-key create`, `import things --dry-run`.
- `RED (explicit confirmation required):` `auth logout`, `task archive`, `project archive`, `comment remove`, `api-key revoke`, `import things` without `--dry-run`.
- Do not rely on CLI prompts for safety in agent mode. `--json`, `--dry-run`, `--yes`, and non-TTY execution can bypass confirmations.

## Workflow

### Default: Try First, Recover on Failure

1. **Execute the command directly** with `--json`. Use the Quick Reference above for common commands.
2. **Handle errors reactively:**
   - Exit code 4 (AUTH_REQUIRED): If the human has no account, run `donebear auth signup --email <their-email> --json --no-interactive` (do not invent the address). If they already have one, run `donebear auth login`, then retry the original command.
   - "No workspace selected" or workspace errors: Run `donebear workspace list --json`, then `donebear workspace use <slug>`, then retry.
   - Unknown option error: Run `donebear <command> --help` to get the real flags, then retry.
3. **Trust `--json` output.** When `task add --json` returns `{ "created": true, "id": "..." }`, the task exists. Do NOT call `task show` to validate.
4. **Use `donebear spec` only for uncommon commands** or when you need to discover available subcommands.

### When Preflight IS Needed

Load `references/preflight-and-safety.md` in these cases:

- First interaction when you don't know if auth is configured and the command fails with exit 4
- Multi-workspace accounts where no default is set
- Before destructive RED-tier operations
- When running uncommon commands (import, api-key)

## Anti-patterns

- Running `donebear spec` before every command. Use the Quick Reference for common commands.
- Running `auth status` + `whoami` + `workspace current` before every operation. Try the command first.
- Calling `task show` after `task add` to validate. The `--json` output already confirms success.
- Assuming a default workspace exists when multiple workspaces are available.
- Using `--json` on destructive commands without explicit user approval.
- Running `import things` without a dry run first.
- Relying on ambiguous id prefixes when a full id or key is available.
- Launching interactive mode when an explicit command is easier to verify.

## Repeating tasks

Configure repeat rules in the app. Upcoming copies can be edited or completed early through ordinary task actions. A fixed rule keeps its calendar schedule; an after-completion rule counts from actual completion. CLI date edits move only the copy. In the app's When picker, Make Exception moves one copy and Update Rule changes the fixed schedule. Custom and count-limited patterns need the Repeat editor. In the app, search for Repeating to see rules and upcoming copies. Select multiple repeating tasks and use More to pause, resume, or stop their series. Do not approximate a repeat rule by adding a pile of dated tasks.