> This page is also available as Markdown: append .md to its URL. The full index of Sikaru docs is at https://docs.sikaru.ai/llms.txt. Code examples use only operations from the public API reference at https://docs.sikaru.ai/api-reference.

# Sikaru CLI

CLI facts on this page:

1. Install: `curl -fsSL https://sikaru.ai/install.sh | sh` (macOS, Linux); `npm install -g sikaru-cli` (Node.js 20+, also Windows); `npx sikaru-cli@latest --help`; or binaries on the GitHub releases page.
2. Auth and endpoint: set `SIKARU_API_KEY`; override the endpoint with `--base-url`.
3. Discovery: `sikaru agents --help`, `sikaru runs --help`, `sikaru runs start --help`, `sikaru runs start --schema`. `--dry-run` validates without sending; `--format json` for scripts. Mutation requests are not automatically retried.
4. Per-run model: `sikaru runs start --model MODEL_ID` with a catalog ID; omit for project default; unknown IDs rejected before run creation. List catalog and default: `sikaru model_settings get_model_settings --project-id ...`. Existing execution sessions keep their model.
5. Automatic improvement: `--auto-improve` on `sikaru runs start` or `sikaru execution-sessions create`; default off; `--auto-improve=false` disables. Requires `runs:create`, `harness:write`, and an agent configured for improvement. Inspect with `sikaru harnesses list_improvements --project-id ... --harness-id ...`.
6. Execution environment: `--execution-environment managed` (default) or `--execution-environment local` (connected machine you control).

The **Sikaru CLI** is the command-line client for the Sikaru public API. Use it to manage agents and sessions, start runs, inspect events, submit tool results, and work with files and artifacts from scripts or your terminal.

## Install

#### Install script

Install the latest release on macOS or Linux:

```sh
curl -fsSL https://sikaru.ai/install.sh | sh
```

#### npm

Install with npm (Node.js 20+, also supports Windows):

```sh
npm install -g sikaru-cli
sikaru --help
```

#### npx

Run without a global installation:

```sh
npx sikaru-cli@latest --help
```

#### Binaries

Standalone binaries and installers are available on the [releases page](https://github.com/aadi-labs/sikaru-cli/releases/latest).

## Discover and validate requests

Set `SIKARU_API_KEY` in your environment. Use `--base-url` to override the API endpoint. Discover operations and request fields with help or machine-readable schemas:

```sh
sikaru agents --help
sikaru runs --help
sikaru runs start --help
sikaru runs start --schema
```

| Option          | Purpose                                    |
| --------------- | ------------------------------------------ |
| `--help`        | Show an operation's required fields.       |
| `--schema`      | Print the machine-readable request schema. |
| `--dry-run`     | Validate a request without sending it.     |
| `--format json` | Structured output for scripts.             |

> **Note**
>
> Mutation requests are not automatically retried.

See [Local compute](/run/local-compute) to attach a machine you control. Continue with [CLI automation](/sdks-and-cli/cli-automation) for detailed usage.

## Select a model for one run

Add `--model MODEL_ID`, using an ID from your project catalog, to `sikaru runs start`. This pins the selected model for that run without changing the project default. Omit the flag to use the project default. Unknown model IDs are rejected before run creation. Provider URLs and credentials stay service-managed.

List catalog choices and the current project default with:

```bash
sikaru model_settings get_model_settings --project-id "$PROJECT_ID"
```

Per-run selection requires a service deployment that supports the `model` request field. Existing execution sessions keep their previously selected model.

See [Models and output](/build/models-and-output) for catalog discovery, reasoning controls, and structured responses.

## Turn on automatic harness improvement

Add `--auto-improve` when you start a run:

```sh
sikaru runs start --project-id PROJECT --harness-id AGENT \
  --tenant-id TENANT --user-id USER --input '{"goal":"Complete the task"}' \
  --product-context '{}' --policy '{}' --auto-improve
```

Or enable it for the turns of a new session:

```sh
sikaru execution-sessions create --project-id PROJECT --harness-id AGENT \
  --tenant-id TENANT --user-id USER --auto-improve
```

| Fact         | Detail                                                                                                                         |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------ |
| Default      | Off. `--auto-improve=false` explicitly disables it at startup.                                                                 |
| Requires     | `runs:create`, `harness:write`, and an agent configured for improvement.                                                       |
| When it runs | After completed turns' evidence is graded and the configured evaluation cases are ready. Work continues when the CLI exits.    |
| Cost         | Improvement uses additional model and evaluation compute.                                                                      |
| Service      | Must support automatic improvement and have its learning worker enabled. This flag does not run an optimizer on your computer. |

Only evaluated improvements can become active. Running sessions keep their pinned release; start a new session to use an approved release. A job that requires review pauses further automatic campaigns for that agent. Inspect progress with:

```sh
sikaru harnesses list_improvements --project-id PROJECT --harness-id AGENT
```

## Choose the execution environment

| Flag                                        | Where the run executes           |
| ------------------------------------------- | -------------------------------- |
| `--execution-environment managed` (default) | Sikaru chooses the sandbox.      |
| `--execution-environment local`             | A connected machine you control. |

See [Local compute](/run/local-compute) for attaching an executor.

## Next steps

#### [CLI automation](/sdks-and-cli/cli-automation)

Credentials, output formats, and scripting.

#### [Local compute](/run/local-compute)

Attach a machine you control.

#### [Models and output](/build/models-and-output)

Pick a model and constrain output shape.