cherri

name	cherri
description	Write, edit, compile, and debug Cherri (.cherri) source files, a language that compiles to Apple Shortcuts for iOS/macOS. Use for .cherri files, the cherri compiler, and building or signing Apple Shortcuts automations.

When to use

Use this skill when creating or modifying .cherri files or building Apple Shortcuts automations for iOS/macOS.

Cherri is a compiled language that produces signed .shortcut files for iOS/macOS. Source files use the .cherri extension and compile via the cherri CLI.

This skill's content is verified against Cherri v2.3.0.

Quick orientation

Cherri looks like a C-style scripting language with these key differences:

• Variables use @ prefix for declaration: @name = "value"
• Constants (magic variables) use const: const x = action()
• String interpolation uses {varName} inside double-quoted strings (no $)
• Includes use #include 'actions/web' for action categories
• Definitions use #define for shortcut metadata (color, glyph, inputs)
• Import questions use #question for first-run setup prompts

Invoking the compiler

ALWAYS run each cherri command as its own standalone Bash call with no shell additions. NEVER append 2>&1, ; echo ..., &&, or any other shell constructs. Write source to a file first, then compile:

cherri /path/to/file.cherri --skip-sign

Compilation success = exit code 0 AND a .shortcut file written. Compiles are not necessarily silent on success: warnings (e.g. dead-code after stop()/output()) print to stdout while still exiting 0. Errors print to stdout and exit 1 (compiler panics exit 2). --action lookups print the requested doc block but exit 1 even when the action is found; judge lookup success by the output, not the exit code. --docs lookups exit 0.

ALWAYS pass --no-ansi, including when compiling: it produces plain text instead of ANSI-escaped output, with no effect on exit codes or compilation results.

To decompile an existing Shortcut back into Cherri source, use cherri --import=<icloud-link-or-file> ([BETA]). Local .shortcut files must be unsigned; signed files need an iCloud link instead. Review and test-compile the generated source, since the feature is beta.

Critical rules

• NEVER use ${} for string interpolation. Cherri uses {varName}.
• NEVER omit #include statements. Actions outside basic require explicit includes.
• NEVER use @variable when the value won't change. Use const for smaller shortcuts.
• NEVER use bracket syntax (dict['key']) on constants — use getValue(dict, "key") instead.
• NEVER nest action calls as arguments — store results in variables first.
• ALWAYS use const over @var when the value is assigned once and never mutated.
• ALWAYS add nothing() after actions whose output you won't use.
• ALWAYS use text() to store import question values before using them in string interpolation.

Variable referencing

Variables are declared with @ prefix. When referencing them later, the @ prefix is required — a bare variable name is a compile error ("Unknown reference '...'. Variable references must be prepended with @."). Constants declared with const use the bare name instead:

@myVar = "hello"
const myConst = "hello"

// Variables require @prefix:
alert(@myVar, "Title")
show("{@myVar}")

// Constants always use bare name:
alert(myConst, "Title")
show("{myConst}")

Reference files

• references/language-fundamentals.md — Variables, constants, types, control flow, functions, string interpolation, globals
• references/actions-and-includes.md — Include system, CLI action discovery, custom action definitions, raw actions, stdlib, copy/paste macros
• references/shortcut-metadata.md — #define directives, import questions, input/output types, share sheet config
• references/common-patterns.md — Reusable code patterns: HTTP, menus, dictionaries, dates, share sheet, lists
• references/patterns-and-practices.md — Best practices, efficiency tips, compilation, CLI hygiene, anti-patterns
• references/compiler-quirks.md — Known compiler bugs and workarounds (read when debugging unexpected compile errors)
• references/share-sheet-shortcut.md — Complete pattern for building a share sheet bookmark shortcut with API integration

Looking up actions

ALWAYS use the cherri CLI to look up action signatures — it reflects the exact compiler version installed and is the source of truth.

# Look up a specific action
cherri --action=jsonRequest --no-ansi

# Browse all actions in a category
cherri --docs=web --no-ansi

# Search for a glyph
cherri --glyph=bookmark --no-ansi

Categories: basic, web, text, documents, calendar, contacts, crypto, sharing, shortcuts, intelligence, translation, pdf, math, mac, images, photos, music, media, network, device, settings, location, a11y, dropbox.

The scripting category was removed in v2.3.0. #include 'actions/scripting' now fails to compile ("Undefined actions include 'scripting'"). Most of its actions (e.g. getValue, getFirstItem) moved to basic and need no include; others moved elsewhere (e.g. runShellScript now requires #include 'actions/mac').

Official language documentation

For language syntax and features not covered by this skill, consult https://cherrilang.org/language/. The site tracks the latest compiler release, which can be ahead of or behind the installed version — check the installed version with cherri -v and verify anything taken from the site with a test compile before relying on it.