--- title: apply and export sidebar_label: apply, export description: "clika-cli apply and export: the resource YAML round trip that keeps a definition in git identical to the definition the platform runs." --- `apply` and `export` are two halves of one idea. `apply` reads a YAML file and creates or updates what it names. `export` fetches a resource and writes the YAML that `apply` accepts back for it. Together they let a definition live in your repository, be reviewed like code, and still be the exact thing the platform runs. This matters because the platform database is a real authoring surface too. Someone can create a job definition in the web app, and that definition is then only in the deployment. A definition edited in the dashboard and never committed disappears when the deployment is torn down; a definition edited in the repository and never applied never takes effect. The round trip is what keeps the two honest. ## `apply` ``` clika-cli apply -f [-f ...] [flags] ``` Reads one or more multi-document YAML files, routes each document by its `kind` field, and sends the resulting requests. | Flag | Type | Default | Meaning | | --- | --- | --- | --- | | `-f`, `--file` | string, repeatable | none | The YAML file to apply. Repeat it to apply several. `-f -` reads standard input. | | `--dry-run` | bool | `false` | Resolve every reference and print the requests that would be sent, without sending them. | ### Semantics - **Definitions are created or updated by name.** `JobDefinition`, `ServiceDefinition` and `Model` are matched on their `name`, so applying a committed file twice does not create a duplicate. This is what makes `apply` safe to run from CI on every merge. - **Runs always create.** `Job`, `Service`, `Benchmark` and `BenchmarkGroup` are actions, not state, so each apply starts a new one. - **References may be names.** Write `devices: [jetson-01]` rather than a UUID; the same [name resolution](index.md#names-instead-of-uuids) the rest of the CLI uses applies inside the document. - **A `spec:` wrapper is accepted.** If your document nests the body under `spec:`, it is unwrapped. Keys beside `spec:` win over keys inside it. - **Documents apply in order.** Several documents in one file, separated by `---`, are applied top to bottom, so a document may reference something an earlier one created. ### Supported kinds | Kind | Endpoint | Semantics | Exportable | | --- | --- | --- | --- | | `JobDefinition` | `/api/job-definitions` | Create or update by name | Yes | | `ServiceDefinition` | `/api/service-definitions` | Create or update by name | Yes | | `Model` | `/api/models` | Create or update by name | Yes | | `Job` | `POST /api/jobs` | Always creates | Yes | | `Service` | `POST /api/devices/{id}/services` | Always creates, once per target device | No | | `Benchmark`, `BenchmarkGroup` | `POST /api/benchmark-groups` | Always creates | Yes | `Service` is apply-only, because there is no flat collection to fetch one service back from by id. Read a running service through `devices services-svc_id` instead. `clika-cli apply --help` prints the kinds this binary supports, which is the authoritative list for the deployment you are talking to. ### Reference fields Certain fields are resolved from a name to an id before the request goes out. | Field in your document | Looked up in | Sent as | | --- | --- | --- | | `job_definition` | `/api/job-definitions` | `job_definition_id` | | `device` | `/api/devices` | `device_id` | | `devices` (list) | `/api/devices` | `device_ids` | | `model` | `/api/models` | `model_id` | | `models` (list) | `/api/models` | `model_ids` | | `service_definition` | `/api/service-definitions` | The definition's fields, merged in as defaults | The canonical `*_id` fields accept a name too, so either spelling works. One thing that is deliberately **not** implemented: `device_selector`, the old group-based way of picking targets. `apply` reports it as unknown rather than quietly forwarding it, so list the devices explicitly. ### Examples Apply a definition and a run in one file: ```yaml kind: JobDefinition name: llm-latency output_path: /tmp/results.json result_type: structured script: command: - python3 - run.py timeout_sec: 3600 --- kind: Job job_definition: llm-latency devices: - jetson-01 - jetson-02 ``` ``` $ clika-cli apply -f llm-latency.yaml job definition "llm-latency" updated (7a31...) job "llm-latency-jetson-01" created (c4f2...) job "llm-latency-jetson-02" created (c4f3...) ``` Register a model and benchmark it in one file: ```yaml kind: Model huggingface_url: https://huggingface.co/Qwen/Qwen2.5-0.5B-Instruct task: text-generation --- kind: Benchmark name: nightly-llm-sweep benchmark_type: llm_performance models: - Qwen2.5-0.5B-Instruct devices: - jetson-01 - orin-02 ``` Check what a file would do before it does it: ``` clika-cli apply -f defs.yaml -f run.yaml --dry-run ``` Generate a document and pipe it in: ``` cat run.yaml | clika-cli apply -f - ``` ## `export` ``` clika-cli export ``` Fetches one resource and writes it as canonical resource YAML on standard output. Server-managed fields are stripped: ids, timestamps, audit columns, run state and derived counters, and null fields are omitted. What comes out is what `apply` takes back in. Exportable kinds are `Benchmark`, `BenchmarkGroup`, `Job`, `JobDefinition`, `Model` and `ServiceDefinition`. ``` $ clika-cli export JobDefinition llm-latency kind: JobDefinition name: llm-latency description: Single-stream latency for text generation output_path: /tmp/results.json result_type: structured script: command: - python3 - run.py timeout_sec: 3600 required_resources: min_gpu_count: 1 ``` ``` clika-cli export ServiceDefinition vllm-server clika-cli export Job 1f0a2b3c-4d5e-6f70-8192-a3b4c5d6e7f8 ``` ## The round trip Bringing a dashboard-authored definition into the repository: ``` clika-cli export JobDefinition llm-latency > job-defs/llm-latency/config.yaml git add job-defs/llm-latency/config.yaml && git commit -m "chore: commit llm-latency definition" ``` Pushing a repository edit back to a deployment: ``` clika-cli apply -f job-defs/llm-latency/config.yaml ``` Verifying that the two match, which is worth doing in CI: ``` clika-cli export JobDefinition llm-latency | diff -u job-defs/llm-latency/config.yaml - ``` Because `export` strips exactly the fields the platform owns, that `diff` is empty when the definition has not drifted, and shows precisely what changed when it has. ## Applying to several deployments A file is not tied to a deployment, so the same definition can be rolled out everywhere with a profile per target: ``` for p in cloud onprem; do clika-cli --profile "$p" apply -f job-defs/llm-latency/config.yaml; done ``` See [authentication and profiles](authentication.md) for setting those up. ## 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 apply` #### `clika-cli apply` Applies one or more multi-document YAML files. Each document is routed by its `kind:` field; a `spec:` wrapper around the body is accepted and unwrapped. Definitions are created or updated by name, so re-applying a committed file is idempotent; runs (Job, Service, Benchmark) always create. References inside a document may be names rather than UUIDs. ``` clika-cli apply -f [-f ...] [flags] ``` Positional arguments: required ``, ``; optional `[-f ...]`. | Flag | Type | Default | Meaning | | --- | --- | --- | --- | | `--dry-run` | bool | `false` | print the resolved requests instead of sending them | | `-f, --file` | stringArray | none | YAML file to apply (repeatable; '-' reads stdin) | ### `clika-cli export` #### `clika-cli export` Fetches a resource and writes the YAML that `apply` accepts back for it, with server-managed fields (ids, timestamps, run state, counters) stripped. This is the download half of the job-definitions convention: what the platform emits should equal the file committed to the repo. ``` clika-cli export [flags] ``` Positional arguments: required ``, ``. ## Related - [job definitions](job-definitions.md): the field reference for what goes inside these documents. - [Jobs](jobs.md) and [benchmarks](benchmarks.md): what a `Job` or `Benchmark` document dispatches. - [How-to guides](../how-to/index.md): task-shaped walkthroughs for authoring a definition. - [CLI overview](index.md): global flags, output formats and exit codes.