Skip to content

Script manifest

The script manifest is a file called manifest.json which should be included in every script, located in the resources folder. This file consist of several properties that are outlined below.

  • package_name the package name of your script, this must match the package name as provided when registering the script in the Cereal Developer Console.
  • name the name of your script used to list it in the tasks overview in the Cereal application.
  • version_code a positive integer used as an internal version number. This number helps determine whether one version is more recent than another, with higher numbers indicating more recent versions. This is not shown to users. Make sure that each successive release of your script uses a greater value.
  • sdk_version the version of the Cereal SDK your script was built against (e.g., "1.10.0"). This must match the cereal-sdk dependency version declared in your build file. Users whose Cereal client bundles an older SDK are prompted to update before they can run your script; the comparison uses the major and minor version only, so patch differences never block a user. Omitting the field means your script declares no minimum and is never blocked — set it, so users on an old client get a clear update prompt instead of a runtime failure. When using the script template, this value is automatically injected from the version catalog at build time.
  • script the fully qualified class name of your script, the package's only entry. Required unless you declare scripts, which replace it. Make sure that ProGuard keeps these classes; when using the script template, this is already the case.
  • child_scripts (optional) list of fully qualified class names for child script packages, if any. Make sure that ProGuard keeps these classes; when using the script template, this is already the case.
  • features (optional) list of Script features your script uses. This is a closed set; llm is the only value today. Declare "features": ["llm"] when your script calls provider.llm(); without it, the call throws and the task fails with an error telling you to add it. features doesn't replace sdk_version: older clients ignore features, so also set sdk_version to 1.14.0 or higher. Unknown values are ignored with a warning.
  • instructions (optional) instructions to display at the top of the script configuration screen. Use this to provide users with important setup information or configuration guidelines. With scripts, give each script its own instead.
  • scripts (optional) list of entry scripts in the same package that the user picks from, called workflows in the Cereal client. When present, they are the package's only entries and script can be left out. See Scripts below.

The manifest file must be included when the script jar is uploaded to the developer console.

Example

{
  "package_name": "com.cereal",
  "name": "My Script",
  "version_code": 1,
  "sdk_version": "1.14.0",
  "features": ["llm"],
  "script": "com.cereal.MyScript",
  "child_scripts": [
    "com.cereal.child.MyChildScript"
  ],
  "instructions": "You need to have a registered account before using this script."
}

Example (minimal)

{
  "package_name": "com.cereal",
  "name": "My Script",
  "version_code": 1,
  "sdk_version": "1.10.0",
  "script": "com.cereal.MyScript"
}

Scripts

A script package without scripts has one entry, the script class, listed under the package's name with the package's instructions. With scripts a package offers several entry scripts instead, for example a general-purpose script plus narrower, use-case-specific versions of it that share the same code. The Cereal client calls them workflows: the user picks one when adding a task, and each gets its own configuration form and its own tasks. The first script is the one the client preselects.

When a package has scripts, they are its only entries: leave out the top-level script and instructions, and list your main script in scripts with its own id, name and instructions. A top-level script next to scripts is ignored.

Each entry in scripts has these properties:

  • id the stable identifier of the script. The Cereal client stores it with every task created for it, so never change it once released. It must be unique within the package.
  • name the name shown to the user for this script. Unlike id, you can change it between releases.
  • script the fully qualified class name of the script, an ordinary Script<T> implementation with its own configuration interface. Make sure that ProGuard keeps this class.
  • instructions (optional) instructions to display at the top of this script's configuration screen.

Things to keep in mind:

  • package_name, version_code, sdk_version, features and child_scripts stay at package level and apply to every script. Declare a feature like llm once if any entry uses it.
  • One listing and one license in the Cereal marketplace cover the whole package: a user who has it can run every script in it.
  • Entries in scripts aren't child scripts. An entry is what the user picks; a child script is started by your script and isn't listed to the user.
  • A malformed entry (missing id, name or script, a duplicate id, or a script class that can't be loaded as a script) makes the client reject the whole package, the same way an invalid script does.
  • scripts requires SDK 1.15.0: build against cereal-sdk 1.15.0 or newer and set "sdk_version": "1.15.0" (or higher). Clients that bundle an older SDK can't read a manifest without script: they don't list the package at all, rather than asking the user to update.

Example (scripts)

{
  "package_name": "com.cereal",
  "name": "My Script",
  "version_code": 1,
  "sdk_version": "1.15.0",
  "scripts": [
    {
      "id": "full",
      "name": "Full Run",
      "script": "com.cereal.MyScript",
      "instructions": "You need to have a registered account before using this script."
    },
    {
      "id": "quick-check",
      "name": "Quick Check",
      "script": "com.cereal.quickcheck.QuickCheckScript",
      "instructions": "Enter the product URL to check."
    }
  ]
}