switchdesk CLI reference

#Install and sign in

npm install -g switchdesk
switchdesk login
switchdesk whoami

1. In SwitchDesk on your Mac: Settings → AI Access → Connect an AI → Terminal & coding tools (CLI), pick what it may do, Continue. “Copy the key now. It won’t be shown again.”
2. Run switchdesk login and paste the key. Nothing shows while you paste. The key is checked, then saved in your macOS Keychain (service switchdesk, account $USER), never in a plain file.
3. switchdesk whoami shows the connection and what it may do. switchdesk logout removes the Keychain copy; to end a key, revoke it in SwitchDesk.

Needs Node.js 20 or newer and SwitchDesk Pro. Keys never go on the command line (shell history): login --stdin reads one from a pipe.

#Where the key comes from

1. SWITCHDESK_TOKEN, if set (Linux, CI, a cloud agent’s secret store).
2. The macOS Keychain item switchdesk / $USER (what switchdesk login writes; the app’s “Without the CLI” setup uses the same item).
3. A token file you made yourself: ~/.config/switchdesk/token (or under $XDG_CONFIG_HOME), refused unless it is chmod 600.

#Output and exit codes

Output is a table; --json on any command prints the API’s JSON (errors too, on stdout). Server text is stripped of control characters before it reaches your terminal. Writes send an idempotency key, so the one automatic retry after a network error can’t act twice.

Error codes behind 2, 4 and 5: capability_off → 2, plan_required → 2, paused → 2, missing_key → 2, invalid_key → 2, revoked → 2, expired → 2, not_available_yet → 4, copy_off → 4, transcripts_off → 4, needs_confirm → 4, no_mac → 4, brain_off_for_ai → 4, brain_off → 4, secret → 2, rate_limited → 5. Everything else is 1. Codes: Errors.

#Shortcuts

Inside a group: ls = list, show = get, new = create, rm = delete, edit = update. A bare group lists (switchdesk todos), a group plus an id gets one (switchdesk notes <id>), and - in place of text reads stdin (switchdesk notes create -). switchdesk <command> --help prints the options below.

#Local MCP server: switchdesk mcp

switchdesk mcp speaks MCP over stdio and forwards each message to https://api.switchdesk.org/mcp with the stored key, so no MCP config file holds it. Without a key, every request is answered with “run switchdesk login”.

# Claude Code
claude mcp add switchdesk -- switchdesk mcp

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

Put the second block in ~/.cursor/mcp.json (Cursor) or ~/Library/Application Support/Claude/claude_desktop_config.json (Claude Desktop). If the app can’t find switchdesk, use the full path from which switchdesk.

#Commands

#switchdesk login

Save your SwitchDesk AI key in the macOS Keychain.

switchdesk login [--stdin]

Options:

• --stdin: Read the key from stdin instead of a hidden prompt

Calls get_access. Add --json for the API’s JSON.

#switchdesk logout

Remove the key from your Keychain (revoke it in SwitchDesk to end it).

switchdesk logout

#switchdesk whoami

This connection: name, access, plan.

switchdesk whoami

Calls get_access. Add --json for the API’s JSON.

#switchdesk status

Same as whoami.

switchdesk status

Calls get_access. Add --json for the API’s JSON.

#switchdesk todos list

List to-dos (open ones by default).

switchdesk todos list [--incoming|--today|--week|--section S] [-c CATEGORY] [-q TEXT] [--done|--all]

Options:

• --incoming
• --today
• --week: This Week
• --section S: incoming|today|week|category|uncategorized|assigned|done
• -c, --category NAME
• --category-id ID
• -q, --query TEXT: Search titles and notes
• --done: Done to-dos only
• --all: Open and done
• --backlog
• --due-before DATE
• --notes: Include each to-do's notes
• --limit N
• --cursor C

Calls list_todos. Add --json for the API’s JSON.

#switchdesk todos get

One to-do with notes, sub-to-dos and Team Notes.

switchdesk todos get ID

Calls get_todo. Add --json for the API’s JSON.

#switchdesk todos add

Add a to-do (Incoming unless you say where).

switchdesk todos add TITLE [-c CATEGORY] [--today|--week [--day mon]] [--due DATE] [--repeat RULE] [--notes TEXT]

Options:

