donebear

Command-line interface for Done Bear.

Quick start

Install and build from the repo root:

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

Run the CLI:

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

Log in via browser OAuth:

npx donebear auth login
npx donebear auth login --provider google
npx donebear auth login --provider github

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

List and search:

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

Edit:

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

Complete and manage:

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

Checklists:

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

Task IDs can be a full UUID or a unique prefix (4+ characters).

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 <workspace-id> --email [email protected]

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 | — | List today's tasks | | search | — | Search tasks by title or notes | | history | — | Workspace audit log | | context | — | Workspace state snapshot (--markdown for prompts) | | spec | — | CLI spec for agent discovery (no auth required) | | api-key | — | create, list, revoke | | import things | — | Import from Things 3 (--dry-run supported) | | whoami | — | 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 prefix "..." is ambiguous | Use the full task ID from task list |

Development

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