Job definitions

A job definition describes a piece of work the platform knows how to run: which command, with which files pushed to the device first, what resources the device must have, and where the result file lands. Dispatching it creates a job.

Definitions are the reusable half of the platform. You author one once, then run it against any device that meets its requirements. Because they are also the thing most worth reviewing before it runs on a fleet, they round-trip to YAML through apply and export, so the file in your repository and the definition in the platform can be kept identical.

The long-running counterpart is a service definition. The difference in one line: a job finishes, a service does not.

The commands

clika-rt job-definitions [command]

Subcommand	Purpose
list	Every definition. Takes --search <text> for a partial name match.
get <name-or-id>	One definition in full.
create --body '<json>'	Create one.
update <name-or-id> --body '<json>'	Change one.
delete <name-or-id>	Delete one.

The body

Three fields are required: name, output_path and script.

Field	Type	Meaning
name	string, required	Display name, and the handle you use everywhere else in place of the UUID.
output_path	string, required	Path on the device where the run writes its result file. The platform collects this file when the job finishes.
script	object, required	What to run. script.command is the argument vector, script.working_dir the directory to run it in, script.env an object of environment variables, and script.timeout_sec a wall-clock limit.
description	string	Free text for whoever reads the definition next.
artifacts	array of objects	Files to push to the device before the run: models, datasets, runner bundles. See artifacts.
benchmark_type_id	string	The benchmark type this definition implements. Setting it links the definition into the catalogue and turns on server-side scoring.
required_resources	object	The minimum device this definition can run on: min_cpu_cores, min_disk_bytes, min_gpu_count, further minimums, an accelerators list, a custom object, and engine.
cleanup_policy	object	What to remove from the device afterwards: remove_artifacts (unspecified means true), remove_output, and custom_paths.

Two notes on required_resources that catch people out.

The numeric minimums are a headroom warning. A dispatch that fails them can be forced through with force, on the assumption that you know something the inventory does not.

required_resources.engine is not forceable. It names a licensed inference engine the definition cannot run without, today only modelverse, which is delivered to devices as a separate entitlement-gated package. An absent engine is a missing component rather than a tight fit, so the dispatch is refused.

Examples

$ clika-rt job-definitions list --search latency
NAME              BENCHMARK TYPE   UPDATED
llm-latency       performance      3d ago
vision-latency    performance      3d ago

clika-rt job-definitions create --body '{
  "name": "GPU Benchmark v2",
  "output_path": "/tmp/benchmark_results.json",
  "script": {"command": ["python3", "run.py"], "timeout_sec": 1800}
}'

Editing an existing definition is usually easier through the YAML round trip than by writing a JSON patch:

clika-rt export JobDefinition llm-latency > job-defs/llm-latency/config.yaml
$EDITOR job-defs/llm-latency/config.yaml
clika-rt apply -f job-defs/llm-latency/config.yaml

Keeping definitions in git

The platform database and your repository are two halves of one workflow. A definition can be authored in either place, but it should end up in both. A definition edited in the dashboard and never committed disappears when the deployment is torn down, and a definition edited in the repository and never applied never takes effect.

The round trip is export to bring the platform's copy down, and apply to push your copy up. Because export strips server-managed fields (ids, timestamps, run state, counters), what the platform emits equals the file you committed.

Full command reference

Every command below is generated from the deployment's own API description, so one subcommand is exactly one platform operation. Each entry names the method, the endpoint and the MCP tool name, so the same operation is identifiable whichever surface you drive it from. Path parameters are positional arguments, query parameters are flags, and a request body is --body or --body-file. The hand-written commands, the ones that stream, propagate an exit code, or hand your terminal to ssh, carry no operation line.

The prose above covers the commands most people reach for. This section is the complete surface, for when you need the flag you have not used before.

clika-rt job-definitions

job-definitions has 5 subcommands.

clika-rt job-definitions create

Create job definition

clika-rt job-definitions create [flags]

Flag	Type	Default	Meaning
--body	string	none	request body (inline JSON)
--body-file	string	none	request body (path to a JSON file)
--raw	bool	false	print raw response without pretty-printing

Endpoint: POST /api/job-definitions. MCP tool name: post_job_definitions.

clika-rt job-definitions delete

Delete job definition

clika-rt job-definitions delete <name-or-id> [flags]

Positional arguments: required <name-or-id>.

Flag	Type	Default	Meaning
--raw	bool	false	print raw response without pretty-printing

Endpoint: DELETE /api/job-definitions/{id}. MCP tool name: delete_job_definitions_id.

clika-rt job-definitions get

Get job definition

clika-rt job-definitions get <name-or-id> [flags]

Positional arguments: required <name-or-id>.

Flag	Type	Default	Meaning
--raw	bool	false	print raw response without pretty-printing

Endpoint: GET /api/job-definitions/{id}. MCP tool name: get_job_definitions_id.

clika-rt job-definitions list

List job definitions

clika-rt job-definitions list [flags]

Flag	Type	Default	Meaning
--raw	bool	false	print raw response without pretty-printing
--search	string	none	Filter by name (partial match)

Endpoint: GET /api/job-definitions. MCP tool name: get_job_definitions.

clika-rt job-definitions update

Update job definition

clika-rt job-definitions update <name-or-id> [flags]

Positional arguments: required <name-or-id>.

Flag	Type	Default	Meaning
--body	string	none	request body (inline JSON)
--body-file	string	none	request body (path to a JSON file)
--raw	bool	false	print raw response without pretty-printing

Endpoint: PUT /api/job-definitions/{id}. MCP tool name: put_job_definitions_id.

Related

• Jobs: dispatching a definition and reading what it produced.
• Service definitions: the long-running counterpart.
• apply and export: the resource YAML format and its round trip.
• Artifacts and models: the files a definition pushes to a device.
• Job concept: what a job is, in prose.