---
title: Using the CLI
sidebar_label: Overview
slug: /cli
description: "clika-cli, the CLIKA Platform command-line client: install it, log in, and drive every platform operation from a terminal or a CI job."
---

`clika-cli` is the CLIKA Platform from a terminal. It talks to your deployment's API and does the same things the web application does, so a benchmark you would start by clicking can be started from a shell script or a CI job, a device you would inspect on its page can be queried from your prompt, and an AI assistant can be given the platform as a set of tools. One binary covers the whole platform: devices, benchmarks, jobs, artifacts, models, projects and licenses are all subcommands, each generated from the deployment's own API description, so the CLI and the platform never disagree about what exists.

New to it? [Get started with the CLI](get-started.md) takes you from nothing to your first commands in about ten minutes. The rest of this page is the reference: how to install it, how it authenticates, how the commands are shaped, and where each group of commands is documented.

`clika-dm` is the sibling binary for a CLIKA Device Management deployment. It is built from the same source and behaves identically; only the set of resources differs. Everything on these pages describes `clika-cli`.

## What you can do with it

- **Drive the platform from scripts.** List devices, launch a benchmark, wait for it, and fail the build if a leg did not complete.
- **Keep definitions in git.** [`export`](apply-export.md) writes a job or service definition as YAML, [`apply`](apply-export.md) puts it back. The file you commit is the file the platform runs.
- **Reach into a device.** Run a command on it, push a file to it, or open an SSH session, without leaving your terminal.
- **Give an AI assistant access to the platform.** The [`mcp`](mcp.md) subcommand turns the CLI into a Model Context Protocol server that Claude Code, Cursor and similar tools can call.

## Install

Every deployment serves the binaries built from its own commit, so the CLI you install always matches the orchestrator it talks to. The channel lives at `<base-url>/files/installation/cli/`, where `<base-url>` is the address of your deployment (for example `https://platform.clika.io`).

**The download channel requires authentication.** That is deliberate, because the binaries are part of the deployment rather than a public download. You authenticate with one of three things:

| Credential | Where it comes from | Best for |
| --- | --- | --- |
| Download token | The web app, under **Settings** then **Developer access**. Valid for 15 minutes. | A one-off install on your own machine. |
| API key | The web app, same tab. Starts with `clika_` and does not expire until you revoke it. | CI runners and unattended installs. |
| Session token | An existing browser session. | Rarely needed by hand. |

### macOS and Linux

The **Developer access** settings tab prints a ready-to-paste one-liner with the token already filled in. It looks like this:

```
curl -fsSL "https://platform.clika.io/files/installation/cli/install.sh?token=<download-token>" | CLIKA_BASE_URL="https://platform.clika.io" CLIKA_DOWNLOAD_TOKEN="<download-token>" sh
```

The installer detects your operating system and CPU architecture, downloads the matching binary, checks it against the channel's `checksums.txt`, and installs it into `/usr/local/bin` when that is writable and `~/.local/bin` otherwise. Set `CLIKA_INSTALL_DIR` to choose a different directory. With an API key instead of a download token, set `CLIKA_API_KEY` in place of `CLIKA_DOWNLOAD_TOKEN`.

### Windows

On Windows the same tab prints a PowerShell one-liner, which runs the installer's PowerShell twin, `install.ps1`:

```
$env:CLIKA_BASE_URL='https://platform.clika.io'; $env:CLIKA_DOWNLOAD_TOKEN='<download-token>'; irm 'https://platform.clika.io/files/installation/cli/install.ps1?token=<download-token>' | iex
```

It runs in Windows PowerShell 5.1 and PowerShell 7 and needs no administrator rights. It checks the download against `checksums.txt`, installs `clika-cli.exe` into `%LOCALAPPDATA%\Programs\clika\bin` (`CLIKA_INSTALL_DIR` chooses another directory), adds that directory to your user `PATH`, and puts it on the current session's `PATH` so the CLI runs straight away. On Windows on Arm it installs the native arm64 build. Running it again upgrades the CLI in place.

