Getting Started with Cherri

This guide will walk you through installing Cherri, writing your first Shortcut, and running it on your Apple device.

Table of contents

  1. Prerequisites
  2. Installation
    1. macOS (Recommended)
    2. Linux / Windows
    3. Alternative: Try the Web Playground
  3. Your First Shortcut
    1. Step 1: Create a Cherri File
    2. Step 2: Compile the Shortcut
    3. Step 3: Transfer to Your Device
      1. Option A: AirDrop (macOS only)
      2. Option B: iCloud Drive
      3. Option C: Email / Messages
    4. Step 4: Run Your Shortcut
  4. Adding Variables and Logic
  5. Using Standard Library Actions
  6. Working with Functions
  7. Debugging Tips
    1. Use Debug Mode
    2. Add Show Actions
    3. Check Variable Types
    4. Use Nothing Actions
    5. Read Compiler Errors Carefully
  8. Signing Options
    1. macOS (Automatic)
    2. Non-macOS Platforms
      1. Option 1: HubSign (Recommended)
      2. Option 2: Custom Signing Server
  9. Editor Setup
    1. VS Code (Recommended)
    2. macOS App
  10. Next Steps
    1. Learn More Language Features
    2. Explore Standard Actions
    3. Advanced Topics
    4. Migrate Existing Shortcuts
    5. Get Help
  11. Common First-Time Issues
    1. “Command not found: cherri”
    2. “Shortcut won’t import on my device”
    3. “Undefined action error”
    4. “Type mismatch error”
  12. Tips for Success

Prerequisites

Before you begin, make sure you have:

  • A Mac, Linux, or Windows computer for development
  • An Apple device (iPhone, iPad, or Mac) to run the compiled Shortcut
  • Basic familiarity with programming concepts (variables, functions, control flow)

While you can compile Shortcuts on any platform, macOS is recommended for the best experience, as it can sign Shortcuts natively without requiring external services.

Installation

The easiest way to install Cherri on macOS is using Homebrew:

1. Add the Cherri tap:

brew tap electrikmilk/cherri

2. Install Cherri:

brew install electrikmilk/cherri/cherri

3. Verify installation:

cherri --version

Linux / Windows

1. Download the latest release:

Visit the GitHub Releases page and download the appropriate binary for your platform.

2. Make it executable (Linux only):

chmod +x cherri

3. Move to your PATH:

# Linux
sudo mv cherri /usr/local/bin/

# Windows: Move cherri.exe to a directory in your PATH

4. Verify installation:

cherri --version

On non-macOS platforms, Shortcuts will be compiled but not signed. You’ll need to use --hubsign or --signing-server= to sign them. See Signing Options below.

Alternative: Try the Web Playground

If you want to try Cherri without installing anything, visit playground.cherrilang.org to write, compile, and export Shortcuts directly from your browser!

Your First Shortcut

Let’s create a simple “Hello, World!” Shortcut that displays a greeting.

Step 1: Create a Cherri File

Create a new file called hello.cherri:

/* Hello, World! Shortcut
   My first Cherri shortcut
*/

#define glyph smileyFace
#define color yellow

// Display a greeting
const message = "Hello, Cherri!"
alert("{message}", "My First Shortcut")

Let’s break down what this does:

  • Comments: /* ... */ and // let you document your code
  • Metadata: #define glyph and #define color set the Shortcut’s icon and color
  • Constant: const message = ... creates a constant (magic variable in Shortcuts terminology)
  • Action: alert(...) shows an alert with your message

Terminology: In Shortcuts, immutable values are called “magic variables.” Cherri uses const for these. Mutable variables use @variable syntax, which creates a “Set Variable” action in Shortcuts. See Variables, Constants & Globals for details.

Step 2: Compile the Shortcut

Open your terminal and navigate to the directory containing hello.cherri, then run:

cherri hello.cherri

If the compilation is successful, you’ll see no output (following Unix conventions). The compiled hello.shortcut file is now ready to transfer to your device!

If there are any errors during compilation or signing, they will be displayed. On macOS, the Shortcut is automatically signed. On other platforms, use cherri hello.cherri --hubsign to sign it using the HubSign service.

Step 3: Transfer to Your Device

There are several ways to transfer the compiled Shortcut to your Apple device:

Option A: AirDrop (macOS only)

  1. Right-click hello.shortcut in Finder
  2. Select Share → AirDrop
  3. Choose your iPhone or iPad
  4. On your device, tap the notification to open in Shortcuts

Option B: iCloud Drive

  1. Upload hello.shortcut to iCloud Drive from your computer
  2. On your device, open the Files app
  3. Navigate to iCloud Drive
  4. Tap hello.shortcut to import it into Shortcuts

Option C: Email / Messages

  1. Attach hello.shortcut to an email or message
  2. Send it to yourself
  3. On your device, open the email/message and tap the attachment

Step 4: Run Your Shortcut

  1. Open the Shortcuts app on your device
  2. Find “hello” in your Shortcuts library
  3. Tap it to run
  4. You should see an alert saying “Hello, Cherri!”

🎉 Congratulations! You’ve just created and run your first Cherri Shortcut!

Adding Variables and Logic

Let’s make our Shortcut more interactive by asking for the user’s name.

Create a new file called greeting.cherri:

#define glyph personSpeech
#define color purple

// Ask for the user's name
@name = prompt("What's your name?")

// Create a personalized greeting
if name {
    @greeting = "Hello, {name}! Welcome to Cherri."
} else {
    @greeting = "Hello there! Welcome to Cherri."
}

