<!-- SPDX-FileCopyrightText: 2026 Apoorv Garg <apoorvgarg.21@gmail.com> -->
<!-- SPDX-FileCopyrightText: 2026 Hari Srinivasan <harisrini21@gmail.com> -->
<!-- SPDX-License-Identifier: AGPL-3.0-only -->

# Observal CLI

Command-line interface for the Observal platform. Authenticate with a server, manage registry components, configure IDEs, and collect telemetry.

## Install

The CLI is packaged as a Python project. From the repo root:

```bash
uv pip install -e .
```

This installs four entry points:

| Command                | Purpose                                             |
| ---------------------- | --------------------------------------------------- |
| `observal`             | Main CLI                                            |
| `observal-shim`        | Telemetry wrapper that sits in front of MCP servers |
| `observal-proxy`       | HTTP proxy for MCP servers                          |
| `observal-sandbox-run` | Sandbox execution runner                            |

## Quick Start

```bash
observal auth login                  # connect to your Observal server
observal scan                        # discover what's installed across your IDEs (read-only)
observal doctor patch --all --all-ides  # instrument everything (hooks + shims + OTel)
observal agent pull my-agent --ide cursor  # fetch agent config for Cursor
observal doctor                      # check IDE compatibility
```

## Commands

### Authentication

```
observal auth login       # connect to server (initializes admin on first run)
observal auth register    # create a new account
observal auth logout      # clear saved credentials
observal auth whoami      # show current user
observal auth status      # check connectivity and buffer status
```

### Agent Workflow

```
observal agent init              # scaffold observal-agent.yaml
observal agent add mcp <id>      # add a component to the agent definition
observal agent build             # validate the definition
observal agent publish           # push to the server
observal agent list              # list active agents
observal agent show <id>         # show agent details
observal agent install <id> --ide <ide>  # get IDE config snippet
```

### Component Registry

Each component type (mcp, skill, hook, prompt, sandbox) shares the same subcommand pattern:

```
observal registry <type> submit      # submit for review
observal registry <type> list        # list approved items
observal registry <type> show <id>   # show details
observal registry <type> install <id> --ide <ide>  # get IDE config
observal registry <type> delete <id> # delete
```

Hooks have an extra `sync` subcommand. Prompts have an extra `render` subcommand for variable substitution.

### Operations

```
observal ops review list           # pending submissions
observal ops review approve <id>   # approve
observal ops review reject <id> --reason "..."  # reject
observal ops telemetry status      # check telemetry flow
observal ops telemetry test        # send a test event
observal ops overview              # system-wide stats
observal ops metrics <id>          # metrics for an MCP or agent
```

### Utilities

```
observal agent pull <agent> --ide <ide>             # write agent config to IDE files
observal scan [--ide <ide>]                          # discover what's installed (read-only)
observal doctor patch --all --all-ides               # instrument everything (hooks + shims + OTel)
observal doctor patch --hook --ide <ide>             # install hooks for a specific IDE
observal doctor patch --shim --ide <ide>             # wrap MCP servers for a specific IDE
observal use <profile>                               # swap IDE config from a profile
observal doctor                                      # diagnose IDE/Observal issues
observal config show                                 # show current config
observal uninstall                                   # tear down Docker, remove config
```

## Supported IDEs

| IDE / Tool                  | Support Level                |
| --------------------------- | ---------------------------- |
| Claude Code                 | Fully supported              |
| Kiro CLI                    | Supported (next most tested) |
| Cursor, VS Code, Gemini CLI | Untested                     |

The `--ide` flag controls which config format is generated. Each IDE has its own config paths and JSON structure.

## Config Files

All CLI state lives in `~/.observal/`:

| File                     | Contents                                  |
| ------------------------ | ----------------------------------------- |
| `config.json`            | Server URL, tokens, user ID               |
| `aliases.json`           | User-defined name-to-UUID aliases         |
| `last_results.json`      | Cached list results for numeric shorthand |
| `telemetry_buffer.db`    | SQLite buffer for offline event queuing   |
| `keys/server_public.pem` | Server public key for payload encryption  |

## Telemetry

When `observal doctor patch --shim` wraps an MCP server, tool calls flow through `observal-shim` which records usage events. If the server is unreachable, events are retried automatically on the next hook fire.

Hook scripts in `observal_cli/hooks/` capture IDE-level events (prompts, tool use, subagent spawning) and forward them to the server.

## Directory Layout

```
observal_cli/
├── main.py                  # Root app, command registration
├── config.py                # Config file I/O
├── client.py                # HTTP client with auth and token refresh
├── constants.py             # Valid IDEs, categories, component types
├── render.py                # Rich output formatting
├── analyzer.py              # Repo analysis for MCP submission
├── settings_reconciler.py   # Non-destructive Claude Code settings merge
├── cmd_auth.py              # Auth commands
├── cmd_agent.py             # Agent commands
├── cmd_mcp.py               # MCP commands
├── cmd_skill.py             # Skill commands
├── cmd_hook.py              # Hook commands
├── cmd_prompt.py            # Prompt commands
├── cmd_sandbox.py           # Sandbox commands
├── cmd_pull.py              # Pull command
├── cmd_scan.py              # Scan command
├── cmd_doctor.py            # Doctor command
├── cmd_ops.py               # Operations commands
├── cmd_profile.py           # Profile swapping
├── cmd_uninstall.py         # Uninstall command
├── shim.py                  # observal-shim entrypoint
├── proxy.py                 # observal-proxy entrypoint
├── sandbox_runner.py        # observal-sandbox-run entrypoint
└── hooks/                   # Telemetry hook scripts
```
