---
title: Jobs
sidebar_label: jobs
description: "clika-cli jobs: dispatch work to a device, follow it, and pull back its logs, outputs and per-sample results."
---

A **job** is one unit of work the platform runs on one device: a benchmark leg, a script, a data collection pass. It has a lifecycle (queued, running, finished), it produces an execution log and an output file, and it may produce per-sample results the platform scores afterwards.

Most jobs are created for you. Launching a [benchmark group](benchmarks.md) creates one job per model and device pair; a [job definition](job-definitions.md) pushed as desired state creates jobs on a schedule. You create one by hand when you want an ad-hoc run.

```
clika-cli jobs [command]
```

## `jobs list`

```
clika-cli jobs list [flags]
```

Lists jobs, newest first.

| Flag | Type | Default | Meaning |
| --- | --- | --- | --- |
| `--status` | string | all | One of `pending`, `starting`, `running`, `completed`, `failed`, `cancelled`, `pushing_artifacts`, `running_setup`, `running_teardown`, `collecting_output`, `cleaning_artifacts` or `interrupted`. The intermediate values are useful when a job seems stuck: they say which phase it is in. |
| `--device_id` | string | all | Only jobs on one device, by UUID. |
| `--artifact_id` | string | all | Only jobs involving one artifact, by UUID. |
| `--search` | string | none | Full-text search on the job name. |
| `--sort` | string | `created_at` | Sort column: `created_at`, `status`, `name` or `device`. |
| `--dir` | string | `desc` | Sort direction, `asc` or `desc`. |
| `--page` | string | `1` | Page number. |
| `--page_size` | string | server default | Rows per page. |
| `--raw` | bool | `false` | Print the response body byte for byte. |

```
$ clika-cli jobs list --status running
NAME                          STATUS    DEVICE      CREATED
nightly-llm-sweep-jetson-01   running   jetson-01   2m ago
nightly-llm-sweep-orin-02     running   orin-02     2m ago
```

```
clika-cli jobs list --status failed -o json | jq -r '.items[] | "\(.name)\t\(.error)"'
```

## `jobs get`

```
clika-cli jobs get <name-or-id>
```

One job in full: its status and phase, the device it ran on, timings, the definition it came from, and any error. Accepts the job name as well as its UUID.

## `jobs create`

```
clika-cli jobs create --body '<json>' [flags]
```

Dispatches a job. The body must set at least one of `job_definition_id`, `script` or `artifact_id`, which are the three ways of saying what to run.

| Body field | Type | Meaning |
| --- | --- | --- |
| `job_definition_id` | string | The preferred form: run an existing [job definition](job-definitions.md). Accepts the definition's name. |
| `script` | object | An inline script configuration, when you do not want a stored definition. Requires `output_path`. |
| `artifact_id` | string | The legacy proxy-based form. Prefer a script or a definition. |
| `device_id` | string | The single device to run on. |
| `device_ids` | array of strings | Several devices, dispatching one job each. |
| `model_id` | string | The model artifact to run against. |
| `model_ids` | array of strings | Several models. |
| `huggingface_url` | string | Source the model from a Hugging Face repository instead of an uploaded artifact. Valid only alongside `job_definition_id`. |
| `name` | string | Job name. Generated when omitted. |
| `output_path` | string | Where on the device the job writes its output. Required for an inline script job. |
| `result_type` | string | `raw` (default) or `structured`. Structured results are parsed and scored; raw ones are stored as they are. |
| `interpreter` | string | Which result interpreter to score with: `llm`, `vision` or `audio`. |
| `idle_timeout_sec` | integer | Abandon the job after this many seconds with no progress. |
| `retry_config` | object | `max_retries`, `retry_delay_ms` and `retry_on`, a list of result statuses that trigger a retry. |
| `artifacts` | array of objects | Artifacts to push to the device, overriding the definition's own list. |
| `force` | boolean | Skip the device resource compatibility check. Also available as the `--force` flag. |

```
clika-cli jobs create --body '{
  "job_definition_id": "llm-latency",
  "device_ids": ["jetson-01", "orin-02"],
  "model_id": "Qwen2.5-0.5B-Instruct"
}'
```

