@donebear/cli

Done Bear CLI for OAuth auth, workspace selection, and task workflows against manage-api.

Quick start

1. Install workspace dependencies from repo root:

npm install

2. Build the CLI package:

npm run build --workspace=packages/donebear-cli

3. Set required environment variables:

export DONEBEAR_SUPABASE_URL="https://<project-ref>.supabase.co"
export DONEBEAR_SUPABASE_PUBLISHABLE_KEY="<publishable-or-anon-key>"
export DONEBEAR_API_URL="http://127.0.0.1:3001"

4. Define a local runner command:

CLI="npm exec --workspace=packages/donebear-cli donebear --"

5. Authenticate and run the core task flow:

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

OAuth setup

The default callback URL is:

http://127.0.0.1:8787/auth/callback

Add that URL to Supabase Auth allowed redirect URLs.

Login options:

$CLI auth login --provider google
$CLI auth login --provider github --port 8787 --timeout 180
$CLI auth login --no-open

Check and clear auth:

$CLI auth status
$CLI whoami
$CLI auth logout

Core task flows

Capture:

$CLI task add "Draft release notes" --when inbox
$CLI task add "Pay invoice" --when today --deadline 2026-03-05

Review:

$CLI task list --state open --limit 50
$CLI task list --state all --search invoice
$CLI task show <task-id-or-prefix>

Triage/edit:

$CLI task edit <id> --title "Pay vendor invoice"
$CLI task edit <id> --notes "Waiting for approval" --when upcoming
$CLI task edit <id> --clear-deadline

Complete and clean up:

$CLI task done <id>
$CLI task reopen <id>
$CLI task archive <id>
$CLI task unarchive <id>

Workspace:

$CLI workspace create "Personal" --slug personal --no-use
$CLI workspace join <invite-code>
$CLI workspace clear

Notes:

• task show|done|reopen|archive|unarchive|edit accept a full task ID or unique ID prefix.
• Prefix resolution uses your selected workspace, or --workspace if provided.
• task list paginates through GraphQL results, so it is not capped at 100 tasks.
• donebear auth, donebear workspace, and donebear task run sensible defaults (status, list workspaces, list open tasks).

Command reference

Global options:

• --json machine-readable output
• --token <token> explicit bearer token
• --api-url <url> manage-api base URL
• --debug include stack traces in failures
• --no-color disable ANSI color

Root commands:

• auth (default: status) + login/status/logout
• workspace (default: list) + list/current/use/clear/create/join
• task (default: list open) + list/show/add/edit/done/reopen/archive/unarchive
• whoami print current authenticated user (me alias)

Run donebear <command> --help for aliases and short flags.

JSON and automation

Example: pick current workspace id:

$CLI workspace current --json | jq -r '.workspace.id'

Example: list open task titles:

$CLI task list --state open --json | jq -r '.tasks[].title'

Auth token precedence:

1. --token <token>
2. DONEBEAR_TOKEN
3. stored session (auth login)

Environment variables

| Variable | Purpose | Default / fallback | | --- | --- | --- | | DONEBEAR_SUPABASE_URL | Supabase project URL for OAuth | fallback: NEXT_PUBLIC_SUPABASE_URL, SUPABASE_URL | | DONEBEAR_SUPABASE_PUBLISHABLE_KEY | Supabase publishable/anon key | fallback: NEXT_PUBLIC_SUPABASE_PUBLISHABLE_OR_ANON_KEY, SUPABASE_ANON_KEY | | DONEBEAR_API_URL | manage-api base URL | fallback: NEXT_PUBLIC_RESERVE_MANAGE_API, default http://127.0.0.1:3001 | | DONEBEAR_TOKEN | non-interactive bearer token | none | | DONEBEAR_CONFIG_DIR | override local config/cache directory | OS config dir + /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 | Cause | Fix | | --- | --- | --- | | Not authenticated. Run donebear auth login. | Missing or expired token | Run $CLI auth login, or pass --token | | OAuth times out waiting for callback | Callback URL/port mismatch or blocked browser redirect | Verify Supabase redirect URL and retry with --port or --no-open | | No default workspace selected. | Multiple workspaces and none selected | Run $CLI workspace use <id-or-slug> | | Task prefix "..." is ambiguous | Prefix matches multiple tasks | Use full task ID from task list |

Development

From repo root:

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

Package-local start command:

npm run start --workspace=packages/donebear-cli