> 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.

# CLI configuration and automation

CLI facts on this page:

1. Credentials: `SIKARU_API_KEY` (automation, takes precedence when present); keyring: `sikaru auth login` (device sign-in), `sikaru auth status`, `sikaru auth logout`; `sikaru auth login --with-token` reads a project token from standard input.
2. Validate: `sikaru runs start --schema`; `--dry-run` validates locally only.
3. Output: `--format json|table|yaml|csv|jsonl|raw|http`, `--human`, `--query EXPR` (JMESPath), `--quiet`. Check exit status; handle stderr separately.
4. Connection: `SIKARU_BASE_URL` or `--base-url`; `SIKARU_TIMEOUT_SECS` bounds one HTTP request; `SIKARU_PROXY` or standard proxy variables; `SIKARU_CA_BUNDLE`; `--debug` includes HTTP diagnostics (redact before sharing).
5. Only GET and HEAD retry automatically. A CLI timeout does not cancel a hosted run; use `sikaru runs cancel`.
6. Completions: `sikaru completion zsh`, `sikaru completion bash` (supported shells: bash, zsh, fish, PowerShell, elvish); manual: `sikaru man`.
7. Agent integration: `sikaru generate-skills --output-dir ...`, `sikaru --schema`.
8. Workspace run: `sikaru exec --project ... --agent ... --workspace /absolute/path --prompt ...`; resume only with the returned `state_dir` and original workspace.

Install the CLI using [CLI](/sdks-and-cli/cli). Use `sikaru --help` for top-level options, and an operation's `--help` or `--schema` for exact arguments.

## Set up credentials

| Use                   | Credential source                                                 |
| --------------------- | ----------------------------------------------------------------- |
| Automation            | Inject `SIKARU_API_KEY` through your secret manager.              |
| Interactive, personal | Operating-system keyring via `sikaru auth login`.                 |
| Project token         | `auth login --with-token`, reading the token from standard input. |

```sh
sikaru auth login
sikaru auth status
sikaru auth logout
```

`sikaru auth login` starts device sign-in:

1. Open the displayed verification URL.
2. Enter the code if requested.
3. Approve with your Sikaru account.

The CLI stores the resulting user credentials in its credential store and refreshes them automatically. This signed-in identity can connect your personal apps and secrets.

`SIKARU_API_KEY` takes precedence when present, so unset it for interactive personal access. Do not put a literal token in shell history. If sign-in expires or is denied, start login again. If refresh is revoked, sign in again.

> **Note**
>
> An environment credential can stay active after keyring logout. Use `auth status` to identify credential sources, and remove an injected environment variable separately when needed.

## Discover and validate a request

```sh
sikaru runs start --schema
sikaru runs start --project-id PROJECT --harness-id support --dry-run --json '{"tenant_id":"customer-42","user_id":"user-7","input":{"text":"Analyze this case"},"product_context":{},"policy":{}}'
```

`PROJECT` and `support` stand for your project ID and active agent slug. A dry run validates the request locally. It does not prove that credentials, permissions, resources, or hosted execution are available.

## Format output for scripts

```sh
sikaru runs get --project-id PROJECT --run-id RUN --format json
sikaru runs get --project-id PROJECT --run-id RUN --query status --format json
sikaru execution-sessions list --project-id PROJECT --format yaml
```

| Option                            | Purpose                                                          |
| --------------------------------- | ---------------------------------------------------------------- |
| `--format json`                   | Structured output for programs.                                  |
| `--format table` or `--human`     | Human-readable terminal output.                                  |
| `--format yaml` or `--format csv` | Alternative serialization for compatible response shapes.        |
| `--format jsonl`                  | One compact JSON value per line; arrays are flattened.           |
| `--format raw`                    | Unmodified response bytes; use for downloads.                    |
| `--format http`                   | HTTP status, headers, and body.                                  |
| `--query EXPR`                    | Apply a JMESPath projection before formatting structured output. |
| `--quiet`                         | Suppress successful stdout output while retaining errors.        |

Raw output bypasses structured formatting. Use `--query status --format json` when you extract a field. Scripts should check the process exit status and handle stderr separately.

## Configure connection settings

| Setting                                    | Purpose                                                                                                                  |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
| `SIKARU_BASE_URL` or `--base-url`          | The intended API environment.                                                                                            |
| `SIKARU_TIMEOUT_SECS`                      | Bounds one HTTP request. Separate from a hosted run's lifetime and from the native `sikaru exec` workflow's `--timeout`. |
| `SIKARU_PROXY` or standard proxy variables | Proxy, when needed.                                                                                                      |
| `SIKARU_CA_BUNDLE`                         | Additional trusted certificate authorities.                                                                              |
| `--debug`                                  | Includes HTTP diagnostic data. Inspect and redact it before you share logs.                                              |

> **Warning**
>
> Only GET and HEAD may retry automatically. Mutation commands require reconciliation after uncertain responses. A CLI timeout does not cancel a hosted run: call `sikaru runs cancel` explicitly when you intend to cancel.

## Generate shell completions and the manual

```sh
sikaru completion zsh > ./_sikaru
sikaru completion bash > ./sikaru-completion.bash
sikaru man > ./sikaru.1
```

Install the generated file using your shell's completion setup. Supported shells are bash, zsh, fish, PowerShell, and elvish.

## Integrate with other agents

```sh
sikaru generate-skills --output-dir ./sikaru-skills
sikaru --schema
```

Skill generation writes local instructions for using the public CLI. It does not create a hosted managed agent, deploy a release, or export the hosted agent's instructions. Review the output before you add it to another agent's tool environment. For machine execution, use [Local compute](/run/local-compute).

## Run in your workspace

```sh
sikaru exec --project PROJECT --agent AGENT --workspace /absolute/workspace --prompt "Review this project"
```

Fresh calls create fresh sessions. Resume only with the returned `state_dir` and the original workspace. See [Local compute](/run/local-compute) for scoped workers, containers, approval parking, and structured exit outcomes.

## Next steps

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

Install the CLI and pick models per run.

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

Attach workers and executors you control.