Running a definition from a file instead, so the request is reviewable in git, is what [`apply`](apply-export.md) is for:

```yaml
kind: Job
job_definition: llm-latency
devices:
  - jetson-01
  - jetson-02
```

## Following a job

There is no `jobs watch`. For a benchmark group use [`benchmarks watch`](benchmarks.md), which follows every leg at once. For a single job, poll `jobs get`, or read its log as it grows:

```
clika-cli jobs execution-log nightly-llm-sweep-jetson-01
```

`jobs execution-log` downloads what the agent captured while the job ran, which is the first thing to read when a job failed.

## Getting results back

A job produces up to three kinds of output, and each has its own command.

| Command | What it returns |
| --- | --- |
| `jobs output <name-or-id>` | The job's output file, as the job wrote it. |
| `jobs execution-log <name-or-id>` | The execution log captured on the device. |
| `jobs results <name-or-id>` | The per-sample proxy results, paginated. Takes `--status` (`success`, `timeout`, `queue_full`, `server_error`, `proxy_error`), `--page` and `--page_size`, which defaults to 50. |
| `jobs results-body <name-or-id> <result_id>` | One proxy result's full response body, which the list view truncates. |
| `jobs results-summary <name-or-id>` | The aggregate: counts, rates and the headline numbers. |
| `jobs results-throughput <name-or-id>` | Throughput over the life of the run, for plotting. |
| `jobs benchmark-results <name-or-id>` | The measured benchmark metrics for a benchmark job. |
| `jobs benchmark-results-io <name-or-id>` | The per-sample input, model output and expected answer, when the run was created with detailed outputs enabled. |
| `jobs benchmark-results-samples <name-or-id>` | The stored benchmark result samples. |
| `jobs benchmark-results-summary <name-or-id>` | The aggregate of those benchmark results. |
| `jobs results-latency-histogram <name-or-id>` | Latency distribution across the run, for plotting. |

```
$ clika-cli jobs results-summary nightly-llm-sweep-jetson-01
{
  "total": 500,
  "success": 498,
  "timeout": 2,
  "p50_latency_ms": 210,
  "p95_latency_ms": 470
}
```

```
clika-cli jobs results nightly-llm-sweep-jetson-01 --status timeout -o json
```

## Rescoring

```
clika-cli jobs rescore <name-or-id>
```

Runs the server-side scoring pass again over an existing benchmark job's stored results. Use it when the scoring logic changed, or when a scorer failed while the run itself was fine. The device is not involved, so this is cheap compared with re-running the job.

## Stopping and removing

```
clika-cli jobs cancel <name-or-id>
clika-cli jobs delete <name-or-id>
```

`cancel` stops a job that is queued or running. `delete` removes a finished job and its stored results.

## Subcommand index

