Automate with Tokens, JSON, and Context

Use this guide when you want repeatable, non-interactive CLI runs. You will create or supply a token, switch to machine-readable output, and use spec and context to keep scripts and agents grounded in the current workspace.

Use a token instead of browser login

For CI and non-interactive scripts, set DONEBEAR_TOKEN instead of running donebear auth login.

export DONEBEAR_TOKEN=<token>
donebear task list --json

Token precedence is:

1. --token <token>
2. DONEBEAR_TOKEN
3. The stored session from donebear auth login

That means you can override a local session for one command without changing the session on disk:

donebear --token <token> workspace list --json

Create an API key for automation

Create a long-lived key:

donebear api-key create "CI"

List or revoke keys later:

donebear api-key list
donebear api-key revoke <key-id>

Use JSON, CSV, or TSV output

Use --json for scripting and --format csv|tsv for exports.

donebear task list --json
donebear search "launch" --format csv
donebear history --format tsv

Count-only output works well for health checks and shell conditions:

donebear search "blocked" --total

Target a workspace explicitly

Use --workspace when a script should never depend on the current default workspace:

donebear task list --workspace personal --json

Use the prefix form when you want the workspace at the very front of the command:

donebear workspace=personal task list --json
donebear workspace=personal search "launch"

Generate agent-friendly context

Use spec when an agent needs the command surface without any auth requirement:

donebear spec
donebear spec task add

Use context when an agent needs the current workspace state:

donebear context --json
donebear context --markdown

spec is static and command-focused. context is workspace-aware and stateful.

Export recent work

Capture open tasks as JSON:

donebear task list --state open --json > open-tasks.json

Export search results as CSV:

donebear search "invoice" --format csv > invoice-results.csv

Caveats for automation

• Task IDs can be full UUIDs or unique prefixes of four or more characters.
• Prefix resolution is workspace-scoped, so ambiguous prefixes should be replaced with full IDs in scripts.
• context --markdown is meant for prompt injection and human review, not structured parsing.

Next steps

• Read Command reference for the supported global flags and command groups.
• Follow Import from Things 3 if your automation starts with a migration.
• Switch to API overview if you need direct HTTP access instead of the CLI.