# investibook-cli — Design Document > Status: Proposal > Last updated: 2026-03-08 --- ## Overview `investibook-cli` is a command-line interface for Investibook. It brings the full production-grade investigation capability of the Investibook platform to the terminal, enabling two primary use cases: 1. **On-call engineers** who prefer CLI workflows — run investigations, browse results, and interact with the AI agent without switching to a browser. 2. **OpenClaw** — the agent can autonomously drive an end-to-end investigation by invoking `investibook-cli` commands as tools, while team members observe in real time through the web UI. The CLI is a thin client. All state, persistence, and agent execution live in the Investibook backend; the CLI speaks the same REST + SSE API as the web frontend. --- ## Vision ``` ┌────────────────────────────────────────────────────┐ │ Investibook │ │ │ │ Web UI (multi-player · mobile · OpenCode-powered) │ │ ── Sources panel ── Chat panel ── Studio panel │ │ Jira · O11Y · Clinic · Ops Portal │ └────────────────────┬───────────────────────────────┘ │ REST API + SSE ┌──────────┴──────────┐ │ investibook-cli │ │ investibook-cli │◄── OpenClaw (agent tool) └─────────────────────┘ ``` - The **web UI** is the collaboration surface: multi-player, mobile-friendly, full visual Studio panel. - The **CLI** is the automation surface: scriptable, agent-invokable, zero-UI. - Both read and write the **same Workspace** — a `/chat` command from the CLI surfaces instantly in the web UI for any co-viewers. --- ## Authentication ```bash investibook init --api https://investibook.internal --email alice@company.com # Stores token in ~/.investibook/config.json ``` All subsequent commands automatically include `Authorization: Bearer `. The CLI respects the `INVESTIBOOK_API` and `INVESTIBOOK_TOKEN` environment variables for scripting and CI contexts. --- ## Commands ### `/workspace` — Manage workspaces ```bash investibook workspace create [--name ] [--description ] investibook workspace list investibook workspace use # sets default for current shell session investibook workspace show [] investibook workspace delete investibook workspace export [] [--no-wait] investibook workspace exports ``` The active workspace is stored in `~/.investibook/session.json` (or `INVESTIBOOK_WORKSPACE` env var). All subsequent commands operate on this workspace unless `--workspace ` is explicitly passed. **`workspace export`** compresses the workspace directory into a `.tar.gz` archive, uploads it to S3, and prints a presigned download URL valid for 1 hour. The command blocks until the upload completes. Excluded from the archive: `.opencode/skills/`, `.git/`, `node_modules/`, `__pycache__/`, `.venv/`. Flags: - `--no-wait` — return immediately after kicking off the upload; use `workspace exports` to check progress. ``` $ investibook workspace export Export started (task exp-a3f9c2d01b8e) Compressing and uploading........ ✓ Export ready. Download URL (valid 1 hour): https://s3.amazonaws.com/bucket/investibook-exports/ws-xxx/1741680000.tar.gz?... $ investibook workspace exports TASK ID WORKSPACE STATUS CREATED DOWNLOAD URL exp-a3f9c2d01b8e My Workspace completed 2026-03-11T08:00 https://... ``` --- ### `/chat` — Chat with the AI agent ```bash investibook chat "" [--workspace ] investibook chat --interactive [--workspace ] # REPL mode ``` - Sends the message via `GET /api/chat/stream?message=...` (SSE). - Streams the agent's response to stdout in real time (text + tool call events rendered as plain text). - **Multi-player sync**: because this uses the same SSE endpoint as the web UI, anyone viewing the workspace in a browser sees the message and agent response appear in real time — no extra protocol needed. Example output: ``` > investibook chat "Why is TiKV OOM on cluster prod-us-west-2?" [thinking] Analyzing Jira issue sources and cluster metadata... [tool] clinic.get_slow_query_log(cluster=prod-us-west-2, window=1h) [tool] o11y.get_metric(metric=tikv_memory_usage, window=2h) Based on the data collected: **Root cause**: Region cache explosion triggered by a full table scan in slow query `SELECT * FROM orders WHERE status='pending'` at 14:32 UTC, causing TiKV RSS to spike from 12 GB → 28 GB over 20 minutes, exceeding the 24 GB memory limit. **Recommended actions**: 1. Add index on `orders(status)` — estimated impact: 90% reduction in scan rows 2. Kill the current slow query (process id 8821) immediately 3. Tune `region-max-size` from 96 MB → 144 MB as a short-term mitigation A Report Artifact has been created in your workspace Studio panel. ``` --- ### `/sources` — Add sources to a workspace Sources are the primary data inputs for a workspace. Each source type represents a different kind of data or capability: ```bash investibook sources add jira-issues [--workspace ] investibook sources add skills [--workspace ] # not yet implemented investibook sources add git [--workspace ] investibook sources list [--workspace ] investibook sources remove [--workspace ] ``` **Jira issue sources** trigger the backend preparation pipeline (`POST /api/sources/prepare`). The CLI polls for completion and shows a progress indicator: ``` > investibook sources add jira-issues O11Y-195801 Preparing Jira issue source O11Y-195801... ✓ Fetched alert metadata ✓ Fetched cluster diagnostic package ✓ Fetched historical metrics Source ready. cluster_meta source auto-added. Report and Anomaly artifacts created in Studio. ``` **Skill sources** *(not yet implemented)* — will fetch skill definitions from the given URL (supports GitHub tree URLs), create a `skill` source in the workspace, and inject the skill content into the ACP Agent's system prompt for the session. Multiple skills can be added; they accumulate. ``` > investibook sources add skills https://github.com/tidbcloud/nutshell-skills/tree/main/skills/clinic-api Added skill source: clinic-api ``` --- ### `/reports` — View generated reports ```bash investibook reports list [--workspace ] investibook reports get [--workspace ] [--format json|text] ``` Reports are the Artifacts created in the Studio panel. The CLI renders them as structured text (or raw JSON with `--format json`). --- ### `/files` — Browse workspace files ```bash investibook files list [--workspace ] [--filter agent] investibook files get [--workspace ] investibook files edit [--workspace ] # opens $EDITOR ``` `--filter agent` shows only files created by the ACP Agent (relies on the agent-file-tracking feature). `files edit` fetches the file, opens it in `$EDITOR`, and writes it back via `PUT /api/workspace/{id}/file-content` on save. --- ### `/bash` — Shell access to the workspace ```bash investibook bash "" [--workspace ] investibook bash --interactive [--workspace ] # interactive shell ``` Requires the **Pod Terminal Access** infrastructure (WebSocket shell forwarding). In non-interactive mode, runs the command and streams stdout/stderr. Useful for inspecting raw diagnostic files or manually running scripts inside the agent's working directory. --- ## Configuration File `~/.investibook/config.json`: ```json { "api": "https://investibook.internal", "token": "", "email": "alice@company.com", "defaultWorkspace": "ws_abc123" } ``` Environment variable overrides: `INVESTIBOOK_API`, `INVESTIBOOK_TOKEN`, `INVESTIBOOK_WORKSPACE`. --- ## OpenClaw Integration `investibook-cli` is designed to be invoked as a tool by OpenClaw (or any MCP-compatible agent). Suggested tool definitions: | Tool | Maps to | |------|---------| | `investibook_create_workspace` | `investibook workspace create` | | `investibook_add_issue` | `investibook sources add jira-issues ` | | `investibook_add_skill` | `investibook sources add skills ` *(not yet implemented)* | | `investibook_chat` | `investibook chat ""` | | `investibook_get_reports` | `investibook reports list` | | `investibook_get_report` | `investibook reports get latest` | | `investibook_list_files` | `investibook files list` | | `investibook_bash` | `investibook bash ""` | | `investibook_export_workspace` | `investibook workspace export` | | `investibook_list_exports` | `investibook workspace exports` | **Autopilot flow** (OpenClaw Fire-and-forget): ``` 1. investibook_create_workspace → ws_xyz 2. investibook_add_issue O11Y-195801 → sources prepared, artifacts created 3. investibook_chat "Diagnose the root cause and propose remediation steps" 4. investibook_get_report latest → structured report returned to OpenClaw 5. (Optional) investibook_bash "cat insight.json" → raw data for deeper analysis ``` Team members can open the workspace URL at any point during this flow and watch the investigation unfold in real time in the web UI. --- ## Implementation Notes - **Package**: Ship as a standalone binary (Go) or npm package (`npx investibook`). Go preferred for single-binary distribution. - **SSE rendering**: Use a simple terminal renderer — `[thinking]` lines in dim gray, `[tool]` lines in blue, final answer in default color. - **Workspace context persistence**: The active workspace ID is stored per-shell in `$INVESTIBOOK_WORKSPACE` or written to `~/.investibook/session.json`. `cd`-style switching via `investibook workspace use`. - **`/bash` dependency**: The interactive bash command depends on the Pod Terminal Access infrastructure (WebSocket forwarding). The non-interactive single-command form can be implemented earlier via a `POST /api/workspace/{id}/exec` endpoint. - **Auth**: Piggybacks on the existing email-based token system. OAuth/SSO upgrade is transparent to the CLI once the backend supports it.