caesar-research

# Caesar Research

CLI for [Caesar](https://www.caesar.org/) deep research. Runs multi-source research jobs with citations, follow-up chat, and brainstorming.

## Setup

```bash
go install github.com/alexrudloff/caesar-cli@latest
export CAESAR_API_KEY=your_key_here
```

## Research

Run a query (waits for completion by default, prints events as they happen):

```bash
caesar research create "What are the latest advances in mRNA vaccines?"
```

Returns JSON with `content` (synthesized answer with `[n]` citations) and a `results` array of sources.

Fire-and-forget:

```bash
caesar research create "query" --no-wait
# Returns: { "id": "uuid", "status": "queued" }
```

Then check on it:

```bash
caesar research get <job-id>
caesar research watch <job-id>
caesar research events <job-id>
```

### Research Options

| Flag | Description |
|------|-------------|
| `--no-wait` | Return immediately with job ID |
| `--model <name>` | `gpt-5.2`, `gemini-3-pro`, `gemini-3-flash`, `claude-opus-4.5` |
| `--loops N` | Max reasoning loops (default 1, higher = deeper research) |
| `--reasoning` | Enable advanced reasoning mode |
| `--auto` | Let Caesar auto-configure based on query |
| `--exclude-social` | Skip social media sources |
| `--exclude-domain x.com` | Exclude specific domains (repeatable) |
| `--system-prompt "..."` | Custom synthesis prompt |
| `--brainstorm <id>` | Use a brainstorm session for context |

### Status Lifecycle

`queued` → `searching` → `summarizing` → `analyzing` → `researching` → `completed` or `failed`

## Chat (Follow-Up Questions)

Ask follow-up questions about a completed research job:

```bash
caesar chat send <job-id> "How does this compare to traditional vaccines?"
```

Waits for the response by default. The answer includes inline `[n]` citations referencing the original research sources.

```bash
caesar chat send <job-id> "question" --wait=false
caesar chat history <job-id>
```

## Brainstorm

Get clarifying questions before research to improve resul...

# caesar-cli

A command-line interface for the [Caesar](https://www.caesar.org/) research API.

## Install

Requires [Go](https://go.dev/dl/) 1.21 or later.

```bash
go install github.com/alexrudloff/caesar-cli@latest
```

Or build from source:

```bash
git clone https://github.com/alexrudloff/caesar-cli.git
cd caesar-cli
go build -o caesar .
```

This produces a `caesar` binary in the current directory. Move it somewhere on your `$PATH` to use it globally:

```bash
mv caesar /usr/local/bin/
```

## Configuration

Get an API key from [caesar.org](https://www.caesar.org/) and set it as an environment variable:

```bash
export CAESAR_API_KEY=your_key_here
```

To persist it across shell sessions, add the export line to your shell profile (`~/.zshrc`, `~/.bashrc`, etc.), or create a local `.env` file:

```bash
echo 'export CAESAR_API_KEY=your_key_here' > .env
source .env
```

The `.env` file is git-ignored and will not be committed.

## Usage

### Research

```bash
# Run a research query (waits for completion by default)
caesar research create "What is quantum computing?"

# Return immediately with job ID
caesar research create "query" --no-wait

# Check on a job
caesar research get <job-id>

# Watch a job until it completes, printing events
caesar research watch <job-id>

# View reasoning events for a job
caesar research events <job-id>
```

Research options:

| Flag | Description |
|------|-------------|
| `--no-wait` | Return immediately with job ID |
| `--model` | Model to use (`gpt-5.2`, `gemini-3-pro`, `gemini-3-flash`, `claude-opus-4.5`) |
| `--loops N` | Max reasoning loops (default 1) |
| `--reasoning` | Enable reasoning mode |
| `--auto` | Auto-configure based on query |
| `--exclude-social` | Exclude social media sources |
| `--exclude-domain` | Domains to exclude (repeatable) |
| `--system-prompt` | Custom system prompt |
| `--brainstorm` | Brainstorm session ID to use |

### Chat

Ask follow-up questions about a completed research job:

```bash
# Send a fo...