Skip to content

Getting Started

This guide walks you through setting up a Cereal script project and running it for the first time. By the end you will have a working script that you can extend with your own logic.

Prerequisites

  • A GitHub account
  • IntelliJ IDEA (recommended) or another JVM-compatible IDE
  • JDK 11 or higher

1. Create your repository

Use the official Script Template as your starting point:

  1. Open the Script-Template repository on GitHub.
  2. Click Use this template → Create a new repository.
  3. Clone your new repository locally:
git clone https://github.com/Your-Org/Your-Script-Repo.git
  1. Open the project in IntelliJ IDEA.

2. Configure the project

Update three files to give your script its identity:

File What to change
settings.gradle.kts Set rootProject.name to your script's name
.idea/.name Set the file content to your script's name
src/main/resources/manifest.json Set package_name, name, and version_code

Then rename the package com.cereal.script.sample to your own package name. Choose carefully — the package name is permanent and cannot be changed after you upload the script to the Developer Console.

3. Implement your script

The template includes a SampleScript class. Rename it and implement the three lifecycle methods.

!!! note The main script class constructor must remain empty. Cereal instantiates the class directly and will not pass constructor arguments.

onStart

Called once when the script starts. Use it to validate configuration and check licenses. Return false to abort startup.

override suspend fun onStart(
    configuration: MyConfiguration,
    provider: ComponentProvider
): Boolean {
    // Validate required config, check license, etc.
    return true
}

execute

Called repeatedly until the script finishes. Return an ExecutionResult to control what happens next:

Result Meaning
ExecutionResult.Loop(message, delayMs) Run execute again after delayMs milliseconds
ExecutionResult.Success(message) End the task successfully
ExecutionResult.Error(message) End the task with an error 
override suspend fun execute(
    configuration: MyConfiguration,
    provider: ComponentProvider,
    statusUpdate: StatusUpdate
): ExecutionResult {
    // Your automation logic here
    return ExecutionResult.Loop("Checking...", 5000)
}

onFinish

Called once after the task ends (regardless of success or error). Use it for cleanup or final notifications.

override suspend fun onFinish(
    configuration: MyConfiguration,
    provider: ComponentProvider
) {
    provider.notification().sendNotification(notification("Script finished") {})
}

4. Run the tests

The template includes a test file (TestSampleScript.kt). Run it to verify your script compiles and executes correctly before publishing.

Next steps