AI MindClip CLI User Guide
Read your AI MindClip data from the command line: browse recordings, read transcripts and AI summaries, check your to-dos, and get daily recaps and weekly summaries. You can also have AI assistants like Claude Code and Codex run these commands for you, so you can query your recordings in plain language.
1Check your environment
Run this in your terminal:
node -v
You need version 18 or later. If Node.js isn't installed or your version is too old, install the latest LTS version from nodejs.org first.
Also, make sure your MindClip recordings have synced to the cloud. Recordings that are still on the device and haven't been uploaded can't be read.
✓Done when: node -v prints v18 or later.
2Install the CLI
npm install -g @switchbot/openapi-cli
After installation, check the version:
switchbot --version
✓Done when: The version number is 3.9.0 or later.
3Sign in to your account
Choose either of the following methods.
Option 1: Sign in with your browser
switchbot auth login
Your browser opens the authorization page automatically. After you sign in and confirm, your credentials are saved to the system keychain.
On a remote machine or one without a graphical interface, add --no-open and then manually open the link printed in the terminal:
switchbot auth login --no-open
Option 2: Token / Secret
Copy your Token and Secret from App → Profile → Preferences → Developer Options, then run:
switchbot config set-token <token> <secret>
You can also set them as environment variables:
export SWITCHBOT_TOKEN=your_token
export SWITCHBOT_SECRET=your_secret
Verify your sign-in
After signing in with either method, run the self-check:
switchbot doctor
✓Done when: switchbot doctor shows your credentials are valid, with no errors.
4Find your MindClip
List the MindClip devices on your account:
switchbot devices list --filter type="AI MindClip"
Note the device ID in the output, then use it to try reading your 5 most recent recordings:
switchbot mindclip recordings --device <device-id> --page 1 --size 5
✓Done when: You can see your list of recordings (each with an id, displayName, and createdTime).
5Let your AI assistant use the CLI
Any AI assistant that can run commands in a terminal can run switchbot mindclip commands directly to read your data, such as Claude Code, Codex, Gemini CLI, and Cursor in Agent mode. No extra installation or configuration is needed.
Add the following instructions to the instructions file your AI assistant reads, and it will know which commands to use:
| AI assistant | Instructions file |
|---|---|
| Claude Code | CLAUDE.md in the project root |
| Codex / Cursor | AGENTS.md in the project root |
| Gemini CLI | GEMINI.md in the project root |
## AI MindClip
Use `switchbot mindclip` commands to read my AI MindClip data. Output is JSON, with the data in the `data` field.
- Device ID: <device-id>
- List recordings: switchbot mindclip recordings --device <device-id> --page 1 --size 20
- Recording details / transcript / AI summary: switchbot mindclip recording|transcript|summary <recording-id>
- To-dos: switchbot mindclip todos --completed 0 --page 1 --size 20
- Daily recap / urgent to-dos: switchbot mindclip daily|urgent-todos --date YYYY-MM-DD
- Weekly summary: switchbot mindclip weekly --week YYYY-Www
Replace <device-id> with the ID you noted in step 4. The first time your AI assistant runs a command, it will usually ask you to confirm — just allow it.
✓Done when: When you tell your AI assistant "List my 5 most recent MindClip recordings", it runs switchbot mindclip recordings and returns your list of recordings.
6Start using it
Just ask your AI assistant questions in plain language, and it runs the matching commands for you:
- "List my 10 most recent MindClip recordings"
- "Summarize this afternoon's meeting"
- "Give me the transcript of Tuesday's recording, with each speaker labeled"
- "What's my daily recap for today?"
- "Summarize this week's recordings"
- "What urgent to-dos do I have today?"
- "Write a follow-up email based on the to-dos from yesterday's meeting"
That's it — you're all set up. If you run into problems, see "FAQ" below.
Advanced usage
Terminal commands
You can also run commands yourself in the terminal, without going through an AI assistant. Output is JSON, with the data in the data field.
# Recordings
switchbot mindclip recordings --device <device-id> --page 1 --size 20
switchbot mindclip recording <recording-id>
switchbot mindclip transcript <recording-id>
switchbot mindclip summary <recording-id>
# To-dos
switchbot mindclip todos --completed 0 --page 1 --size 20
# AI recaps
switchbot mindclip daily --date 2026-10-14
switchbot mindclip weekly --week 2026-W42
switchbot mindclip urgent-todos --date 2026-10-14
# Device status (battery, recording, uploading, etc.)
switchbot devices status <device-id>
For all parameters, see "Command parameters". Combine with jq for simple automation — for example, to export today's daily recap:
switchbot mindclip daily --date $(date +%F) | jq -r '.data.list[0].summaryContent'
Webhook automation
If you want to automatically trigger follow-up workflows when a recording finishes uploading, a transcription completes, or a recap is generated, you can subscribe to a Webhook:
switchbot webhook setup https://your-server.example.com/mindclip
You can also receive and print events locally first for debugging:
switchbot events tail --port 8080
MindClip pushes the following events (eventType: changeReport, deviceType: AI MindClip):
| Event field | When it fires |
|---|---|
chargeUploadCompleted |
A recording finishes uploading while charging (includes fileID and fileName) |
transcription |
The transcription status changes (status 0–5; 0 means not transcribed; for the other values, see the transcription status in "Data fields") |
dailySummary |
A daily recap has been generated |
weeklySummary |
A weekly summary has been generated |
A typical workflow: when you receive transcription.status = 2, call switchbot mindclip summary <fileID>, then push the summary to Notion or Slack.
Changelog
| Version | Date | Changes |
|---|---|---|
| V1.0 | 2026-10-14 | Initial version, based on @switchbot/openapi-cli 3.9.0 and the AI MindClip OpenAPI documentation |
FAQ
Troubleshooting
| Symptom | Solution |
|---|---|
command not found: switchbot |
Make sure the installation in step 2 succeeded; if it still can't be found, check that the npm global install directory (npm prefix -g) is in your PATH, then reopen your terminal |
Your AI assistant doesn't run switchbot commands |
Make sure you added the instructions to the instructions file as described in step 5, or say "use switchbot mindclip commands" directly when you ask |
| You're told the device ID is missing when listing recordings | Go back to step 4 to look up the device ID, then add it to the instructions file from step 5, or add --device to the command |
| The latest recording doesn't show up | Run switchbot devices status <device-id> and check hasUntransferredFiles and uploadStatus. Recordings are only available after they're uploaded to the cloud, and uploads happen while charging |
| The transcript or summary is empty | A transcribeStatus of 1 means transcription is still in progress, so try again later; 3/4/5 means it failed |
| The transcript looks like a string of escaped JSON | This is expected. transcribeResult is itself a JSON string, so you need to parse it again |
The weekly parameter returns an error |
Weeks use the ISO week format YYYY-Www, for example 2026-W42; only some years have W53 |
| The daily recap is empty | There were no recordings that day, or the recap hasn't been generated yet. You can subscribe to the dailySummary event |
| 401 / authentication failed | Repeat step 3, then run switchbot doctor to self-check |
| 429 / too many requests | The API is limited to 10,000 calls per day. Run switchbot quota status to check your usage |
Upgrading and uninstalling
Upgrade:
npm install -g @switchbot/openapi-cli@latest
Uninstall:
npm uninstall -g @switchbot/openapi-cli
rm -rf ~/.switchbot
If you added the AI MindClip instructions to the instructions file in step 5, remove them as well.
Reference
Command parameters
All switchbot mindclip commands are read-only and never modify or delete your recordings.
recordings
| Parameter | Required | Description |
|---|---|---|
--device <id> |
✓ | Device ID |
--page <n> |
✓ | Page number, ≥ 1 |
--size <n> |
✓ | Items per page, 1–100 |
--start <ms> / --end <ms> |
Time range (millisecond timestamps) | |
--folder <n> |
Folder ID |
recording / transcript / summary
| Command | What it does |
|---|---|
recording <recording-id> |
Metadata for a single recording |
transcript <recording-id> |
Transcription status and transcript |
summary <recording-id> |
AI summary, template results, atmosphere analysis, to-dos, speakers |
todos
| Parameter | Required | Description |
|---|---|---|
--completed <n> |
✓ | Completion status filter, 0–2 |
--page <n> |
✓ | Page number, ≥ 1 |
--size <n> |
✓ | Items per page, 1–100 |
--device <id> / --file <id> |
Filter by device or recording | |
--start <ms> / --end <ms> |
Time range (millisecond timestamps) | |
--category <n> |
Category filter, 0–5 |
daily / weekly / urgent-todos
| Command | Required parameters | What it does |
|---|---|---|
daily |
--date YYYY-MM-DD |
The daily recap for a given day |
weekly |
--week YYYY-Www |
The weekly summary for a given week (ISO week, e.g. 2026-W42) |
urgent-todos |
--date YYYY-MM-DD |
Urgent to-dos for a given day |
Dates and weeks aren't inferred automatically — you must pass them explicitly.
Data fields
Recordings
| Field | Description |
|---|---|
id |
Recording ID |
displayName |
Recording name |
recordingLen |
Recording duration |
fileSize |
File size |
deviceID |
Device ID |
transcribeStatus |
Transcription status (see the table below) |
createdTime |
Creation time (millisecond timestamp) |
folderID / emoji / isSystem |
Containing folder, icon, whether it's a system folder |
Transcription status
transcribeStatus |
Meaning |
|---|---|
1 |
Transcribing |
2 |
Succeeded |
3 |
Failed |
4 |
Timed out |
5 |
Speech-to-text failed |
Transcript
| Field | Description |
|---|---|
transcribeStatus |
Transcription status |
transcribeResult |
Transcription result. This is a JSON string containing a segments array (each segment includes text, speaker, start, end) |
speakers[] |
Speaker number speaker and name speakerName |
AI summary
| Field | Description |
|---|---|
transcribeResult |
Transcript text |
aiSummaryResult |
AI summary |
aiTemplateResult |
AI template results (meeting notes and more, in Markdown) |
aiAtmoResult |
AI atmosphere analysis |
aiTodoList[] |
Extracted to-dos: title, reminderTime, isCompleted, category |
speakers[] |
Speakers: name, display color, recognition confidence speakerConfidence |
To-dos
Fields: title, reminderTime (reminder time, in milliseconds), isCompleted, createdTime, fileID (source recording), deviceID, category.
Daily recap / weekly summary / urgent to-dos
| Command | Key fields |
|---|---|
daily |
list[].summaryDate, summaryContent, timezone, locations[] (time, latitude and longitude, place name, linked recordings) |
weekly |
summaryWeek, summaryContent, timezone |
urgent-todos |
summaryDate, todos[] (title, reminderTime, rank priority, fileID, isCompleted) |
Daily recaps include location information (latitude, longitude, and place names). Keep this in mind before you hand the data to a third-party AI or share it.
Device status
| Field | Description |
|---|---|
battery |
Battery level 0–100 |
chargingStatus |
0 not charging, 1 charging |
recordingStatus |
0 not recording, 1 recording |
uploadStatus |
0 not uploading, 1 uploading |
hasUntransferredFiles |
Whether the device still has files that haven't been transferred |
AI MindClip doesn't support control commands, so you can't remotely start or stop recording through the API.