Both installers also take `CLIKA_MCP`, a comma-separated list of AI clients (`claude-code`, `claude-desktop`, `codex`) to register the CLI's MCP server with once it is installed. [Get started with the CLI](get-started.md#register-your-ai-clients-in-the-same-step) shows the commands.

### Downloading one binary by hand

Any platform can skip the installer and fetch a single asset. The asset name is `clika-cli-<os>-<arch>`, with `.exe` appended on Windows:

```
curl -fsSL -H "Authorization: Bearer clika_..." -o clika-cli "https://platform.clika.io/files/installation/cli/clika-cli-linux-amd64" && chmod +x clika-cli
```

The channel publishes these assets:

| Operating system | Architecture | Asset |
| --- | --- | --- |
| Linux | x86_64 | `clika-cli-linux-amd64` |
| Linux | ARM64 | `clika-cli-linux-arm64` |
| macOS | Apple silicon | `clika-cli-darwin-arm64` |
| Windows | x86_64 | `clika-cli-windows-amd64.exe` |
| Windows | ARM64 | `clika-cli-windows-arm64.exe` |

Alongside them the channel serves `latest.json` (the published version), `checksums.txt` and `signatures.txt`, which is what [`self-update`](self-update.md) reads.

## First login

The CLI signs in with an API key: create one in the web app under **Settings** then **Developer access**, then run `login` once. It prompts for the key without echoing it, and saves the deployment address and the key to a profile file that every later command reads:

```
clika-cli --base-url https://platform.clika.io login
```

Email and password sign-in is for the web application only; the CLI never asks for a password. For CI, skip `login` and set `CLIKA_BASE_URL` and `CLIKA_API_KEY` in the environment instead.

Then check that it worked:

```
clika-cli devices list
```

Full detail on credential types, profiles and multiple deployments is on the [authentication and profiles](authentication.md) page.

### Where credentials are stored

`login` writes `$XDG_CONFIG_HOME/clika-cli/<profile>.json`, which on a default Linux or macOS setup is `~/.config/clika-cli/default.json`. The file is created with mode `0600` (readable only by you) and holds one deployment's base URL and credential. Use `--profile <name>` to keep several deployments side by side.

## Global flags

These flags work on every command. Put them anywhere on the command line.

| Flag | Type | Default | What it means |
| --- | --- | --- | --- |
| `--base-url` | string | from the profile | Address of the orchestrator to talk to, for example `https://platform.clika.io`. Reads `CLIKA_BASE_URL` when the flag is absent. |
| `--api-key` | string | from the profile | A `clika_` API key, the CLI's only credential. Pass `--api-key=<value>`, or a bare `--api-key` to be prompted without echo; when standard input is piped the value is read from it. Reads `CLIKA_API_KEY`. |
| `--profile` | string | `default` | Which saved profile to load credentials from, or save them to. |
| `-o`, `--output` | string | `table` | Output format: `table`, `json` or `yaml`. |
| `--color` | string | `auto` | When to emit ANSI color: `auto` (only when writing to a terminal), `always`, or `never`. |
| `--no-color` | bool | `false` | Turn color off. A non-empty `NO_COLOR` environment variable does the same. |
| `--insecure-tls` | bool | `false` | Skip TLS certificate verification. Only for on-premise development stacks that use a throwaway certificate authority. |
| `-y`, `--yes` | bool | `false` | Answer confirmation prompts with yes. Required for destructive deletes when standard input is not a terminal. |
| `-h`, `--help` | bool | `false` | Print help for the command and exit. |
| `-v`, `--version` | bool | `false` | Print the CLI version and exit. |

Credentials resolve in this order, highest priority first:

1. The `--api-key` and `--base-url` flags.
2. The `CLIKA_API_KEY` and `CLIKA_BASE_URL` environment variables.
3. The saved profile.

## Output formats

Every command that prints a response honors `-o`/`--output`.