• -c, --category NAME
• --category-id ID
• --incoming
• --today
• --week: This Week
• --day DAY: With --week: 1-7 or mon…sun
• --next-week
• --notes TEXT
• --tag CATEGORY: For Incoming: the category it probably belongs to
• --due DATE
• --repeat RULE: An RRULE like FREQ=WEEKLY;BYDAY=MO
• --tz ZONE: IANA time zone, when SwitchDesk doesn't know yours
• --parent ID: Add it as a sub-to-do
• --urgent
• --estimate MIN

Calls add_todo. Add --json for the API’s JSON.

#switchdesk todos update

Change only the fields you pass.

switchdesk todos update ID [--title T] [--append-notes T] [-c CATEGORY|--today|--week] [--due DATE|--no-due] [--urgent] …

Options:

• --title T
• --notes T: Replace the notes
• --append-notes T
• -c, --category NAME
• --category-id ID
• --today
• --week
• --uncategorized
• --day DAY
• --no-day: The week's backlog
• --next-week
• --no-next-week
• --due DATE
• --no-due
• --repeat RULE
• --no-repeat: Stop repeating
• --urgent
• --not-urgent
• --blocked
• --not-blocked
• --backlog
• --no-backlog
• --estimate MIN
• --priority 1-10
• --progress T: Progress note
• --parent ID: Nest under a main to-do
• --no-parent: Make it a main to-do
• --tz ZONE

Calls update_todo. Add --json for the API’s JSON.

#switchdesk todos done

Check off to-dos.

switchdesk todos done ID [ID…]

Calls set_todo_state. Add --json for the API’s JSON.

#switchdesk todos undone

Reopen to-dos.

switchdesk todos undone ID [ID…]

Calls set_todo_state. Add --json for the API’s JSON.

#switchdesk todos start

Mark to-dos in progress.

switchdesk todos start ID [ID…]

Calls set_todo_state. Add --json for the API’s JSON.

#switchdesk todos delete

Delete to-dos (you can Undo in SwitchDesk for 7 days).

switchdesk todos delete ID [ID…] [--stop-series]

Options:

• --stop-series: Needed for a repeating to-do: ends the series

Calls delete_todos. Add --json for the API’s JSON.

#switchdesk todo-notes add

Post a Team Note on a to-do.

switchdesk todo-notes add TODO_ID TEXT…

Calls add_todo_note. Add --json for the API’s JSON.

#switchdesk todo-notes delete

Delete one of your Team Notes.

switchdesk todo-notes delete NOTE_ID

Calls delete_todo_note. Add --json for the API’s JSON.

#switchdesk categories list

Categories with their bios.

switchdesk categories list

Calls list_categories. Add --json for the API’s JSON.

#switchdesk categories create

Create a category.

