TodoBud CLI & agent guide

Use the todobud CLI to read and update todos, projects, notes, and activities. Agents can start at /llms.txt.

Install and sign in

npm install -g todobud
todobud auth login
todobud auth status

Check todobud auth status before starting work. If the CLI is missing or authentication fails, ask the user to install it and complete login. For SSH or a headless environment, use todobud auth login --device and let the user authorize it in their browser.

Never put an API key or access token in a URL, log, activity message, or note.

Find work and inspect commands

todobud --help
todobud todos --help
todobud --json todos list --filter status=T --all
todobud --json todos get 123

Use --json when parsing output. Use --all on list commands when you need every page. Replace example ID 123 with the todo the user asked you to work on; read its requirements before making changes.

Requests use your personal workspace by default. Team access is currently disabled. If a saved CLI workspace setting points to a team, use todobud --workspace personal --json todos list.

Keep the todo up to date

Mark the todo in progress when work starts. Post a comment describing the result and validation, and attach the real PR link when one exists. Mark it done only when its requirements are complete.

todobud todos update 123 --status IP
todobud activities create --todo 123 --kind comment --message "Implemented the requested change and verified it."
todobud activities create --todo 123 --kind link --url https://github.com/OWNER/REPO/pull/42
todobud todos update 123 --status D

Status codes: T (todo), IP (in progress), D (done), and C (cancelled). Use todobud COMMAND --help for available flags, and follow the user's repository instructions.

API references

For direct API integrations, read the Markdown API guide or interactive API documentation (staff only).