| Value | What you get |
| --- | --- |
| `table` (default) | A column table for any list response. Common resources (devices, jobs, artifacts, models, benchmark groups, job definitions, service definitions) have hand-picked columns; every other list derives its columns from the fields the rows actually carry, headed by the JSON field names. A single resource, or a shape the CLI does not recognise, prints as pretty JSON. Timestamps render as ages such as `3m ago`, and byte counts render with units. |
| `json` | Pretty-printed JSON of the whole response, pagination envelope included. |
| `yaml` | The same document as YAML. |

Paginated endpoints wrap their array in `{items, total, page, page_size}`. Table mode unwraps that so you see only the rows; `json` and `yaml` keep it, so a script can still read the page state.

An empty list in table mode writes a note such as `No devices found` to standard error and prints nothing to standard output, which keeps pipes clean. In `json` and `yaml` the empty document is printed as it came back.

Color marks resource status only, and only when standard output is a terminal, so piped output never carries escape codes:

```
clika-cli devices list
clika-cli devices list -o json | jq '.items[].name'
clika-cli jobs list --color=always | less -R
```

Generated commands also accept `--raw`, which prints the response body byte for byte with no formatting at all.

## Names instead of UUIDs

Most resources have both a UUID and a human name. Anywhere a command takes an id, you can type the name instead:

```
clika-cli devices get jetson-01
clika-cli job-definitions delete llm-latency
```

The CLI lists the collection once and matches on the `name` field. An argument that already looks like a UUID is used directly, with no extra request. Name lookup is enabled for devices, jobs, models, artifacts, job definitions, service definitions and benchmark groups, and names inside an [`apply`](apply-export.md) document resolve the same way.

If two resources share a name, the CLI stops and lists the candidate ids rather than picking one, so a script never silently targets the wrong resource.

## Deletes ask first

Deleting a device also deletes its job history, so `devices delete` and `devices batch-delete` prompt for confirmation:

```
$ clika-cli devices delete jetson-01
delete device "jetson-01" (1f0a...)? (this also deletes its job history) [y/N]:
```

Pass `-y`/`--yes` to skip the prompt. When standard input is not a terminal (a CI job, a pipeline), the CLI refuses to proceed without `--yes`, so a script has to state destructive intent explicitly. Other deletes accept `--yes` as a no-op, so you can pass it uniformly.

Every delete reports what it removed, echoing both the name you typed and the id it resolved to:

```
$ clika-cli job-definitions delete smoke-test
deleted job definition "smoke-test" (7a31...)
```

Under `-o json`, `-o yaml` or `--raw` that line moves to standard error and standard output carries the response body, so scripts keep parsing.

## Exit codes

| Code | Meaning |
| --- | --- |
| `0` | The command succeeded. |
| `1` | The command failed. The reason is printed to standard error, prefixed with `error:`. A benchmark watch whose legs did not all complete also exits `1`. |
| the remote code | `devices exec` and `devices command` propagate the exit code of the command that ran on the device, the way `ssh` does. |
| `130` | You interrupted a credential prompt with Ctrl-C. |

## The command tree

Running `clika-cli --help` groups the tree into five sections.

| Section | Commands | Documented in |
| --- | --- | --- |
| Getting started | `login`, `logout`, `self-update`, `version` | [Authentication and profiles](authentication.md), [self-update](self-update.md) |
| Resources | 60 groups generated from the deployment's API description, one per resource family | The pages listed below |
| Declarative | `apply`, `export` | [apply and export](apply-export.md) |
| Advanced | `call`, `mcp`, `tools` | [MCP server and generic dispatch](mcp.md) |
| Additional | `completion`, `help` | This page |

The reference pages are grouped and ordered to follow the [concepts](../concepts/index.md), so a command sits where the thing it acts on is explained:

