Your to-do list, from the terminal
Bluma has a REST API that every account can use today, and a bluma command built on it. Both work on the same lists as the Mac, iPhone and web apps.
Open in browserRead the API guide
What you can use today
- REST API: open to every account at
https://api.bluma.sh/v1. Make a token in Settings or withbluma token addand send it as a bearer token. A token can be read only, and can expire after 30 or 90 days. - MCP server: open to every account. See Bluma for agents.
- The
blumacommand: for macOS and Linux, installed with Homebrew, npm or one line of shell.
Install
brew install arnenoori/bluma/bluma # Homebrew
npm install -g bluma-cli # npm (or try it: npx bluma-cli today)
curl -fsSL https://bluma.sh/install.sh | sh
bluma login
Each one installs the same self-contained bluma program for Apple silicon, Intel and ARM. The script checks the download against its published checksum.
The REST API
curl https://api.bluma.sh/v1/tasks?view=today \
-H "Authorization: Bearer blm_…"
curl -X POST https://api.bluma.sh/v1/tasks \
-H "Authorization: Bearer blm_…" -H "content-type: application/json" \
-d '{"title": "Renew passport", "when": "tomorrow", "deadline": "2027-01-15"}'
GET /tasks?view=today, also inbox, upcoming, anytime, someday, logbook and trash, with filters for project, area, tag and text.POST /tasks,PATCH /tasks/:id,DELETE /tasks/:idandPOST /tasks/:id/restore. Projects, areas and headings have the same shape.GET /sync?since=<rev>returns everything changed since a revision, which is how the apps stay in step.- Errors are JSON with a code, a message and the fields at fault.
The bluma command
$ bluma add "Renew passport" -w tomorrow -d 2027-01-15 -t errand -c "Photos" -c "Form" Added 3fk2 Renew passport $ bluma done 3fk Completed 3fk2 Renew passport
bluma add "Call mum" -w today --evening -r "today 18:30"
bluma add "Water the plants" --repeat "every 3 days after completion"
bluma today # also: inbox, upcoming, anytime, someday, logbook, trash
bluma list -p website -q copy
bluma done 3fk # any unique id prefix works
bluma edit 3fk -w someday -p none
bluma today --json # every command can print JSON
- Reminders, repeats and This Evening from flags:
--remind,--repeat,--evening. - Import:
bluma import thingsreads a copy of your Things 3 database, andbluma import todoisttakes Todoist's CSV exports. Both have--dry-run. - Export:
bluma exportprints everything in your account as JSON. - Tokens for agents and scripts: sign in with
bluma login --email you@example.com, thenbluma token add "claude code". Add--read-onlyfor a token that cannot change anything, and--expires 30dfor one that stops working by itself.bluma tokensshows what each one can do and when it expires. Making a token needs an email sign-in; an API token cannot make another one. - Scripts and CI: set
BLUMA_URLandBLUMA_TOKENand skip signing in.
Questions
How do I install the bluma command?
With Homebrew, npm or the install script: see Install above. It is one self-contained program, with nothing else to set up.
Is the API rate limited?
There is no published limit. As the terms say, automated use that degrades the service for others may be limited.
Does the API cost anything?
No. Bluma is free to use today, including the API. There is no paid plan.