--- title: Services and service definitions sidebar_label: service-definitions, services description: "clika-cli service-definitions and services: the long-running processes the platform keeps alive on a device." --- A **service** is a long-running process the platform keeps alive on a device: an HTTP server, a collector, anything that is supposed to stay up. A **service definition** describes one, the way a [job definition](job-definitions.md) describes a piece of work that finishes. The difference in one line: a job finishes, a service does not. This page covers the free-form service feature, where you supply the command. A service that serves one of your models through the CLIKA runtime is a [model deployment](model-deployment.md), which the platform defines for you. ## Service definitions ``` clika-cli service-definitions [command] ``` | Subcommand | Purpose | | --- | --- | | `list` | Every service definition. | | `get ` | One definition. | | `create --body ''` | Create one. | | `update --body ''` | Change one. | | `delete ` | Delete one. | A service definition carries the fields a long-running process needs that a job does not. | Field | Type | Meaning | | --- | --- | --- | | `name` | string | Display name and handle. | | `description` | string | Free text. | | `command` | array of strings | The argument vector to run. Unlike a job definition, it sits at the top level rather than under `script`. | | `env` | object | Environment variables. | | `port` | integer | The port the service listens on, which is what the platform advertises and health-checks. | | `health_check` | object | How to tell whether the process is actually serving, as opposed to merely running. | | `auto_restart` | boolean | Restart the process when it exits. | | `artifacts` | array of objects | Files pushed to the device before the service starts. | | `cleanup_steps` | array of objects | What to run when the service is stopped or removed. | | `required_resources` | object | The same minimums, accelerator list and `engine` gate as a [job definition](job-definitions.md#the-body). | | `project_id` | string | Scopes the definition to one project. | ## Running services `services` and `devices services-*` are the runtime side. They act on the processes actually running, as opposed to the definitions describing them. ``` clika-cli services list [flags] ``` | Flag | Type | Default | Meaning | | --- | --- | --- | --- | | `--device_id` | string | all | Only services on one device. | | `--state` | string | all | Filter by service state. | | `--search` | string | none | Match a service id, a device name, or a service type. | | `--page` | string | `1` | Page number. | | `--page_size` | string | server default | Rows per page. | That is an organization-wide view. To act on one device's services, use the [device commands](devices.md#services-on-a-device): ``` clika-cli devices services jetson-01 clika-cli devices services-create jetson-01 --body '{"service_definition_id":"vllm-server"}' clika-cli devices services-restart jetson-01 clika-cli devices services-stop jetson-01 ``` Starting a service from a committed file works the same way as a job: ```yaml kind: Service service_definition: vllm-server devices: - jetson-01 ``` `Service` is apply-only. There is no flat collection to fetch one service by id across the fleet, so `export` does not support the kind. Read a running service back through `devices services-svc_id` instead. ## Desired state keeps a service up A service is not started once and forgotten. The platform holds it in the device's **desired state**, and the agent reconciles towards it, which is what brings the process back after a device reboots. The desired-state commands are on the [devices page](devices.md#desired-state). ## 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 service-definitions` `service-definitions` has 5 subcommands. #### `clika-cli service-definitions create` Create service definition ``` clika-cli service-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/service-definitions`. MCP tool name: `post_service_definitions`. #### `clika-cli service-definitions delete` Delete service definition ``` clika-cli service-definitions delete [flags] ``` Positional arguments: required ``. | Flag | Type | Default | Meaning | | --- | --- | --- | --- | | `--raw` | bool | `false` | print raw response without pretty-printing | Endpoint: `DELETE /api/service-definitions/{id}`. MCP tool name: `delete_service_definitions_id`. #### `clika-cli service-definitions get` Get service definition ``` clika-cli service-definitions get [flags] ``` Positional arguments: required ``. | Flag | Type | Default | Meaning | | --- | --- | --- | --- | | `--raw` | bool | `false` | print raw response without pretty-printing | Endpoint: `GET /api/service-definitions/{id}`. MCP tool name: `get_service_definitions_id`. #### `clika-cli service-definitions list` List service definitions ``` clika-cli service-definitions list [flags] ``` | Flag | Type | Default | Meaning | | --- | --- | --- | --- | | `--raw` | bool | `false` | print raw response without pretty-printing | Endpoint: `GET /api/service-definitions`. MCP tool name: `get_service_definitions`. #### `clika-cli service-definitions update` Update service definition ``` clika-cli service-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/service-definitions/{id}`. MCP tool name: `put_service_definitions_id`. ### `clika-cli services` `services` has 1 subcommands. #### `clika-cli services list` List running services (org-wide) ``` clika-cli services list [flags] ``` | Flag | Type | Default | Meaning | | --- | --- | --- | --- | | `--device_id` | string | none | Filter by device ID (UUID) | | `--page` | string | none | Page number (1-based) | | `--page_size` | string | none | Items per page | | `--raw` | bool | `false` | print raw response without pretty-printing | | `--search` | string | none | Match service id, device name, or type | | `--state` | string | none | Filter by service state | Endpoint: `GET /api/services`. MCP tool name: `get_services`. ## Related - [Model deployment](model-deployment.md): the pre-defined service that serves a model through the CLIKA runtime. - [Job definitions](job-definitions.md): the counterpart for work that finishes. - [Devices](devices.md): starting, stopping and inspecting a service on one device. - [apply and export](apply-export.md): the resource YAML round trip. - [Service concept](../concepts/service.mdx): what a service is, in prose.