--- title: Job definitions sidebar_label: job-definitions description: "clika-cli job-definitions: the reusable description of a piece of work the platform runs on a device." --- 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](jobs.md). 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`](apply-export.md), so the file in your repository and the definition in the platform can be kept identical. The long-running counterpart is a [service definition](services.md). The difference in one line: a job finishes, a service does not. ## The commands ``` clika-cli job-definitions [command] ``` | Subcommand | Purpose | | --- | --- | | `list` | Every definition. Takes `--search ` for a partial name match. | | `get ` | One definition in full. | | `create --body ''` | Create one. | | `update --body ''` | Change one. | | `delete ` | 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](artifacts.md). | | `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-cli job-definitions list --search latency NAME BENCHMARK TYPE UPDATED llm-latency performance 3d ago vision-latency performance 3d ago ``` ``` clika-cli 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-cli export JobDefinition llm-latency > job-defs/llm-latency/config.yaml $EDITOR job-defs/llm-latency/config.yaml clika-cli 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`](apply-export.md) to bring the platform's copy down, and [`apply`](apply-export.md) 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](mcp.md) 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-cli job-definitions` `job-definitions` has 5 subcommands. #### `clika-cli job-definitions create` Create job definition ``` clika-cli 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-cli job-definitions delete` Delete job definition ``` clika-cli job-definitions delete [flags] ``` Positional arguments: required ``. | 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-cli job-definitions get` Get job definition ``` clika-cli job-definitions get [flags] ``` Positional arguments: required ``. | 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-cli job-definitions list` List job definitions ``` clika-cli 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-cli job-definitions update` Update job definition ``` clika-cli job-definitions update [flags] ``` Positional arguments: required ``. | 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](jobs.md): dispatching a definition and reading what it produced. - [Service definitions](services.md): the long-running counterpart. - [apply and export](apply-export.md): the resource YAML format and its round trip. - [Artifacts and models](artifacts.md): the files a definition pushes to a device. - [Job concept](../concepts/job.mdx): what a job is, in prose.