| Group | Pages |
| --- | --- |
| Organization and project | [authentication and profiles](authentication.md), [organizations, projects and access](projects-and-orgs.md) |
| Device | [devices](devices.md), [transfers](transfers.md), [events, metrics and alerts](monitoring.md) |
| Benchmark | [benchmarks](benchmarks.md) |
| Model deployment | [model deployment](model-deployment.md) |
| Runtime licenses | [licensing](licensing.md) |
| Artifact | [artifacts and models](artifacts.md) |
| Job | [jobs](jobs.md), [job definitions](job-definitions.md) |
| Service | [services and service definitions](services.md) |
| Tools and automation | [apply and export](apply-export.md), [MCP and generic dispatch](mcp.md), [cloud instances](cloud.md), [keeping the CLI current](self-update.md), [other groups](other-resources.md), [cheat sheet](cheatsheet.md) |

The CLI has no platform administration surface: an API key never carries the administrator step-up, so platform administration is done in the admin dashboard of the web app.

Because the resource commands are generated, the mapping from the API to the command line is mechanical and worth knowing:

| In the API | On the command line |
| --- | --- |
| A path parameter such as `{id}` | A positional argument, `<id>` or `<name-or-id>` |
| A query parameter | A flag, `--<name>` |
| A request body | `--body '<json>'` or `--body-file <path>` |
| `GET` on a collection | `list` |
| `GET` on one resource | `get <id>` |
| `POST` to a collection | `create` |
| `PUT` or `PATCH` on one resource | `update <id>` |
| `DELETE` on one resource | `delete <id>` |
| A verb in the path, such as `/restart` | A subcommand of that name |
| A name that would collide | The method or the extra path parameter is appended, as in `services-create` or `services-svc_id` |

Because the mapping is one to one, every resource subcommand is exactly one platform operation. The full command reference at the foot of each group page names that operation next to the command, with its method, its endpoint and its [MCP](mcp.md) tool name, so the same operation is identifiable whichever surface you drive it from.

For any command that takes a body, `--help` prints the body's field reference (name, type, whether it is required, description and permitted values) straight from the API description, plus a worked `--body` example when the body has required fields.

### Built-in prose help

The binary carries its own short guides, which are the condensed form of what these pages cover:

```
clika-cli help credentials
clika-cli help names
clika-cli help output
clika-cli help profiles
clika-cli help apply
clika-cli help self-update
```

### Shell completion

`completion` prints a completion script for `bash`, `zsh`, `fish` or `powershell`:

```
clika-cli completion zsh > "${fpath[1]}/_clika-cli"
```

## How the CLI relates to the web app, the API and MCP

All four are views onto one platform, and none of them can do something the others cannot see:

- **The web app** is the interactive surface. It is where you create an organization, invite people, mint API keys and read charts.
- **The platform API** is the contract. Every handler in it is annotated, and those annotations are compiled into a machine-readable description of the operations the platform offers.
- **The CLI** is generated from that description. A new endpoint becomes a new subcommand with no hand-written mapping, which is why the resource tree is so large and so uniform.
- **MCP**, the Model Context Protocol, exposes the same operations as tools an AI assistant can call. The CLI can serve them over standard input and output ([`clika-cli mcp`](mcp.md)), and the deployment serves them over HTTP at `/api/mcp`. Both are built from the same description, so a tool call and the matching CLI command do exactly the same thing.

Authorization does not change between surfaces. A CLI command runs as the identity behind your token or API key and passes the same permission checks a browser request would. An API key can additionally be scoped to a subset of your own permissions, in which case it is refused anywhere that subset does not reach, whichever surface it is used from.

## Where to go next

- [Authentication and profiles](authentication.md): the three credential types, and addressing several deployments from one machine.
- [Cheat sheet](cheatsheet.md): the twenty commands you will use most.
- [Devices](devices.md), [benchmarks](benchmarks.md), [jobs](jobs.md), [artifacts](artifacts.md): the day-to-day resource commands.
- [Model deployment](model-deployment.md): serving a model from a device.
- [Download the ClikaRT SDK](../how-to/download-the-clikart-sdk.md#download-with-the-platform-cli): `runtime-sdk list` and `runtime-sdk download`, the hand-written group that fetches a ClikaRT release archive and verifies its digest.
- [apply and export](apply-export.md): the resource YAML round trip.
- [MCP server and generic dispatch](mcp.md): give an AI assistant access to the platform.