---
name: kelam-setup
description: Install and configure the Kelam CLI on this machine ("kelam.sh"). Use when the user says "please setup kelam.sh for me", "install the kelam CLI", "set up kelam", "get kelam working", or otherwise wants the `kelam` command installed and pointed at a server. Handles the install, the KELAM_API_URL / KELAM_PASSWORD config, and a verification check.
---

# Setting up the Kelam CLI

Goal: leave the user with a working `kelam` command pointed at their server and authenticated.
Be concise and run the steps; only ask the user for what you genuinely cannot infer.

## 1. Install the CLI

Prefer the installer bundled with this plugin (works offline); fall back to the hosted one:

```bash
sh "${CLAUDE_PLUGIN_ROOT}/install.sh"   # bundled
# or, if you have network and the bundled copy is missing:
# curl -fsSL https://kelam.sh | sh
```

The installer auto-picks `uv` → `pipx` → `pip --user`, and bootstraps `uv` if no Python
installer is present. After it runs, confirm the binary resolves:

```bash
command -v kelam && kelam --help | head -3
```

If `kelam` is not on PATH, tell the user the exact line the installer printed (usually adding
`$HOME/.local/bin` to PATH, then restarting the shell).

## 2. Configure the server + auth

The CLI is a thin client and needs to know which server to talk to:

- `KELAM_API_URL` — the control-plane URL (e.g. `https://api.kelam.sh` or `http://<host>:8000`).
- `KELAM_PASSWORD` — only if the server has `KELAM_API_PASSWORD` set (demo shared-password auth).
  The CLI sends it as the `X-Kelam-Password` header. If the server has no password, skip this.
- `KELAM_WORKSPACE` — optional tenant; defaults to `default`.

Ask the user for the URL (and password if needed) if you don't already know them, then persist
them to the user's shell profile so they survive new terminals:

```bash
{
  echo 'export KELAM_API_URL=<url>'
  echo 'export KELAM_PASSWORD=<password-if-any>'
} >> ~/.zshrc   # or ~/.bashrc
```

Also export them in the current shell so the verification below works without a restart.

## 3. Verify

```bash
kelam list
```

A JSON array of agents (even `[]`) means success. A `401` means the password is wrong or
missing; a connection error means `KELAM_API_URL` is wrong or the server is unreachable.

## 4. Tell the user what's next

Point them at the core loop and that the `kelam-viz` skill (also in this plugin) turns
`kelam export` / `kelam stats` output into dashboards:

```
kelam create my-bot        # scaffold + provision
kelam deploy <agent_id>    # make it callable
kelam call   <agent_id> +1...   # place a real call
kelam web    <agent_id>    # or talk in the browser, no phone number
```