switchdesk

The official command line for SwitchDesk: your to-dos, meetings, notes and recaps from the terminal, for you and for the AI agents you allow. It also runs a local MCP server for Claude Desktop, Claude Code and Cursor.

It uses the same API and the same AI-access key as any other connection, so it can only do what you turned on in SwitchDesk → Settings → AI access, every call shows up in Activity there, and you can undo or revoke from the app.

Needs Node.js 20 or newer and SwitchDesk Pro.

Install and sign in

npm install -g switchdesk
switchdesk login

1. In SwitchDesk on your Mac: Settings → AI access → Claude Code · Cursor → Create. Copy the key (sda_…; it's shown once).
2. Run switchdesk login and paste it. Nothing shows while you paste. The key is checked, then saved in your macOS Keychain (service switchdesk), never in a plain file.
3. switchdesk whoami shows the connection and what it may do.

Keys never go on the command line (shell history). On Linux or in CI, keep the key in your secret store and set SWITCHDESK_TOKEN; the CLI reads it first. switchdesk logout removes the Keychain copy. To end a key, revoke it in SwitchDesk.

Commands

switchdesk todos list [--incoming|--today|--week] [-c Botsi] [-q text] [--done|--all]
switchdesk todos get ID
switchdesk todos add "Call Ana" [-c Botsi | --today | --week --day wed] [--due 2026-10-14] [--repeat "FREQ=WEEKLY;BYDAY=MO"]
switchdesk todos update ID [--title …] [--append-notes …] [-c Work] [--due DATE | --no-due] [--urgent] …
switchdesk todos done|undone|start ID…
switchdesk todos delete ID… [--stop-series]
switchdesk todo-notes add TODO_ID "text" · todo-notes delete NOTE_ID
switchdesk categories list · categories create NAME [--bio …] · categories update ID [--bio …] [--color #RRGGBB]
switchdesk meetings list [--since 7d] [-q …] · meetings search QUERY · meetings get ID [--transcript] · meetings transcript ID [--all]
switchdesk notes list [-q …] · notes search QUERY · notes get ID · notes create "text" · notes append ID "text" · notes update ID --title … · notes delete ID
switchdesk recap [day|week]
switchdesk approvals list · approvals get ID · approvals ask "Move gym?" [--option …] [--wait] · approvals propose -f ops.json
switchdesk whoami · tools · mcp

Shortcuts: ls, add, show, edit, done, undone, start, rm, ask, proposals. switchdesk <command> --help lists every option. - in place of text reads it from stdin (notes create -).

Output is a readable table; add --json to any command for the API's JSON. Activity and Undo stay in the app: an AI key can't read or undo them, by design.

Exit codes: 0 ok · 1 error · 2 not allowed (turned off, paused, revoked, no Pro) · 3 waiting for your approval in SwitchDesk · 4 not available yet, meetings/notes not shared, or the connection needs your emailed-code confirm · 5 rate limited.

Local MCP server

switchdesk mcp speaks MCP over stdio and forwards to https://api.switchdesk.org/mcp with your stored key, so the key stays in the Keychain instead of a config file.

Claude Code: claude mcp add switchdesk -- switchdesk mcp

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json) and Cursor (~/.cursor/mcp.json):

{ "mcpServers": { "switchdesk": { "command": "switchdesk", "args": ["mcp"] } } }

If the app can't find switchdesk, use the full path from which switchdesk.

For AI agents

docs/AGENTS.md is a snippet for your AGENTS.md / CLAUDE.md, and docs/claude-skill/switchdesk/SKILL.md is a Claude Code skill (copy the switchdesk folder into ~/.claude/skills/).

Safety: don't allowlist every switchdesk command for a coding agent (Bash(switchdesk:*)): a web page or file it reads could talk it into deleting things. Allow the read commands you want, and keep writes behind a prompt. A key stored on a shared machine (a Grok Bot computer, a CI runner) is readable by everything that runs there.

API reference: https://api.switchdesk.org/docs · Privacy: https://api.switchdesk.org/privacy