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_namethe package name of your script, this must match the package name as provided when registering the script in the Cereal Developer Console.namethe name of your script used to list it in the tasks overview in the Cereal application.version_codea 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_versionthe version of the Cereal SDK your script was built against (e.g.,"1.10.0"). This must match thecereal-sdkdependency 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.scriptthe fully qualified class name of your script, the package's only entry. Required unless you declarescripts, 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;llmis the only value today. Declare"features": ["llm"]when your script callsprovider.llm(); without it, the call throws and the task fails with an error telling you to add it.featuresdoesn't replacesdk_version: older clients ignorefeatures, so also setsdk_versionto1.14.0or 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. Withscripts, 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 andscriptcan 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:
idthe 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.namethe name shown to the user for this script. Unlikeid, you can change it between releases.scriptthe fully qualified class name of the script, an ordinaryScript<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,featuresandchild_scriptsstay at package level and apply to every script. Declare a feature likellmonce 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
scriptsaren'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,nameorscript, a duplicateid, or ascriptclass that can't be loaded as a script) makes the client reject the whole package, the same way an invalidscriptdoes. scriptsrequires SDK 1.15.0: build againstcereal-sdk1.15.0 or newer and set"sdk_version": "1.15.0"(or higher). Clients that bundle an older SDK can't read a manifest withoutscript: 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."
}
]
}