Every subcommand, as a quick index. The full detail for each one, with its flags and the API operation it dispatches, is in the [full command reference](#full-command-reference) below.

| Subcommand | Purpose |
| --- | --- |
| `list` | List jobs with filters. |
| `get` | Get one job. |
| `create` | Dispatch a job. |
| `cancel` | Cancel a queued or running job. |
| `delete` | Delete a job and its results. |
| `output` | Download the job's output file. |
| `execution-log` | Download the execution log. |
| `results` | List per-sample proxy results. |
| `results-body` | Download one result's response body. |
| `results-summary` | Aggregate result summary. |
| `results-throughput` | Throughput over time. |
| `benchmark-results` | Measured benchmark metrics. |
| `benchmark-results-io` | Per-sample input and output samples. |
| `benchmark-results-samples` | Stored benchmark result samples. |
| `benchmark-results-summary` | Aggregate of the benchmark results. |
| `results-latency-histogram` | Latency histogram over the run. |
| `rescore` | Re-run server-side scoring. |

<!-- BEGIN GENERATED COMMAND REFERENCE (NOTES/gen-cli-reference.py) -->

## 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 jobs`

`jobs` has 19 subcommands.

#### `clika-cli jobs benchmark-results`

Get benchmark results

```
clika-cli jobs benchmark-results <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/jobs/{id}/benchmark-results`. MCP tool name: `get_jobs_id_benchmark_results`.

#### `clika-cli jobs benchmark-results-io`

Get benchmark result I/O samples

```
clika-cli jobs benchmark-results-io <name-or-id> [flags]
```

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

| Flag | Type | Default | Meaning |
| --- | --- | --- | --- |
| `--correct` | string | none | Filter by correctness, accuracy-style schemas only |
| `--filter_field` | string | none | Field filter (repeatable, aligned with filter_op / filter_value): a field the schema declares, correct, latency_ms, outcome, input.`<key>`, output.`<key>` or expected_output.`<key>` |
| `--filter_op` | string | none | Field filter operator (repeatable, aligned): gte / lte for a range filter, eq for a boolean or categorical one |
| `--filter_value` | string | none | Field filter value (repeatable, aligned): a number for gte / lte, true / false for a boolean eq, a string for a categorical eq |
| `--page` | string | none | Page number (default: 1) |
| `--page_size` | string | none | Items per page (default: 50, max: 500) |
| `--raw` | bool | `false` | print raw response without pretty-printing |
| `--status` | string | none | Filter by sample status (e.g. success, failure) |

Endpoint: `GET /api/jobs/{id}/benchmark-results/io`. MCP tool name: `get_jobs_id_benchmark_results_io`.

#### `clika-cli jobs benchmark-results-samples`

Get benchmark result samples

```
clika-cli jobs benchmark-results-samples <name-or-id> [flags]
```

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

| Flag | Type | Default | Meaning |
| --- | --- | --- | --- |
| `--page` | string | none | Page number (default: 1) |
| `--page_size` | string | none | Items per page (default: 50) |
| `--raw` | bool | `false` | print raw response without pretty-printing |
| `--status` | string | none | Filter by sample status |

Endpoint: `GET /api/jobs/{id}/benchmark-results/samples`. MCP tool name: `get_jobs_id_benchmark_results_samples`.

#### `clika-cli jobs benchmark-results-summary`

Get benchmark results summary

```
clika-cli jobs benchmark-results-summary <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/jobs/{id}/benchmark-results/summary`. MCP tool name: `get_jobs_id_benchmark_results_summary`.

#### `clika-cli jobs cancel`

Cancel job

```
clika-cli jobs cancel <name-or-id> [flags]
```

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

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

Endpoint: `POST /api/jobs/{id}/cancel`. MCP tool name: `post_jobs_id_cancel`.

#### `clika-cli jobs create`

Create job

```
clika-cli jobs create [flags]
```

| Flag | Type | Default | Meaning |
| --- | --- | --- | --- |
| `--body` | string | none | request body (inline JSON) |
| `--body-file` | string | none | request body (path to a JSON file) |
| `--force` | string | none | Skip resource compatibility check (default: false) |
| `--raw` | bool | `false` | print raw response without pretty-printing |

Endpoint: `POST /api/jobs`. MCP tool name: `post_jobs`.

#### `clika-cli jobs delete`

Delete job

```
clika-cli jobs delete <name-or-id> [flags]
```

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

| Flag | Type | Default | Meaning |
| --- | --- | --- | --- |
| `--delete_outputs` | string | none | Also delete the artifacts this job's pipeline collected (its output file and execution log). Default false: the outputs stay in the artifact library, tagged with the job id, for the record. |
| `--raw` | bool | `false` | print raw response without pretty-printing |

Endpoint: `DELETE /api/jobs/{id}`. MCP tool name: `delete_jobs_id`.

#### `clika-cli jobs execution-log`

Download job execution log

```
clika-cli jobs execution-log <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/jobs/{id}/execution-log`. MCP tool name: `get_jobs_id_execution_log`.

#### `clika-cli jobs get`

Get job

```
clika-cli jobs 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/jobs/{id}`. MCP tool name: `get_jobs_id`.

#### `clika-cli jobs list`

List jobs

```
clika-cli jobs list [flags]
```

| Flag | Type | Default | Meaning |
| --- | --- | --- | --- |
| `--artifact_id` | string | none | Filter by artifact ID (UUID) |
| `--device_id` | string | none | Filter by device ID (UUID) |
| `--dir` | string | none | Sort direction: desc (default), asc |
| `--page` | string | none | Page number (default: 1) |
| `--page_size` | string | none | Items per page |
| `--raw` | bool | `false` | print raw response without pretty-printing |
| `--search` | string | none | Full-text search on job name |
| `--sort` | string | none | Sort column: created_at (default), status, name, device |
| `--status` | string | none | Filter by status (pending\|starting\|running\|completed\|failed\|cancelled\|pushing_artifacts\|running_setup\|running_teardown\|collecting_output\|cleaning_artifacts\|interrupted) |

Endpoint: `GET /api/jobs`. MCP tool name: `get_jobs`.

#### `clika-cli jobs output`

Download job output

```
clika-cli jobs output <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/jobs/{id}/output`. MCP tool name: `get_jobs_id_output`.

#### `clika-cli jobs outputs`

List job output artifacts

```
clika-cli jobs outputs <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/jobs/{id}/outputs`. MCP tool name: `get_jobs_id_outputs`.

#### `clika-cli jobs rescore`

Re-run server-side scoring for a benchmark job

```
clika-cli jobs rescore <name-or-id> [flags]
```

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

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

Endpoint: `POST /api/jobs/{id}/rescore`. MCP tool name: `post_jobs_id_rescore`.

#### `clika-cli jobs results`

List job proxy results

```
clika-cli jobs results <name-or-id> [flags]
```

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

| Flag | Type | Default | Meaning |
| --- | --- | --- | --- |
| `--page` | string | none | Page number (default: 1) |
| `--page_size` | string | none | Items per page (default: 50) |
| `--raw` | bool | `false` | print raw response without pretty-printing |
| `--status` | string | none | Filter by result status: success, timeout, queue_full, server_error, proxy_error |

Endpoint: `GET /api/jobs/{id}/results`. MCP tool name: `get_jobs_id_results`.

#### `clika-cli jobs results-body`

Download one proxy result's response body

```
clika-cli jobs results-body <name-or-id> <result_id> [flags]
```

Positional arguments: required `<name-or-id>`, `<result_id>`.

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

Endpoint: `GET /api/jobs/{id}/results/{result_id}/body`. MCP tool name: `get_jobs_id_results_result_id_body`.

#### `clika-cli jobs results-latency-histogram`

Job latency histogram

```
clika-cli jobs results-latency-histogram <name-or-id> [flags]
```

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

| Flag | Type | Default | Meaning |
| --- | --- | --- | --- |
| `--buckets` | string | none | Number of histogram buckets (default: 20, max: 200) |
| `--raw` | bool | `false` | print raw response without pretty-printing |

Endpoint: `GET /api/jobs/{id}/results/latency-histogram`. MCP tool name: `get_jobs_id_results_latency_histogram`.

#### `clika-cli jobs results-summary`

Job results summary

```
clika-cli jobs results-summary <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/jobs/{id}/results/summary`. MCP tool name: `get_jobs_id_results_summary`.

#### `clika-cli jobs results-throughput`

Job throughput over time

```
clika-cli jobs results-throughput <name-or-id> [flags]
```

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

| Flag | Type | Default | Meaning |
| --- | --- | --- | --- |
| `--raw` | bool | `false` | print raw response without pretty-printing |
| `--window_sec` | string | none | Aggregation window in seconds (default: 10, max: 86400) |

Endpoint: `GET /api/jobs/{id}/results/throughput`. MCP tool name: `get_jobs_id_results_throughput`.

#### `clika-cli jobs status-counts`

Count jobs by status

```
clika-cli jobs status-counts [flags]
```

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

Endpoint: `GET /api/jobs/status-counts`. MCP tool name: `get_jobs_status_counts`.

<!-- END GENERATED COMMAND REFERENCE -->

## Related

- [Benchmarks](benchmarks.md): the usual way jobs get created, and how to watch a whole group of them.
- [job definitions](job-definitions.md): the reusable description a job runs from.
- [Devices](devices.md): where jobs run, and the queue and dirty-state rules that decide when.
- [Artifacts](artifacts.md): the inputs jobs consume and the outputs they leave behind.
- [Job concept](../concepts/job.mdx): what a job is, in prose.