// Show the greeting
show("{greeting}")

New concepts:

  • Variables: @name creates a variable (set variable action in Shortcuts)
  • Prompt action: prompt(...) prompts the user for input
  • If/else: Conditional logic to check if the user entered a name
  • String interpolation: {name} inserts the variable’s value into text
  • Show action: show(...) displays the result as a notification or dialog

Compile and run:

cherri greeting.cherri

Transfer it to your device and run it. This time, it will ask for your name and greet you personally!

Using Standard Library Actions

Cherri includes a comprehensive standard library of actions. Let’s create a Shortcut that gets device information.

Create device-info.cherri:

#include 'actions/device'

#define glyph phone
#define color lightBlue

// Get device details
const deviceName = getDeviceDetail("Device Name")
const model = getDeviceDetail("Device Model")
const osVersion = getDeviceDetail("System Version")
const battery = getBatteryLevel()

// Format the information
@info = "📱 Device: {deviceName}
Model: {model}
OS: {osVersion}
Battery: {battery}%"

// Display it
show("{info}")

New concepts:

  • Includes: #include 'actions/device' imports action definitions
  • Multiple actions: Using several standard library actions
  • Multiline text: Text can span multiple lines

See the Standard Library documentation for all available actions.

Working with Functions

Functions let you reuse code and organize complex Shortcuts.

Create calculator.cherri:

#include 'actions/scripting'

#define glyph calculator
#define color green

// Define a function to add two numbers
function add(number a, number b): number {
    const s = a + b
    output("{s}")
}

// Define a function to multiply
function multiply(number a, number b): number {
    const p = a * b
    output("{p}")
}

// Use the functions
const sum = add(5, 3)
const product = multiply(4, 7)

show("5 + 3 = {sum}\n4 × 7 = {product}")

New concepts:

  • Function definition: function name(type param): returnType { ... }
  • Output: output(...) returns a value from a function
  • Type annotations: Ensures type safety

Functions are actions run within a Run Shortcut action by injecting code at the top of your Shortcut during a pre-processing step.

Debugging Tips

When your Shortcut doesn’t work as expected, try these debugging techniques:

Use Debug Mode

Compile with the --debug or -d flag to see detailed information:

cherri hello.cherri --debug

This will:

  • Print stack traces for errors
  • Show verbose compilation information
  • Output a .plist file you can inspect

Add Show Actions

Insert show(...) actions to display variable values:

@number = 42
show("Debug: number = {number}")  // Check the value

Check Variable Types

If you get type errors, declare variable types explicitly:

@myVar: text  // Declare as text type

// Now adding to the variable will append text
@myVar += "test"

Use Nothing Actions

If you’re experiencing memory issues, add nothing() after actions that produce unused output:

someAction()
nothing()  // Clears the output

Read Compiler Errors Carefully

Cherri provides helpful error messages. For example:

Undefined reference 'name'

----- hello.cherri:5:3

This tells you exactly where the problem is.

Signing Options

macOS (Automatic)

On macOS, Shortcuts are signed automatically using the system’s signing capabilities. No additional configuration needed!

Non-macOS Platforms

On Linux or Windows, you have two options:

Use the free HubSign service provided by RoutineHub:

cherri hello.cherri --hubsign

Option 2: Custom Signing Server

Run your own signing server using shortcut-signing-server, then use:

cherri hello.cherri --signing-server=http://your-server:port

Editor Setup

Install the Cherri VSCode Extension for:

  • Syntax highlighting
  • File icons
  • Code snippets (coming soon)

Install from VS Code:

  1. Open VS Code
  2. Go to Extensions (Cmd+Shift+X / Ctrl+Shift+X)
  3. Search for “Cherri”
  4. Click Install

macOS App

Download the Cherri macOS app for a native GUI experience with:

  • Built-in editor
  • One-click compilation
  • File type integration
  • Project management

Next Steps

Now that you’ve created your first Shortcuts, here’s what to explore next:

Learn More Language Features

Explore Standard Actions

Advanced Topics

Migrate Existing Shortcuts

If you have existing Shortcuts you want to convert to Cherri, check out the Migration Guide.

Get Help

Common First-Time Issues

“Command not found: cherri”

The cherri binary is not in your PATH. Make sure you’ve followed the installation steps correctly, or use the full path to the binary.

“Shortcut won’t import on my device”

The Shortcut may not be signed. On non-macOS platforms, use --hubsign when compiling.

“Undefined action error”

You may have forgotten to include the necessary action definitions. Add the appropriate #include at the top of your file. For example:

#include 'actions/network'  // For web requests

“Type mismatch error”

Check that your variable types match what the action expects. You can explicitly declare types:

@myNumber: number
@myText: text

Tips for Success

  1. Start small - Begin with simple Shortcuts and gradually add complexity
  2. Use constants - Prefer const over @variable when values don’t change (smaller Shortcuts, better performance)
  3. Check the docs - The standard library has actions for most common tasks
  4. Experiment in the playground - Try ideas quickly without installing anything
  5. Read error messages - They usually tell you exactly what’s wrong
  6. Use debug mode - When stuck, compile with --debug to see what’s happening

Happy coding! 🍒

If you run into issues or have questions, don’t hesitate to open an issue on GitHub or check the FAQ.

Copyright ©. Distributed under the GPL-2.0 License. Siri Shortcuts and Mac are registered trademarks of Apple Inc. Apple is not involved in this project in any way. Do not contact Apple Support unless you are having an issue with the Shortcuts app itself.

Contribute to this page