donebear

Command-line interface for Done Bear, a local-first GTD task manager for the web, macOS, Windows, Linux, and iOS.

Docs: donebear.com/docs/cli · Account: donebear.com

Quick start

npm install -g donebear
donebear --help

Or run it without installing:

npx donebear --help

Log in and start using it:

npx donebear auth login
npx donebear workspace list
npx donebear workspace use <workspace-id-or-slug>
npx donebear task add "Ship donebear CLI" --when today
npx donebear task list

No environment variables are needed; the CLI connects to production by default.

Authentication

Create an account from a coding agent (the human verifies email; do not invent one):

npx donebear auth signup --email [email protected] --json --no-interactive

Log in via browser OAuth:

npx donebear auth login

Check or clear your session:

npx donebear auth status
npx donebear whoami
npx donebear auth logout

For CI or scripts, use an API key instead:

npx donebear api-key create "CI"
export DONEBEAR_TOKEN=<key>
npx donebear task list --json

Token precedence: --token flag > DONEBEAR_TOKEN env var > stored session.

Tasks

Add tasks:

npx donebear task add "Draft release notes" --when inbox
npx donebear task add "Pay invoice" --when today --deadline 2026-03-05
npx donebear task add "Write tests" --project PROJ --team ENG

Without --when, a new task lands in Today. Pass --when inbox to capture something without scheduling it.

List and search:

npx donebear task list
npx donebear task list --state all --search invoice
npx donebear task show <number>
npx donebear today
npx donebear search "invoice"

Edit:

npx donebear task edit <number> --title "Pay vendor invoice"
npx donebear task edit <number> --description "Waiting for approval" --when upcoming
npx donebear task edit <number> --clear-deadline
npx donebear task append <number> "Added follow-up note"

Complete and manage:

npx donebear task done <number>
npx donebear task reopen <number>
npx donebear task archive <number>

Checklists:

npx donebear task checklist <number>
npx donebear task checklist <number> add "Subtask title"
npx donebear task checklist <number> done <item-id>
npx donebear task checklist <number> remove <item-id>

Task numbers are positive integers scoped to a workspace.

Projects

npx donebear project list
npx donebear project add "Q1 Launch" --key LAUNCH --target-date 2026-06-30
npx donebear project edit LAUNCH --target-date 2026-03-31
npx donebear project done LAUNCH
npx donebear project archive LAUNCH

Projects accept a full ID, project key, or name.

Workspaces

npx donebear workspace list
npx donebear workspace use <id-or-slug>
npx donebear workspace create "Personal" --slug personal
npx donebear workspace join <invite-code>
npx donebear workspace members <workspace-id>
npx donebear workspace invite --email [email protected]
npx donebear workspace invite --share --copy

Output formats

npx donebear task list --json
npx donebear task list --format csv > tasks.csv
npx donebear task list --copy          # copy to clipboard
npx donebear task list --total         # count only

Global options

| Flag | Description | | ----------------- | ------------------------ | | --json | Machine-readable output | | --format <fmt> | text, json, csv, or tsv | | --copy | Copy output to clipboard | | --total | Print count only | | --token <tok> | Explicit bearer token | | --api-url <url> | API base URL override | | --debug | Include stack traces | | --no-color | Disable ANSI color |

Commands

| Command | Default action | Subcommands | | --------------- | -------------- | ------------------------------------------------------------------------------------------------- | | auth | status | login, status, logout | | workspace | list | list, current, use, clear, create, join, members, invitations, invite | | task | list open | list, show, add, edit, done, reopen, archive, unarchive, read, append, prepend, random, checklist | | project | list | list, show, add, edit, done, archive, unarchive | | label | list | list, show | | team | list | list, show | | today | n/a | List today's tasks | | search | n/a | Search tasks by title or description | | history | n/a | Workspace audit log | | context | n/a | Workspace state snapshot (--markdown for prompts) | | spec | n/a | CLI spec for agent discovery (no auth required) | | guide | n/a | Concept guides for agents (no auth required) | | doctor | n/a | Environment diagnostics | | api-key | n/a | create, list, revoke | | import things | n/a | Import from Things 3 (--dry-run supported) | | export | n/a | Export a workspace as a portable JSON archive on stdout | | whoami | n/a | Print current user |

Run npx donebear <command> --help for full details.

Environment variables

These are optional; the CLI works out of the box for production use.

| Variable | Purpose | Default | | ----------------------------------- | ------------------------------ | -------------------------- | | DONEBEAR_TOKEN | Non-interactive bearer token | none | | DONEBEAR_API_URL | API base URL override | https://api.donebear.com | | DONEBEAR_SUPABASE_URL | Supabase project URL for OAuth | production instance | | DONEBEAR_SUPABASE_PUBLISHABLE_KEY | Supabase publishable key | production key | | DONEBEAR_CONFIG_DIR | Config/cache directory | ~/.config/donebear | | DONEBEAR_DEBUG | Enable debug logging (1) | disabled |

Exit codes

| Code | Meaning | | ---- | ----------------------- | | 0 | Success | | 1 | General error | | 2 | Cancelled or timeout | | 4 | Authentication required |

Troubleshooting

| Symptom | Fix | | ---------------------------------------- | ------------------------------------------------- | | Not authenticated | Run npx donebear auth login or pass --token | | OAuth times out | Check browser, retry with --port or --no-open | | No default workspace selected | Run npx donebear workspace use <id-or-slug> | | Task number must be a positive integer | Use the number from task list |

Development

Build from a checkout of the monorepo:

npm install
npm run build --workspace=apps/cli

Then, from repo root:

npm run lint --workspace=apps/cli
npm run check-types --workspace=apps/cli
npm run test --workspace=apps/cli
npm run build --workspace=apps/cli