Actions

Source, step, sink

Every action is a one-step pipeline: a source fills it, a step does the work, a sink takes the result.

• Source — placeholders in the action's template: what you typed ({query}), the text selected in the app you're in ({selection}), the clipboard ({clipboard}), text read off a screen region ({screenshot}), and the clock ({date}, {time}, {now:…}).
• Step — the action's type: open a URL, ask an AI, run a shell command, fill a text template, run an Apple Shortcut, translate, start a timer, tidy a folder, or open one of Arci's tools.
• Sink — the action's output: show the result in Arci's panel, copy it, paste it into your app, or save it as a note.

You run an action by typing in Arci's bar and pressing ⇥ to pick it, by typing its keyword, or with its own global hotkey.

Where actions live

All your actions are in one file:

~/Library/Application Support/Arci/actions.json

• First run. Arci writes its default actions there (they're listed under the defaults). From then on the file is yours.
• Edit it anywhere. Settings → Actions → Edit JSON opens it in your editor. Arci watches the folder and reloads the moment you save — there's no restart and no import step.
• Settings writes the same file. Turning an action off in Settings writes "enabled": false into it; editing a field there saves it back. Hand edits and Settings edits never fight.
• A broken file is never overwritten. If the file isn't valid JSON, Arci keeps running its built-in defaults, Settings says the file has a syntax error, and nothing is saved over it until you fix it. Editors that save in two steps are fine: Arci waits a moment and reads again before deciding a file is broken. Delete the file and Arci writes the defaults again.
• An action Arci can't run is skipped. An unknown type, or a missing required field, leaves that one action out of the panel; the rest of the file still works.
• New built-in actions arrive once. When an update ships a new default action, Arci adds it to the end of your file one time, keeping the previous file beside it as actions.json.bak. Delete it and it stays deleted.

The document

The file is one object with one key, actions: a list of actions in the order you want them. A menu groups more actions as its children.

{
  "actions": [
    {
      "id": "youtube",
      "title": "Search YouTube",
      "type": "url",
      "url": "https://www.youtube.com/results?search_query={query}",
      "keyword": "yt"
    },
    {
      "id": "write",
      "title": "Writing",
      "type": "menu",
      "children": [
        {
          "id": "write.shorter",
          "title": "Make Shorter",
          "type": "ai",
          "prompt": "Rewrite this in half the words, keeping its meaning:\n\n{query}"
        },
        {
          "id": "write.formal",
          "title": "Make Formal",
          "type": "ai",
          "prompt": "Rewrite this in a formal, polite tone:\n\n{query}"
        }
      ]
    }
  ]
}

Order matters. The panel lists actions in this order, with one exception: searches — url actions that use {query} — are shown together under Search, where the first of them is. The file stays as you wrote it. When what you typed matches nothing and you press ↩, Arci runs the first enabled search — out of the box, Search Google. Move another search above it to make that the fallback.

A document holds at most 200 actions, counting sub-actions, and menus nest at most 3 levels: action › sub-action › sub-sub-action.

Common fields

These fields work on every action, whatever its type. The fields each type adds are under Types.

Fields a type doesn't use are a mistake, not a no-op: a file that names a field Arci doesn't know, or gives output to a url action, fails the checks Arci and its tools run. Keep each action to the fields listed for its type.

Placeholders

Placeholders are the sources. Put them in an action's template — its url, prompt, command, text or input — and Arci fills them when the action runs.

The clock placeholders use your Mac's time zone; {date}, {time} and {now} always use the fixed formats above, whatever your language or calendar.

How each type fills them

A value is made safe for where it lands, so you never quote or encode placeholders yourself:

Arci fills a template in one pass: text that comes in through a placeholder is never scanned again, so selected text that happens to contain {clipboard} stays literal. A brace that isn't one of the placeholders above is left alone.

Outputs

output is the sink. It applies to the types that make a result — ai, shell, text, shortcut and translate — and is one of:

label files a note under one folder inside your notes folder, like "label": "Reading list". It's a folder name: up to 40 characters, no / or :, not starting with a dot, no spaces at either end. It may use the clock placeholders — "label": "Journal {now:yyyy-MM}" starts a new folder each month. label only goes with "output": "note".

{
  "actions": [
    {
      "id": "read-later",
      "title": "Read Later",
      "type": "text",
      "text": "{query}",
      "output": "note",
      "label": "Reading list"
    }
  ]
}

Keywords

A keyword is one word you type before your text to run the action directly. With "keyword": "yt", typing yt lofi beats and pressing ↩ searches YouTube for "lofi beats".

• One word, no spaces, up to 24 characters. Matching ignores case.
• The keyword alone, then ↩, pins the action: the bar shows its name and whatever you type next is its input.
• An action that doesn't use {query} runs as soon as you press ↩ on its keyword. A menu's keyword opens its sub-actions.
• Your keyword beats Arci's own words for that first word — clip (clipboard history) and the timer words (timer, alarm, remind, pomodoro, stopwatch) — and the calculator.
• Two actions with the same keyword: the first one in the file wins, and Settings → Actions flags the second. It's never an error in the file.

Hotkeys

A hotkey runs the action from any app, without opening Arci first. It's written as modifiers and one key joined by +:

"ctrl+opt+g"     "cmd+shift+k"     "ctrl+cmd+space"     "f5"

• Modifiers: ctrl (or control), opt (or option, alt), shift, cmd (or command), each at most once. Arci writes them in macOS order — ⌃⌥⇧⌘ — whatever order you type.
• The key, last: one character (g, 1, /), a named key — space, return, tab, escape, delete, left, right, up, down — or f1 to f12.
• At least one of ctrl, opt or cmd — or an F-key, which may stand alone.

Arci then refuses, with the reason in Settings → Actions:

• ⌘ with a single character, and ⇧⌘3, ⇧⌘4, ⇧⌘5, ⇧⌘Z — every app's own shortcuts. Add ⌃ or ⌥.
• A combination macOS or another app already holds.
• Arci's own summon shortcut or its Clipboard History shortcut.
• A combination an earlier action in the file already has — the first one wins.

What a hotkey does. An action that needs nothing typed runs at once — fix the selection in the app you're in, copy screen text, start a preset timer. An action that uses {query} opens Arci pinned to it, so you type and press ↩; if Arci is already open with text in the bar, it runs on that. A menu's hotkey opens its sub-actions. The same hotkey again puts Arci away.

Two defaults ship with hotkeys: Copy Screen Text on ⇧⌘8 and Emoji & Symbols on ⌃⌘Space.

Offered by itself

A match is a pattern — a regular expression — for the kind of text an action is made for. When the text you select, paste or type is all of it, the action comes first: the first chip over a selection and the top row in the list — one click, or ↓ ↩; ↩ on its own still does what it always did, so TCP/IP fitting the GitHub pattern still searches the web. Other text never sees it; type its name to use it anyway.

{
  "id": "jira",
  "title": "Open Issue",
  "type": "url",
  "url": "https://yourteam.atlassian.net/browse/{query}",
  "match": "[a-z]+-[0-9]+"
}

• Only for an action that reads {query} — a translate, shortcut or timer action reads it unless its input says otherwise. On any other action it's ignored.
• The whole text has to fit — ARCI-42, not see ARCI-42 — and case doesn't matter. Text over 500 characters is never tried.
• Up to 200 characters. Write [0-9] and [.] rather than backslash escapes: in JSON every backslash has to be doubled.
• Arci ships four: Open on GitHub for owner/repo, Open on npm for @scope/package, Open DOI and Look Up IP. Settings → Actions tags them auto; give your own one in an action's Offer it for field, or ask the Builder: "open a selected Jira key on yourteam.atlassian.net".

Types

One section per type. "Required" means the action is skipped without it.

{
  "actions": [
    {
      "id": "wikipedia",
      "title": "Wikipedia",
      "type": "url",
      "url": "https://en.wikipedia.org/w/index.php?search={query}",
      "keyword": "w"
    }
  ]
}

{
  "actions": [
    {
      "id": "fix-selection",
      "title": "Fix Selection",
      "type": "ai",
      "prompt": "Fix the grammar, spelling and punctuation of the following text. Return only the corrected text, nothing else.\n\n{selection}",
      "output": "paste",
      "hotkey": "ctrl+opt+g"
    }
  ]
}

{
  "actions": [
    {
      "id": "base64",
      "title": "Base64 Encode",
      "type": "shell",
      "command": "printf %s {query} | base64",
      "output": "clipboard"
    }
  ]
}

{
  "actions": [
    {
      "id": "today",
      "title": "Insert Date",
      "type": "text",
      "text": "{now:EEEE, d MMMM yyyy}",
      "output": "paste",
      "keyword": "today"
    }
  ]
}

{
  "actions": [
    {
      "id": "add-to-things",
      "title": "Add to Things",
      "type": "shortcut",
      "shortcut": "Add to Things",
      "input": "{selection}"
    }
  ]
}

{
  "actions": [
    {
      "id": "to-hindi",
      "title": "Hindi In Place",
      "type": "translate",
      "input": "{selection}",
      "to": "hi",
      "output": "paste"
    }
  ]
}

{
  "actions": [
    {
      "id": "tidy-downloads",
      "title": "Tidy Downloads",
      "type": "files",
      "folder": "~/Downloads",
      "organize": "kind"
    }
  ]
}

{
  "actions": [
    {
      "id": "kill",
      "title": "Kill Process",
      "type": "processes",
      "keyword": "kill"
    }
  ]
}

{
  "actions": [
    {
      "id": "pick-color",
      "title": "Pick Color",
      "type": "color",
      "hotkey": "ctrl+opt+c"
    }
  ]
}

{
  "actions": [
    {
      "id": "emoji",
      "title": "Emoji & Symbols",
      "type": "emoji",
      "hotkey": "ctrl+cmd+space"
    }
  ]
}

{
  "actions": [
    {
      "id": "search-files",
      "title": "Search Files",
      "type": "find",
      "hotkey": "ctrl+opt+f"
    }
  ]
}

{
  "actions": [
    {
      "id": "remind-selection",
      "title": "Remind Me",
      "type": "timer",
      "input": "{selection}",
      "hotkey": "ctrl+opt+r"
    }
  ]
}

{
  "actions": [
    {
      "id": "search",
      "title": "Search",
      "type": "menu",
      "keyword": "s",
      "children": [
        { "id": "search.ddg", "title": "DuckDuckGo", "type": "url", "url": "https://duckduckgo.com/?q={query}" },
        { "id": "search.maps", "title": "Apple Maps", "type": "url", "url": "https://maps.apple.com/?q={query}" },
        { "id": "search.github", "title": "GitHub", "type": "url", "url": "https://github.com/search?q={query}" }
      ]
    }
  ]
}

Cookbook

Each recipe is a complete file with one action. To use one, copy the action — the part inside the list — into your own actions list.

Explain what's on the clipboard

{
  "actions": [
    {
      "id": "explain",
      "title": "Explain Clipboard",
      "type": "ai",
      "prompt": "Explain this simply, in a few short paragraphs:\n\n{clipboard}"
    }
  ]
}

Summarize the selection, on this Mac only

{
  "actions": [
    {
      "id": "summary-here",
      "title": "Summarize Here",
      "type": "ai",
      "provider": "apple",
      "prompt": "Summarize the following in three bullet points:\n\n{selection}"
    }
  ]
}

Draft a reply, ready to paste

{
  "actions": [
    {
      "id": "reply",
      "title": "Draft Reply",
      "type": "ai",
      "prompt": "Write a short, friendly reply to this message. Return only the reply.\n\nMessage:\n{selection}\n\nWhat I want to say: {query}",
      "output": "paste"
    }
  ]
}

Translate text on screen

{
  "actions": [
    {
      "id": "screen-translate",
      "title": "Translate Screen",
      "type": "translate",
      "input": "{screenshot}",
      "hotkey": "ctrl+opt+t"
    }
  ]
}

Translate privately

{
  "actions": [
    {
      "id": "translate-here",
      "title": "Translate Here",
      "type": "translate",
      "engine": "device"
    }
  ]
}

Paste a signature

{
  "actions": [
    {
      "id": "signature",
      "title": "Signature",
      "type": "text",
      "text": "Best,\nAsha Rao\nasha@example.com",
      "output": "paste",
      "keyword": "sig"
    }
  ]
}

Keep a journal, a folder a month

{
  "actions": [
    {
      "id": "journal",
      "title": "Journal",
      "type": "text",
      "text": "{time} {query}",
      "output": "note",
      "label": "Journal {now:yyyy-MM}",
      "keyword": "j"
    }
  ]
}

Save a quote from any app

{
  "actions": [
    {
      "id": "keep-quote",
      "title": "Keep Quote",
      "type": "text",
      "text": "{selection}\n\nSaved {date}",
      "output": "note",
      "label": "Quotes",
      "hotkey": "ctrl+opt+q"
    }
  ]
}

Your Mac's address on the network

{
  "actions": [
    {
      "id": "local-ip",
      "title": "Local IP",
      "type": "shell",
      "command": "ipconfig getifaddr en0",
      "output": "clipboard"
    }
  ]
}

Count the words on the clipboard

{
  "actions": [
    {
      "id": "word-count",
      "title": "Word Count",
      "type": "shell",
      "command": "pbpaste | wc -w"
    }
  ]
}

A focus timer on one key

{
  "actions": [
    {
      "id": "focus",
      "title": "Focus 25",
      "type": "timer",
      "input": "25m Focus",
      "hotkey": "ctrl+opt+f"
    }
  ]
}

Remind me in an hour

{
  "actions": [
    {
      "id": "in-an-hour",
      "title": "In An Hour",
      "type": "timer",
      "input": "in 1 hour to {query}",
      "keyword": "later"
    }
  ]
}

Tidy the Desktop

{
  "actions": [
    {
      "id": "tidy-desktop",
      "title": "Tidy Desktop",
      "type": "files",
      "folder": "~/Desktop"
    }
  ]
}

Start an email

{
  "actions": [
    {
      "id": "new-mail",
      "title": "New Email",
      "type": "url",
      "url": "mailto:?subject={query}"
    }
  ]
}

Look up a word

{
  "actions": [
    {
      "id": "define",
      "title": "Define",
      "type": "url",
      "url": "dict://{query}",
      "keyword": "def"
    }
  ]
}

Limits and checks

Arci and its tools check a file against these rules. Hand-written files that follow them behave the same everywhere.

Every text field must be non-empty when present. Leave a field out rather than setting it to "".

The defaults

A fresh install writes this file. It's a good starting point to copy from.

{
  "actions": [
    {
      "id": "google",
      "title": "Search Google",
      "type": "url",
      "url": "https://www.google.com/search?q={query}"
    },
    {
      "id": "ai",
      "title": "Ask AI",
      "type": "menu",
      "children": [
        {
          "id": "ai.ask",
          "title": "Ask",
          "type": "ai",
          "prompt": "{query}"
        },
        {
          "id": "ai.grammar",
          "title": "Fix Grammar",
          "type": "ai",
          "prompt": "Fix the grammar, spelling and punctuation of the following text. Return only the corrected text, nothing else.\n\n{query}"
        },
        {
          "id": "ai.summarize",
          "title": "Summarize",
          "type": "ai",
          "prompt": "Summarize the following concisely:\n\n{query}"
        }
      ]
    },
    {
      "id": "note",
      "title": "Save to Notes",
      "type": "text",
      "text": "{query}",
      "output": "note"
    },
    {
      "id": "translate",
      "title": "Translate",
      "type": "translate"
    },
    {
      "id": "kill-process",
      "title": "Kill Process",
      "type": "processes"
    },
    {
      "id": "pick-color",
      "title": "Pick Color",
      "type": "color"
    },
    {
      "id": "screen-text",
      "title": "Copy Screen Text",
      "type": "text",
      "text": "{screenshot}",
      "output": "clipboard",
      "hotkey": "shift+cmd+8"
    },
    {
      "id": "emoji",
      "title": "Emoji & Symbols",
      "type": "emoji",
      "hotkey": "ctrl+cmd+space"
    },
    {
      "id": "search-files",
      "title": "Search Files",
      "type": "find"
    },
    {
      "id": "app-store",
      "title": "Search App Store",
      "type": "url",
      "url": "macappstore://apps.apple.com/search?term={query}"
    }
  ]
}

Writing actions with your own AI

This whole reference is plain text at arci.prayukta.com/llms.txt. Paste it into the AI you use, describe the action you want, and paste the reply into actions.json. Read what it wrote before you save — especially a shell command.

Or let Arci write it: in Settings → Actions, describe what you want and Arci Builder builds it, shows you the changes, and saves nothing until you apply them — 20 builds a month free, unlimited with Arci Pro (coming soon). Turn on Share my builds below the Build field to help improve it; the privacy policy says what's kept.