Skip to content

Core Concepts

A Cereal script is a JVM JAR that the Cereal desktop app loads, configures, and runs on behalf of the user. Before diving into the dedicated pages, it helps to understand four building blocks and how they fit together.

1. The script lifecycle

Every script implements three suspend methods:

  • onStart — runs once when the script starts. Validate config, check the license, set up state. Return false to abort.
  • execute — runs repeatedly until you return a terminating ExecutionResult. This is where your automation logic lives.
  • onFinish — runs once after the task ends, regardless of outcome. Use it for cleanup or final notifications.

execute returns an ExecutionResult to control what happens next: Loop (call me again after a delay), Success (end with a success message), or Error (end with an error message).

Details: Creating a Script.

2. Configuration

User-facing settings are declared as an interface extending ScriptConfiguration, with one method per setting annotated with @ScriptConfigurationItem. Cereal reads this interface and renders the configuration UI automatically. Supported types include primitives, enums, and special types like Proxy and RandomProxy that change how Cereal schedules your script.

Details: Configuration, Advanced Configuration.

3. Components

Inside the lifecycle methods you have a ComponentProvider that exposes the Cereal app's capabilities: logging, notifications, preferences, user interaction, and starting child scripts. Components are the only sanctioned way for your script to talk to the host application.

Details: Components.

4. Tasks

A task is one running instance of your script. Most scripts run as a single task, but if your configuration uses valuePerTask or a proxy type, Cereal spins up multiple parallel tasks that share the same code with different inputs.

Details: Configuration → Concurrency and tasks, Child Scripts.

Note

The main script class constructor must be empty — Cereal instantiates it directly with no arguments. Child scripts are the exception: they may take a ScriptParameters constructor argument.