Every tool
These are the tools your AI app can call once Cloud Butler is connected. You don't call them yourself: you ask in plain words and your agent picks the right one.
How to read this page
- Plan: Free tools only read. Pro tools act, and need Cloud Butler Pro once plan checks are on (during early access every tool works on any account). See Free and Pro.
- Effect: Reads changes nothing. Changes adds or edits something without losing anything. Replaces overwrites existing details. Deletes removes something or takes access away. Sends and Runs reach outside your account and can't be undone. Cloud Butler tells your AI app each tool's effect, so the app knows which ones to ask you about. See how tools are labelled.
- Permission: the tick box on the Cloud Butler sign-in page that the tool needs. If you unticked it, the tool tells your agent that this connection isn't allowed to do that.
No tool matches that search. Try a simpler word like "mail" or "event".
Mail, Calendar and Contacts (always on, 18 tools)
These work from the cloud as soon as you connect, with your app-specific password.
Calendar
Your iCloud calendars, through CalDAV. Always on.
| Tool | What it does | Plan | Effect | Permission it needs |
|---|---|---|---|---|
calendar_list_calendars | Lists your calendars with their names and colours, and which ones hold events or tasks. | Free | Reads | Read your calendars |
calendar_list_events | Lists events in a time window (this week if you don't say), with repeating events expanded. Can filter by calendar or by words in the title, place or notes. Shows a week view in apps that support it. | Free | Reads | Read your calendars |
calendar_create_event | Adds an event to one of your calendars, with a title, start and end, place, notes and link. All-day events too. | Pro | Changes | Create, change and delete calendar events |
calendar_update_event | Changes an event's time, title, place, notes or link; fields you don't mention stay as they are. For a repeating event it changes the whole series. | Pro | Replaces | Create, change and delete calendar events |
calendar_delete_event | Deletes an event for good (the whole series if it repeats). Your agent is told to confirm with you first. | Pro | Deletes | Create, change and delete calendar events |
Contacts
Your iCloud contacts, through CardDAV. Always on.
| Tool | What it does | Plan | Effect | Permission it needs |
|---|---|---|---|---|
contacts_search | Finds contacts by name, email, company, note or phone digits (up to 500 at a time). Shows contact cards in apps that support it. | Free | Reads | Read your contacts |
contacts_get | Gets one contact's full details. | Free | Reads | Read your contacts |
contacts_create | Adds a new contact: name, company, job title, emails, phone numbers, birthday, note and link. | Pro | Changes | Create, change and delete contacts |
contacts_update | Updates fields on a contact. Fields you don't mention, such as the photo, addresses and groups, are kept. A new list of emails or phone numbers replaces the old list. | Pro | Replaces | Create, change and delete contacts |
contacts_delete | Deletes a contact for good. Your agent is told to confirm with you first. | Pro | Deletes | Create, change and delete contacts |
Your iCloud Mail, through IMAP and SMTP. Always on.
| Tool | What it does | Plan | Effect | Permission it needs |
|---|---|---|---|---|
mail_list_mailboxes | Lists your mail folders with message and unread counts. | Free | Reads | Read your mail |
mail_search | Searches a folder, newest first, by sender, recipient, subject, words, dates, unread or flagged. Shows an inbox view in apps that support it. | Free | Reads | Read your mail |
mail_read | Opens one message: headers, text (HTML is turned into text) and the names of attachments. It leaves the message unread unless your agent asks to mark it read, which is the only change it can make. The message text is labelled as untrusted content. | Free | Reads (can mark read) | Read your mail |
mail_send | Sends mail from your iCloud address, as a new message or a threaded reply, with Cc, Bcc and up to 20 attachments (10 MB in total) from the chat, from iCloud Drive or from a public link. A copy goes to Sent. Your agent is told to show you the final draft and get your OK first. Once sent, mail can't be unsent. | Pro | Sends | Send mail as you |
mail_move | Moves messages to another folder, such as Archive. | Pro | Changes | Move, flag and delete mail |
mail_set_flags | Marks messages read or unread, flagged or unflagged. | Pro | Changes | Move, flag and delete mail |
mail_delete | Moves messages to Trash, or deletes them for good if they are already in Trash. Your agent is told to confirm with you first. | Pro | Deletes | Move, flag and delete mail |
Connection
| Tool | What it does | Plan | Effect | Permission it needs |
|---|---|---|---|---|
icloud_get_capabilities | Says which Apple account is connected, which services Cloud Butler can and can't reach, and why. Agents use it before saying something isn't possible. | Free | Reads | None (always allowed) |
Optional iCloud web services (off on the public service, 14 tools)
The public Cloud Butler service does not offer these tools, and your agent won't see them. Apple has no standard protocol for Drive, Reminders, Notes, Photos or Find My, so these tools would need your Apple ID password and a two-factor code to open a web session like icloud.com, and Apple can change that web access without notice. Cloud Butler doesn't ask for your Apple ID password. The Cloud Butler app will bring Drive, Reminders, Notes and Photos to your agent through your device's own iCloud instead. They are listed here because self-hosted operators can switch them on.
iCloud Drive
| Tool | What it does | Plan | Effect | Permission it needs |
|---|---|---|---|---|
drive_list | Lists the files and folders in a folder, by folder or by path such as Documents/Taxes. | Pro | Reads | Read iCloud Drive files |
drive_read | Opens a file up to 8 MB: text as text, images as images, other files (PDF, Office) as an attached file. | Pro | Reads | Read iCloud Drive files |
drive_download_url | Gets a short-lived download link for a file. Anyone holding the link can download the file until it expires. | Pro | Reads | Read iCloud Drive files |
drive_upload | Saves a new file (up to 8 MB) into a folder. If the name is taken, iCloud keeps both. | Pro | Changes | Upload, rename and delete iCloud Drive files |
drive_create_folder | Creates a folder. | Pro | Changes | Upload, rename and delete iCloud Drive files |
drive_rename | Renames a file or folder. | Pro | Changes | Upload, rename and delete iCloud Drive files |
drive_trash | Moves a file or folder to Recently Deleted, where you can restore it for 30 days. | Pro | Deletes | Upload, rename and delete iCloud Drive files |
Reminders
| Tool | What it does | Plan | Effect | Permission it needs |
|---|---|---|---|---|
reminders_list | Lists your reminders across all lists. | Pro | Reads | Read and change reminders |
reminders_create | Adds a reminder, with an optional list and due date. | Pro | Changes | Read and change reminders |
reminders_complete | Marks a reminder as done. | Pro | Changes | Read and change reminders |
Find My
| Tool | What it does | Plan | Effect | Permission it needs |
|---|---|---|---|---|
findmy_list_devices | Lists your devices in Find My and their last known locations. | Pro | Reads | See your devices' locations and play a sound |
findmy_play_sound | Plays a sound on one of your devices to help you find it. | Pro | Changes | See your devices' locations and play a sound |
Notes and Photos
| Tool | What it does | Plan | Effect | Permission it needs |
|---|---|---|---|---|
notes_list | Lists your Notes folders. | Pro | Reads | Read notes |
photos_list_recent | Lists your most recent photos (up to 100). | Pro | Reads | See recent photos |
With the Cloud Butler app (11 tools)
Home and Shortcuts live only on your own devices, so these tools work through the Cloud Butler app on your paired iPhone, iPad or Mac. The server side is live; the app is in development, so until you pair a device these tools answer that no device is paired. How it works: devices and the Cloud Butler app.
Pairing and devices
| Tool | What it does | Plan | Effect | Permission it needs |
|---|---|---|---|---|
device_pair_start | Makes a one-time pairing code, valid 10 minutes, to enter in the Cloud Butler app. | Pro | Changes | Use your paired Apple devices |
device_list_paired | Lists your paired devices, which are online now, which one is the home hub and what each can do. | Pro | Reads | Use your paired Apple devices |
device_set_hub | Picks the always-on home hub that runs Home actions (best: a Mac or iPad that stays at home). | Pro | Changes | Use your paired Apple devices |
device_remove | Unpairs a device so it can't receive actions any more. Your agent is told to confirm with you first. | Pro | Deletes | Use your paired Apple devices |
device_get_job_result | Gets the answer for a device action that was still running or waiting for your approval. | Pro | Reads | Use your paired Apple devices |
device_list_activity | Shows recent actions sent to your devices (last 7 days), which device ran each and the outcome. | Pro | Reads | Use your paired Apple devices |
Home
| Tool | What it does | Plan | Effect | Permission it needs |
|---|---|---|---|---|
home_list | Reads your Home: homes, rooms, accessories and their current state, and scenes. | Pro | Reads | Use your paired Apple devices |
home_set | Changes one accessory, such as lights on, brightness or the thermostat to 70°. Locks, garage doors and security systems always wait for your tap on your device. | Pro | Changes | Use your paired Apple devices |
home_run_scene | Runs a Home scene such as Good Night. You approve every scene run on your device, because a scene can unlock a door. | Pro | Changes | Use your paired Apple devices |
Shortcuts
| Tool | What it does | Plan | Effect | Permission it needs |
|---|---|---|---|---|
shortcut_list | Lists the Shortcuts the Cloud Butler app may run (on a Mac all of them; on iPhone and iPad the ones you shared with the app). | Pro | Reads | Use your paired Apple devices |
shortcut_run | Runs one of your Shortcuts by name, with optional text input. You approve each run on your device, or choose to always allow that one shortcut. A shortcut can do anything Shortcuts can, including send messages. | Pro | Runs | Use your paired Apple devices |
Not available
- Health, Keychain and passwords: Apple keeps these on your devices with no access for outside apps. Cloud Butler can't read your health data or your passwords, and never will.
- Reading your Messages: not available. Apple gives outside apps no way to read your message history.
- Payments and money: Cloud Butler has no tool that pays, transfers or buys anything.
- Mac control (Apple Scripting), Safari automation, Messages on the Mac and Siri: planned for Cloud Butler for Mac and the Cloud Butler apps. They'll be listed here when they ship.