llmist deep-research

Run long-running deep research models (OpenAI, Gemini, OpenRouter) from the shell. Progress (phases, searches, status) streams to stderr; the report streams to stdout, followed by numbered sources and a cost/usage summary.

Quick start

llmist deep-research "State of solid-state batteries in 2026" \
  --model gemini:deep-research-preview-04-2026

[llmist] Research job int_abc123 started.
[llmist] Status: in_progress
[llmist] Phase: searching
[llmist] Searching: solid state battery production 2026
...
# Solid-State Batteries: 2026 Status Report
...report text...

Sources:
  [1] https://example.com/toyota-ssb — Toyota SSB announcement
  [2] https://example.com/qs-b1 — QuantumScape B1 samples
[llmist] status: completed | 310000 tokens | 42 searches | cost: $1.87 | 1260s

Background jobs — survive the terminal

Research runs take minutes to an hour. --background starts the job, prints a serialized job ref (JSON) to stdout, and exits; the job keeps running server-side:

REF=$(llmist deep-research "..." -m openai:gpt-5.5-pro --background)
# later — even after a reboot:
llmist deep-research --resume "$REF"
# or stop it server-side:
llmist deep-research --cancel "$REF"

Background/resume requires a provider with background jobs (OpenAI, Gemini). OpenRouter research models are stream-only — --background fails with guidance, and a dropped stream cannot be resumed (use --json to log events for salvage on long runs).

Flags

| Flag | Description | |---|---| | -m, --model <id> | Research model (see client.research.listModels() or the error listing). Required unless [deep-research].model is configured. | | --background | Start, print the job ref JSON, exit. | | --resume <ref> | Re-attach to a background job from its ref JSON. | | --cancel <ref> | Cancel a background job server-side. | | --json | Emit newline-delimited JSON research events to stdout (scripting; no decorative output). | | -o, --output <path> | Write the report to a file instead of stdout. | | --timeout <seconds> | Client-side time budget (background jobs keep running server-side). | | --max-tool-calls <count> | Cap on server-side tool calls for cost control (supported by OpenAI research models). | | -q, --quiet | Suppress progress output. |

Exit codes

| Code | Meaning | |---|---| | 0 | Completed. | | 1 | Run failed. | | 2 | Partial result (incomplete, budget exceeded, or cancelled) — the partial report is still printed. |

Configuration

Defaults live in the [deep-research] section of ~/.llmist/cli.toml:

[deep-research]
model = "openrouter:perplexity/sonar-deep-research"
timeout = 1800     # seconds
quiet = false
json = false