Bluma Sign in

Agents, the CLI and the API

Everything the apps can do, an agent or a script can do too, over the same lists. Each tool gets its own token, so you can see what it did and switch it off without touching the rest.

Make an API token

  1. Open app.bluma.sh and open Settings from the bottom of the sidebar.
  2. Under API tokens, type a name such as "Claude Code", choose Can read and change or Read only, choose when it expires (never, 30 days or 90 days), and create the token.
  3. Copy it now. Tokens start with blm_ and are shown once.

From the terminal, sign in with bluma login --email you@example.com, then bluma token add "claude code" makes one (add --read-only or --expires 30d), bluma tokens lists them and bluma token rm <token> revokes one. Making a token needs an email sign-in; an API token cannot make another one. A token can read and change your to-dos unless it is read only, and it never reaches your password or account, so give each agent its own.

Connect an agent over MCP

One command connects Claude Code.

Bluma speaks MCP over Streamable HTTP at https://api.bluma.sh/mcp, with your token in the Authorization header. For Claude Code:

claude mcp add --transport http bluma https://api.bluma.sh/mcp --header "Authorization: Bearer blm_…"

Settings › Connect an agent in the web app shows this command with your new token filled in, and the JSON config for clients that take a file. bluma mcp prints both.

The tools are overview, list_tasks, get_task, add_tasks, update_tasks, complete_tasks, trash_tasks, list_projects, add_project, update_project and add_area. They take batches, accept "today", "tomorrow" or a date like 2027-01-15, and report a failure on one item without dropping the rest.

The bluma command

Sign in once with bluma login --email you@example.com, or create an account with bluma signup --email you@example.com.

bluma add "Renew passport" -w tomorrow -d 2027-01-15 -t errand -c "Photos" -c "Form"
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 rm 3fk                # to the Trash; bluma restore 3fk brings it back
bluma today --json          # every command can print JSON

bluma --help lists every command and option. Scripts and agents can skip signing in by setting BLUMA_URL and BLUMA_TOKEN.

The REST API

The base address is https://api.bluma.sh/v1. Send your token as Authorization: Bearer blm_….

curl https://api.bluma.sh/v1/tasks?view=today \
  -H "Authorization: Bearer blm_…"

Errors come back as { "error": { "code", "message", "issues" } }. A plain-text summary for agents is at bluma.sh/llms.txt.

Seeing and stopping what an agent can do

Settings lists every token with its name, what it can do, when it expires and when it was last used. Revoke one and that tool stops working at once; nothing else is affected. Resetting your password revokes every token and signs out every device.

Still stuck?

Email support@bluma.sh and a person will answer. Say what you were doing and which app you were in. For a security problem, write to security@bluma.sh.