cherri

Files (45)

• SKILL.md
• action-definitions.md · references/
• best-practices.md · references/
• comments.md · references/
• control-flow.md · references/
• copy-paste.md · references/
• definitions.md · references/
• enums.md · references/
• functions.md · references/
• import-actions.md · references/
• import-questions.md · references/
• includes.md · references/
• menus.md · references/
• operators.md · references/
• package-manager.md · references/
• raw-actions.md · references/
• references.md · references/
• a11y.md · references/standard/
• basic.md · references/standard/
• builtin.md · references/standard/
• calendar.md · references/standard/
• contacts.md · references/standard/
• crypto.md · references/standard/
• device.md · references/standard/
• documents.md · references/standard/
• images.md · references/standard/
• intelligence.md · references/standard/
• location.md · references/standard/
• macos-only.md · references/standard/
• math.md · references/standard/
• media.md · references/standard/
• music.md · references/standard/
• network.md · references/standard/
• pdf.md · references/standard/
• photos.md · references/standard/
• settings.md · references/standard/
• sharing.md · references/standard/
• shortcuts.md · references/standard/
• stdlib.md · references/standard/
• text.md · references/standard/
• translation.md · references/standard/
• web.md · references/standard/
• types.md · references/
• variables-constants-globals.md · references/
• vcards.md · references/

SKILL.md (first lines)

# Cherri

> **Last updated: 2026-08-11** (docs synced from cherrilang.org source repo). If today is more than 3 months past this date, offer to run [Self-Update](#self-update).

[Cherri](https://cherrilang.org) is a language that compiles to `.shortcut` files for the Apple Shortcuts app. If the shortcuts live in a dedicated repo, see that repo's AGENTS.md for repo-specific mechanics (secrets/constants pipeline, folder layout).

## Toolchain

With the `cherri` binary installed, it is self-documenting - use these before reaching for the references:

```bash
cherri file.cherri --skip-sign     # compile (unsigned; signing needs contact with Apple servers)
cherri --action=showNotification   # full docs for one action (any action, incl. required include)
cherri --glyph=music               # validate/suggest icon glyph names
cherri --docs=<query>              # search the documentation
cherri file.cherri -d              # also emit the .plist - grep it to verify compiled actions
```

A shortcuts repo can wrap compilation (placeholder substitution for constants and secrets, plist post-patches); follow its AGENTS.md. When placeholders resolve from a secret store your shell cannot read, compile-validate a scratch copy with the placeholders replaced by dummies:

```bash
sed -E -e 's|<<(secret|constant):([A-Za-z_0-9]+)>>|DUMMY_\2|g' file.cherri > /tmp/check.cherri && cherri /tmp/check.cherri --skip-sign
```

## Syntax cheat sheet

```cherri
#define name My Shortcut          // metadata directives first
#define color blue
#define glyph shazam              // must be a valid glyph - verify with cherri --glyph=
#define from sharesheet           // accepts share-sheet input (read via ShortcutInput global)
#include 'actions/web'            // most actions need an include; the compile error names it

@mutable = "value"                // variables; interpolate with "{mutable}"
const Fixed = getName(@x)         // immutable; fewer compiled actions
@declared: text                   // type-only declaration (assign later, e.g. in if branches)

if @textVar == "yes" && @other contains "x" { ... } else { ... }
repeat i for 20 { ... }           // count can be a variable
for item in @list { ... }
```

## Gotchas (hard-won - read before writing code)

1. **HTTP responses are not dictionaries.** `jsonRequest`/`formRequest`/`downloadURL` return "Contents of URL". `@resp['key']` compiles to an inline aggrandizement that silently reads NOTHING at runtime. Always coerce: `@d = getDictionary(@resp)` then `getValue(@d, "key")`. Walk nested keys one level at a time (no dotted paths), and coerce list items too: `getDictionary(getFirstItem(...))`. Verify with `-d`: the .plist should show `detect.dictionary` + `getvalueforkey`; `WFPropertyVariableAggrandizement` on a response means it's broken.
2. **Conditions require `@` on variables** (`if @var == "x"`), despite doc examples showing bare names. The compiler errors otherwise.
3. **`containsText()` hardcodes a `^` anchor** onto its pattern - prepend `.*` for a real contains match. The `contains` *conditional operator* has no such quirk.
4. **Missing include?** The compile error names the exact `#include` to add. Core actions (`showNotification`, `alert`, `prompt`, …) need none.
5. **`show()` blocks the flow with a modal; `showNotification(body, ?title)` is async** - prefer notifications for fire-and-forget status.
6. **JSON `null` reads back as empty text** - `"{value}"` of a null is `""`, testable with `if !@var`.
7. `nothing()` after unused action outputs frees runtime memory; statement blocks add it automatically at their end.
8. **File-typed form values are inexpressible in cherri v2.3** - dictionary items only support text/number/bool/array/dict, so a multipart file upload (`formRequest` with a file field) compiles to an empty form value that silently uploads nothing. The working structure is `WFItemType: 5` + `WFTokenAttachmentParameterState`; post-patch the compiled plist into that shape in your compile pipeline.
9. **`embedFile()` resolves paths relative to cherri's CWD, not the source file** - run the compiler from the `.cherri` file's directory or asset references like `assets/foo.mp3` fail when compiling from the repo root. (`base64File` from the docs doesn't exist in cherri v2.3; the action is `embedFile`.)

## References (complete cherrilang.org/language docs, local)

Read the file matching the problem, per the table below.

| Topic | File |
|---|---|
| Variables, constants, globals (`ShortcutInput`, …) | `references/variables-constants-globals.md` |
| If/else, repeat, for, menus | `references/control-flow.md`, `references/menus.md` |
| Types, enums, operators, functions | `references/types.md`, `references/enums.md`, `references/operators.md`, `references/functions.md` |
| Metadata `#define`s (name, color, glyph, from…) | `references/definitions.md` |
| Includes & the package manager | `references/includes.md`, `references/package-manager.md` |
| Custom action definitions | `references/action-definitions.md` |
| Raw actions (use any Shortcuts action Cherri lacks) | `references/raw-actions.md` |
| Copy-paste blocks, import questions/actions, vcards | `references/copy-paste.md`, `references/import-questions.md`, `references/import-actions.md`, `references/vcards.md` |
| Best practices (performance, memory) | `references/best-practices.md` |
| Standard actions by category (web, media, text, device, scripting-ish basics, macOS-only, …) | `references/standard/*.md` - e.g. `web.md`, `media.md`, `text.md`, `basic.md`, `builtin.md`, `stdlib.md` |

## Self-Update

1. Re-download the docs: list `language/` and `language/standard/` in `electrikmilk/cherrilang.org` (`gh api repos/electrikmilk/cherrilang.org/contents/language`), fetch each `.md` from `https://raw.githubusercontent.com/electrikmilk/cherrilang.org/main/language/...`, strip the Jekyll frontmatter/TOC, and write them into `references/` (same filenames, `standard/` subdir preserved).
2. Skim the [changelog/releases](https://github.com/electrikmilk/cherri/releases) since the Last-updated date; fold breaking syntax changes into the cheat sheet and gotchas.
3. Bump the Last-updated date.

From alexjmiller5/agent-config-public, MIT.

More from alexjmiller5/agent-config-public