> ## Documentation Index
> Fetch the complete documentation index at: https://docs.siclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI & Local Server

> Install Siclaw globally and run as CLI or local server.

## Recommended Working Directory

Siclaw stores most runtime data in a `.siclaw/` folder **relative to the directory where you start it**. Create a dedicated working directory and reuse it:

```bash theme={null}
mkdir -p ~/siclaw-work
cd ~/siclaw-work
```

## Install

```bash theme={null}
npm install -g siclaw
```

## Local Server (recommended)

```bash theme={null}
siclaw local
```

Launches the Web UI at `http://localhost:3000`.

On first launch, open the Web UI and **register the first user** — that account becomes the admin. Subsequent registrations require admin authentication.

## CLI (TUI)

```bash theme={null}
siclaw
```

Personal terminal mode. Same investigation engine, no server.

### Pairing with a local server

If `siclaw local` is already running in the **same working directory**, the TUI detects it automatically and uses the Portal Web UI as the single source of truth for skills, knowledge, credentials, agents, MCP servers, and LLM providers. In that mode the TUI is strictly an observer:

* `/ls [skills|knowledge|mcp|credentials|agents]` — inspect what the current session sees
* `/agent` — show the active Portal agent and all available ones; create / edit happens in the Web UI
* `/setup` — read-only view with "Open in Portal →" links (standalone mode still writes locally)

Pass `--agent <name>` to scope the session to one Portal-configured agent:

```bash theme={null}
siclaw --agent sre-oncall
siclaw agents            # list available agents non-interactively
```

When `siclaw local` is running in the cwd and you start `siclaw` for the first time (no `settings.json` yet), the setup wizard prints Portal Web UI instructions, offers to open `http://localhost:3000/settings/models` in your browser, and exits — provider setup belongs in Portal, not in a per-workstation `settings.json`.

## From Source

```bash theme={null}
git clone https://github.com/scitix/siclaw.git
cd siclaw
npm ci
make build-portal-web
npm run build

# TUI
node siclaw.mjs

# Local server
node siclaw.mjs local
```

## Configuration

By default, Siclaw reads and writes these paths relative to your current working directory:

```
.siclaw/
├── config/
│   └── settings.json     ← LLM provider, model, API key
├── credentials/           ← Imported kubeconfigs, SSH keys, API tokens
├── skills/
└── user-data/
    ├── memory/
    │   └── .memory.db
    └── ...
```

### LLM Configuration

Standalone TUI (no local Portal running in the cwd) reads `.siclaw/config/settings.json`. The easiest path is to let the first-run wizard create it for you. If a `siclaw local` server is running in the same cwd, the wizard redirects to Portal Web UI instead (see [Pairing with a local server](#pairing-with-a-local-server)) — provider setup for Portal-paired TUI happens in the Web UI's **Models** page and applies to every TUI that pairs with that Portal.

Minimal example:

```json theme={null}
{
  "providers": {
    "openai": {
      "baseUrl": "https://api.openai.com/v1",
      "apiKey": "sk-...",
      "api": "openai-completions",
      "models": [{ "id": "gpt-4o", "name": "GPT-4o" }]
    },
    "anthropic": {
      "baseUrl": "https://api.anthropic.com/v1",
      "apiKey": "sk-ant-...",
      "api": "anthropic",
      "models": [{ "id": "claude-sonnet-4-20250514", "name": "Claude Sonnet 4" }]
    }
  }
}
```

Once inside the TUI session, use `/setup` to manage providers, models, and credentials.

In Local Server mode, configure providers and models in the **Models** page of the Web UI.

See [LLM Providers](/configuration/providers) for provider examples.

### Kubernetes Credentials

Siclaw tools resolve kubeconfig from its own credential store, not from your shell's `KUBECONFIG`.

* In TUI mode, use `/setup` to import a kubeconfig
* In Local Server mode, add it in **Credentials**

After import, Siclaw can route `kubectl` calls through that stored credential.

## Embedding (Optional)

To enable Investigation Memory with semantic search, add an embedding config:

```json theme={null}
{
  "embedding": {
    "baseUrl": "https://api.example.com/v1",
    "apiKey": "sk-...",
    "model": "bge-m3",
    "dimensions": 1024
  }
}
```

If `embedding.apiKey` is omitted, Siclaw falls back to the default LLM provider key.

## Traces

Deep investigation traces are written to:

```text theme={null}
.siclaw/traces/
```

The path is resolved relative to the working directory where Siclaw was launched.