---
name: investibook-cli
description: 'Drive AI-powered Jira issue investigations on the Investibook platform via CLI. Use when creating investigation workspaces, adding Jira issue sources, chatting with the AI agent for root-cause analysis, retrieving diagnostic reports, or browsing workspace files from the terminal. Use for on-call triage, automated investigation pipelines, and agent-driven workflows. Actions sync to the web UI in real time.'
argument-hint: 'Describe the investigation task, e.g. "investigate issue O11Y-195801"'
---

# AI Investigation with investibook-cli

## Quick start

```bash
# authenticate (stores the API key and a refreshable session token at ~/.investibook/config.json)
investibook init --api-host https://investibook.tidbcloud.com --api-key ib_<your-key>
# create a workspace
investibook workspace create --name "Prod OOM Investigation"
# set active workspace
investibook workspace use ws-xxx
# add a Jira issue source (triggers data preparation pipeline)
investibook sources add jira-issues O11Y-195801
# chat with the AI agent (streams response via SSE)
investibook chat "Diagnose the root cause and propose remediation steps"
# view the generated report
investibook reports get latest
```

## Commands

### Authentication

```bash
investibook init --api-host <url> --api-key <key>
# default api-host: https://investibook.tidbcloud.com
# config saved to ~/.investibook/config.json
# later commands automatically refresh the short-lived session token from this API key
```

### Workspace

```bash
investibook workspace create --name <name> --description <desc>
investibook workspace list
investibook workspace use <workspace-id>
investibook workspace show [<workspace-id>]
investibook workspace delete <workspace-id>
# alias: investibook ws list
```

### Chat

```bash
# single message — streams agent response to stdout
investibook chat "<message>"
# interactive REPL mode (Ctrl+D or /exit to quit)
investibook chat --interactive
# override workspace
investibook chat "<message>" --workspace <id>
```

Chat stream output format:
- `[thinking] ...` — agent's internal reasoning (dim gray)
- `[tool] tool_name(args)` — tool invocations (blue)
- `Error: ...` — errors (red)
- Plain text — agent's final answer

### Sources

```bash
investibook sources list
investibook sources add jira-issues <issue-id>
investibook sources remove <source-id>
```

`sources add jira-issues` triggers the backend preparation pipeline — the CLI blocks and polls until data is ready, then reports "Source ready" with artifacts created in Studio.

### Reports

```bash
investibook reports list
investibook reports get <report-id>
investibook reports get latest
# output raw JSON instead of human-readable text
investibook reports get latest --format json
```

### Files

```bash
investibook files list
investibook files get <path>
```

### Workspace Export

```bash
# export the active workspace to S3 and print a 1-hour download URL
investibook workspace export
# export a specific workspace
investibook workspace export <workspace-id>
# start the export without waiting (fire-and-forget)
investibook workspace export --no-wait
# list all export tasks for the current user
investibook workspace exports
```

`workspace export` compresses the workspace directory, uploads it to S3, and prints a presigned download URL that is valid for 1 hour. The command blocks and polls until the upload completes. Use `--no-wait` to return immediately and check progress with `workspace exports`.

### Global flags

```bash
# all commands accept --workspace (-w) to override the default
investibook chat "hello" --workspace ws-abc123
investibook sources list -w ws-abc123
```

## Environment variables

```bash
# override config file values — preferred for scripting, CI, and agent automation
export INVESTIBOOK_API="https://investibook.tidbcloud.com"
export INVESTIBOOK_TOKEN="<bearer-token>"
export INVESTIBOOK_WORKSPACE="ws-abc123"
```

## Procedures

### Investigate a Jira issue (standard flow)

1. Create a workspace: `investibook workspace create --name "<issue-id> investigation"`
2. Set active: `investibook workspace use <ws-id>`
3. Add issue source: `investibook sources add jira-issues <issue-id>` — wait for preparation to complete
4. Ask the agent: `investibook chat "What is the root cause? Suggest remediation."`
5. Retrieve report: `investibook reports get latest`
6. (Optional) Browse raw data: `investibook files list` then `investibook files get <path>`

### Autonomous agent workflow

An agent tool can drive the full investigation without human interaction:

```bash
investibook workspace create --name "Auto: O11Y-195801"
investibook workspace use ws-xxx
investibook sources add jira-issues O11Y-195801
investibook chat "Diagnose the root cause and propose remediation steps"
investibook reports get latest --format json
# team members observe the investigation in real time via the web UI
```

## Agent tool mapping

When exposing the CLI as agent-callable tools:

| Tool name | Command |
|-----------|---------|
| `investibook_create_workspace` | `investibook workspace create --name <name>` |
| `investibook_add_issue` | `investibook sources add jira-issues <issue-id>` |
| `investibook_chat` | `investibook chat "<message>"` |
| `investibook_get_reports` | `investibook reports list` |
| `investibook_get_report` | `investibook reports get latest --format json` |
| `investibook_list_files` | `investibook files list` |
| `investibook_get_file` | `investibook files get <path>` |
| `investibook_export_workspace` | `investibook workspace export` |
| `investibook_list_exports` | `investibook workspace exports` |

## Example: End-to-end Jira issue investigation

```bash
investibook init --api-host https://investibook.tidbcloud.com --api-key ib_<your-key>
investibook workspace create --name "O11Y-195801 TiKV OOM"
investibook workspace use ws-xxx
investibook sources add jira-issues O11Y-195801
investibook chat "What is the root cause of this TiKV OOM? Suggest remediation."
investibook reports get latest
```


## Example: Export a workspace

```bash
investibook workspace export
# Compressing and uploading........
# ✓ Export ready. Download URL (valid 1 hour):
# https://s3.amazonaws.com/my-bucket/investibook-exports/ws-xxx/1741680000.tar.gz?...

# Or fire-and-forget, then poll later:
investibook workspace export --no-wait
investibook workspace exports
```

## Example: Browse workspace data

```bash
investibook workspace use ws-xxx
investibook files list
investibook files get insight.json
investibook files get config/settings.yaml
```

## Example: Interactive debugging session

```bash
investibook workspace use ws-xxx
investibook chat --interactive
# > What slow queries ran in the last hour?
# > Show me the TiKV memory usage trend
# > Generate a remediation plan
# > /exit
```