switchdesk categories create NAME [--bio TEXT] [--color #RRGGBB]

Options:

• --bio TEXT
• --color #RRGGBB

Calls create_category. Add --json for the API’s JSON.

#switchdesk categories update

Change a category's bio or colour (never its name).

switchdesk categories update ID [--bio TEXT] [--color #RRGGBB]

Options:

• --bio TEXT
• --color #RRGGBB

Calls update_category. Add --json for the API’s JSON.

#switchdesk meetings list

Meetings you share with AI, newest first.

switchdesk meetings list [--since 7d|DATE] [--until DATE] [-c CATEGORY] [-q TEXT]

Options:

• --since DATE|7d
• --until DATE
• -c, --category NAME
• -q, --query TEXT
• --limit N
• --cursor C

Calls list_meetings. Add --json for the API’s JSON.

#switchdesk meetings search

Full-text search over meetings (and transcripts when allowed).

switchdesk meetings search QUERY… [--since DATE] [-c CATEGORY] [--limit N]

Options:

• --since DATE|7d
• -c, --category NAME
• --limit N

Calls search_meetings. Add --json for the API’s JSON.

#switchdesk meetings get

A meeting's summary, action items and your notes.

switchdesk meetings get ID [--include summary,action_items,my_notes,transcript]

Options:

• --include LIST
• --transcript: Also the transcript's first page

Calls get_meeting. Add --json for the API’s JSON.

#switchdesk meetings transcript

A meeting's transcript (one page, or --all).

switchdesk meetings transcript ID [--page N | --all]

Options:

• --page N
• --all: Every page

Calls get_meeting. Add --json for the API’s JSON.

#switchdesk notes list

Notepad notes you share with AI, last changed first.

switchdesk notes list [-q TEXT] [--tag TAG]

Options:

• -q, --query TEXT
• --tag TAG
• --limit N
• --cursor C

Calls list_notes. Add --json for the API’s JSON.

#switchdesk notes search

Full-text search over shared notes.

switchdesk notes search QUERY… [--limit N]

Options:

• --limit N

Calls search_notes. Add --json for the API’s JSON.

#switchdesk notes get

One note's whole body.

switchdesk notes get ID

Calls get_note. Add --json for the API’s JSON.

#switchdesk notes create

Create a note (queued for your Mac).

switchdesk notes create [--title T] [--tag TAG]… BODY…|-

Options:

• --title T
• --tag TAG (repeatable)

Calls create_note. Add --json for the API’s JSON.

#switchdesk notes append

Add text at the end of a note (queued).

switchdesk notes append ID TEXT…|-

Calls append_to_note. Add --json for the API’s JSON.

#switchdesk notes update

Retitle or retag a note (queued).

switchdesk notes update ID [--title T] [--tag TAG]… [--clear-tags]

Options:

• --title T
• --tag TAG (repeatable): Replaces the whole tag list
• --clear-tags

Calls update_note. Add --json for the API’s JSON.

#switchdesk notes delete

Move a note to the Notes trash (queued).

switchdesk notes delete ID

Calls delete_note. Add --json for the API’s JSON.

#switchdesk recap get

The newest day or week recap your Mac made.

switchdesk recap get [day|week] [--date DATE]

Options:

• --date DATE

Calls get_recap. Add --json for the API’s JSON.

#switchdesk brain search

Search your Brain (cited snippets + the names it knows).

switchdesk brain search QUERY… [--space NAME] [--limit N]

Options:

• -s, --space NAME: One space (name or id)
• --limit N

Calls search_brain. Add --json for the API’s JSON.

#switchdesk brain page

A Brain page: a person, company, project or topic, or a site's context page.

switchdesk brain page ID [--kind entity|page]

Options:

• --kind KIND: entity or page

Calls get_brain_page. Add --json for the API’s JSON.

#switchdesk brain remember

Tell your Brain to remember something (asks you first by default).

switchdesk brain remember TEXT…|- [--space NAME]   (or: switchdesk remember TEXT…)

Options:

• -s, --space NAME: File it in this space (name or id)

Calls remember. Add --json for the API’s JSON.

#switchdesk approvals list

This connection's approval cards.

switchdesk approvals list [--status pending|approved|denied|answered|expired|withdrawn] [--since ISO]

Options:

• --status S
• --since ISO
• --limit N

Calls list_proposals. Add --json for the API’s JSON.

#switchdesk approvals get

One approval card's status, results and answer.

switchdesk approvals get ID

Calls get_proposal. Add --json for the API’s JSON.

#switchdesk approvals ask

Ask the person a question in SwitchDesk.

switchdesk approvals ask QUESTION… [--option A]… [--todo ID]… [--wait] [--timeout SECONDS]

Options:

• --option TEXT (repeatable): Up to 3 answers (default Yes / No)
• --todo ID (repeatable)
• --wait: Wait for the answer
• --timeout SECONDS: With --wait (default 600)

Calls ask_me, get_proposal. Add --json for the API’s JSON.

#switchdesk approvals propose

Send several changes as ONE approval card.

switchdesk approvals propose -f ops.json|- [--summary TEXT]

Options:

• -f, --file FILE
• --summary TEXT

Calls propose_changes. Add --json for the API’s JSON.

#switchdesk activity

Where to see what this connection did.

switchdesk activity

#switchdesk undo

Where to undo a change.

switchdesk undo

#switchdesk mcp

Run a stdio MCP server that proxies to SwitchDesk (for Claude Desktop, Claude Code, Cursor).

switchdesk mcp

#switchdesk tools

Every API tool and the command that calls it (--check: fail if one is missing).

switchdesk tools [--check]

Options:

• --check

#switchdesk call

Call any API tool with JSON arguments (advanced).

switchdesk call TOOL [--args JSON | --args-file FILE|-]

Options:

• --args JSON
• --args-file FILE

#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. For agent instructions see the Claude Code skill.