An Action is one .js file and that file is the whole artifact, so it can
be AirDropped, saved to Files, attached to a message, committed to a gist or
pasted into a chat.
// ==CAIO Action==
// @name Uppercase
// @description Uppercases the current text
// @category Text
// @icon textformat
// @color systemBlue
// @needs-app false
// @version 1
// ==/CAIO Action==
module.exports = async function (ctx) {
const value = ((await Pasteboard.getString()) || "").toUpperCase()
await ctx.update(value)
return value
}The header is optional; a plain .js file also imports (its filename becomes
the name). Metadata values are single-line.
| Key | Meaning |
|---|---|
@name |
Display name (max 120 characters). |
@description |
One-line description shown in the Actions UI (max 500 characters). |
@category |
Folder name; defaults to General. |
@icon |
SF Symbol name; defaults to bolt. |
@color |
Icon background color; defaults to systemBlue. |
@needs-app |
true when the Action needs CAIO's main app (UI/prompts/share). |
@version |
Integer; used to refresh built-ins, defaults to 1. |
Actions run in the same Scripting runtime as CAIO, so their context holds only what the runtime cannot provide: writing the result back through CAIO, and reading CAIO's clip history. Everything else — the clipboard, dialogs, previews, storage, the network — is Scripting's own API.
| Member | Description |
|---|---|
ctx.env |
app, clipboard, editor, keyboard, widget or intent. |
ctx.clip |
The clip the Action was triggered from, or null. |
ctx.text |
The text to start from; "" when there is none. |
ctx.update(value) |
Updates the current clip, inserts into the keyboard/editor, or sets the clipboard. |
ctx.clips(collection?) |
Up to 200 clips from clips, favorite or trash. |
ctx.clip and ctx.text describe what the user acted on, which is not the
same thing as the pasteboard. Run an Action from a clip's long-press menu and
ctx.clip is that clip — its id, kind, tag, imagePath, timestamps and
text — even though the pasteboard may hold something else entirely. From the
clip editor, ctx.text is the unsaved buffer you are looking at, so an Action
never has to read stale storage.
module.exports = async function (ctx) {
// Retag the clip this Action was run on, whatever the pasteboard says.
const kind = ctx.clip ? ctx.clip.kind : "no clip"
await ctx.update(`[${kind}] ${ctx.text.toUpperCase()}`)
return ctx.text.length
}Both are null / "" where there is no trigger: the Actions tab, the keyboard,
a widget or a Shortcut. Write Actions so they fall back to
Pasteboard.getString() rather than assuming a clip exists.
Inside the same source, use the native APIs directly instead of a wrapper:
| Need | Use |
|---|---|
| Read / set text | Pasteboard.getString(), Pasteboard.setString(value) |
| Keyboard text | CustomKeyboard.selectedText, allText, insertText() |
| Ask the user | Dialog.alert, Dialog.confirm, Dialog.prompt, Dialog.actionSheet |
| Show a result | QuickLook.previewText, ShareSheet.present |
| Remember something | Storage.get, Storage.set, Storage.remove |
ctx.update(value) is the one writer that routes by host: it replaces the clip
that launched the Action, inserts into the keyboard or editor, or sets the
pasteboard. To set the clipboard as well, call Pasteboard.setString next to
it.
- Export: use Export in the action menu (or drag a card out from All Actions
/ search) to share the single
.caio.jsfile (AirDrop, Files, Messages, …). Inside a category, long-press drag is reserved for reordering. Cards use Scripting 3.2.2's native drag reordering: a data-backedForEachwithreorderabledirectly inside areorderContainer, withmoveupdating the Observable synchronously throughsetValue. Every card carries its Action id as the key of the view it actually renders. The column count adapts to the available width, and the order is stored locally on the device. - Import: Actions tab → Import → choose a
.js/.caio.jsfile. CAIO shows the parsed name/description and a trust warning before installing. - Edit: tap a card to edit its code. The context menu separates Action Info (read-only metadata), Edit Info (the file-header comments in a code editor), Edit Code (the executable source) and Edit Full File (header and source together). Pinned state and ordering stay local to the device and are not written into the file.
- Delete: every Action, including a built-in, can be removed from the bottom of the context menu or the Action Info sheet. Built-in deletions are remembered locally, so the built-in seeder will not recreate them.
Actions are unsandboxed JavaScript executed in the same script context as CAIO. They can read the clipboard, files and network just like CAIO itself. Only import Actions you trust; the import dialog is the only gate. Settings → “Enable Scripts” is a global kill switch: when off, no Action runs from the app, keyboard, widget or Shortcuts.
Built-ins ship as flat files in CAIO/actions/ and are rewritten when CAIO
updates them. They are normal Actions; export or copy one as a starting point.