CLI Reference
One binary, every runtime: headless runs, interactive TUI, HTTP server, MCP endpoint and maintenance tools. All commands and flags of parallel-research.
Command overview
parallel-research <COMMAND>
run Run a research task (headless)
tui Interactive TUI
serve HTTP API server + dashboard
mcp-serve Expose the agent tools over MCP (stdio)
memory Semantic memory: search / list / stats / distill / gc
sessions Browse past sessions
resume Resume an interrupted session
config Show or set configuration values
profiles List / show / create personas
contacts Contact database: list / export / dedup / push-crm
jobs Durable background jobs
bench Benchmark the tool-execution layer
stats Tool-call statistics for a recorded sessionrun
Headless research. A coordinator decomposes the query into sub-agents, synthesizes their results and writes a structured report. With --repeat it becomes watch mode: each run is diffed against the previous one and new contacts trigger alerts.
| Flag | Description |
|---|---|
| -o, --output <DIR> | Output directory for results (default: from config) |
| --repeat <SECS> | Watch mode — re-run every N seconds, diff runs, alert on new contacts |
| --profile <NAME> | Persona: hunter | analyst | validator | a file in ~/.parallel-research/profiles/ | path to a .toml |
parallel-research run "Compare Rust and Go for backend services" --output ./research/
# watch mode: re-collect every 6 hours, alert on new contacts
parallel-research run "Acme leadership team" --repeat 21600
# with a persona
parallel-research run --profile hunter "Find the CTO of Acme"tui
Interactive terminal interface (ratatui): live agent tree, streaming output, event log, jobs and memory panels, approval flow. See TUI interface for keys and panels.
| Flag | Description |
|---|---|
| [QUERY] | Optional initial query |
| --profile <NAME> | Persona applied to sessions started from the TUI |
| --replay <SESSION-ID> | Replay a stored session instead of a live run (prefix match accepted) |
parallel-research tui
parallel-research tui "Find VPs of Engineering at fintech startups" --profile analyst
parallel-research tui --replay 3f9c2a # browse a saved sessionserve
Axum HTTP server: session and job management, SSE event streams, memory API, Prometheus metrics and the web dashboard at /dashboard. Listens on loopback by default.
| Flag | Description |
|---|---|
| --port <PORT> | Listen port (default: 8080) |
| --host <HOST> | Bind address (default: 127.0.0.1) |
--host 0.0.0.0) requires PARALLEL_RESEARCH_API_KEYS to be set — otherwise startup is refused. Keys are passed via Authorization: Bearer or X-Api-Key.parallel-research serve --port 8080
parallel-research serve --host 0.0.0.0 # requires PARALLEL_RESEARCH_API_KEYSmcp-serve
Exposes all agent tools to external MCP clients (Claude, ZCode, …) over stdio. Tool calls are executed through the same registry the agents use. Logging goes to stderr so stdout stays clean JSON-RPC.
parallel-research mcp-serveAdd it to your MCP client config:
{ "command": "parallel-research", "args": ["mcp-serve"] }memory
Maintain the long-term semantic knowledge base without running an agent: hybrid search (vectors + BM25), append-only version chains, distillation and GC. Nothing is ever silently deleted.
| Subcommand | Flags | Description |
|---|---|---|
| search <query> | --top-k (default 10), --scope agent|user|run|all | Hybrid semantic + keyword search |
| list | --scope, --status active|superseded|archived|all, -n | List stored facts, newest first |
| get <id> | --follow active|latest|full_history | One record plus its version chain |
| stats | — | Counts by scope/status, entity graph, DB size |
| rebuild | — | Re-embed all facts with the current embedding model |
| distill | --session <key>, --dry-run | Distill run-scoped session facts into durable knowledge |
| gc | --ttl-days <N>, --dry-run | Archive stale run facts, compact oversized scope groups |
| nuke | --scope, --yes | Hard-delete a scope's records; requires explicit --yes |
parallel-research memory search "email of the director of Acme" --top-k 10
parallel-research memory list --scope agent --status active
parallel-research memory get 7f31 --follow full_history
parallel-research memory stats
parallel-research memory distill --dry-run
parallel-research memory gc --ttl-days 30 --dry-runsessions
Browse session history stored in the database.
| Subcommand | Flags | Description |
|---|---|---|
| list | -n <LIMIT> (default 20), -s, --search <SUBSTR> | Recent sessions, newest first; optional query substring filter |
| show <id> | — | One session in detail: agents + findings (unique prefix accepted) |
parallel-research sessions list -n 10 --search "fintech"
parallel-research sessions show 3f9c2aresume
Resume an interrupted session: re-runs its unfinished sub-tasks from the persisted state in .research.db.
| Flag | Description |
|---|---|
| -o, --output <DIR> | Session output directory (contains .research.db); default: configured output dir |
| -s, --session-id <ID> | Session to resume; default: the most recent interrupted one |
parallel-research resume --output ./results/config
Show or edit ~/.parallel-research/config.toml from the command line. Keys use dot notation: section.field.
parallel-research config show
parallel-research config set agent.max_depth 3
parallel-research config set agent.max_agents 30profiles
Personas for run --profile and tui --profile: a ready system prompt plus optional overrides for model, temperature, depth, agent count and denied tools. Built-ins: hunter, analyst, validator; your own TOML files live in ~/.parallel-research/profiles/.
parallel-research profiles list
parallel-research profiles show hunter
parallel-research profiles new my-persona # creates a template filecontacts
The OSINT contact database collected by save_contacts: list, export, deduplicate and push to the configured CRM (amoCRM, Bitrix24, HubSpot — dedup by crm_id, no duplicates on repeated pushes).
| Subcommand | Flags | Description |
|---|---|---|
| list | --limit (default 50) | List stored contacts |
| export | --format csv|vcf|json|xlsx (default csv), -o <DIR> | Export contacts to a file |
| dedup | --merge | Find duplicates (normalized email/phone); --merge folds each group into its most complete row |
| push-crm | — | Push all stored contacts to the configured CRM |
parallel-research contacts list
parallel-research contacts export --format csv
parallel-research contacts dedup # dry run: list groups
parallel-research contacts dedup --merge # actually merge them
parallel-research contacts push-crmjobs
Durable background jobs in SQLite: attempts with self-healing retry (the task is re-submitted augmented with the previous error), survive restarts.
| Subcommand | Flags | Description |
|---|---|---|
| submit <task> | --attempts (default 3) | Run a task detached in the background |
| list | — | List all jobs |
| status <id> | --watch <SECS> | Detailed status; --watch refreshes until a terminal state |
| logs <id> | -n <LINES> (default 50) | stdout + stderr of all attempts |
| cancel <id> | — | Cancel a queued or running job |
| rerun <id> | — | Re-run a finished/cancelled/stale job from scratch |
parallel-research jobs submit "Analyze the market of AI agents" --attempts 3
parallel-research jobs list
parallel-research jobs status 9b2e --watch 5
parallel-research jobs logs 9b2e
parallel-research jobs cancel 9b2e
parallel-research jobs rerun 9b2ebench
Benchmark the tool-execution layer — no network, no LLM; fixtures are generated automatically. Nine scenarios cover dispatch overhead, parallel batches, parser scaling and semantic memory.
| Flag | Description |
|---|---|
| -s, --scenario <NAME> | Scenario to run (default: all) |
| -n <N> | Parallel-safe calls / data files in batch scenarios (default: 16) |
| --save <FILE> | Also write the markdown report to a file |
parallel-research bench # all scenarios
parallel-research bench -s feed-parse # feed parsing (quick-xml)
parallel-research bench -s code-map # code_symbols / repo_map
parallel-research bench -s memory # absorb / search / digeststats
Per-tool call statistics — p50/p95 latencies — computed from a real recorded session (.research.db).
| Flag | Description |
|---|---|
| -o, --output <DIR> | Session output directory; default: configured output dir |
parallel-research stats -o ./results/TUI interface
The header shows the session id, elapsed time and a sparkline of token spend over the session. In replay mode the header is marked [REPLAY] and the saved agent tree loads with final statuses.
Keys
| Key | Action |
|---|---|
| q | Quit (also Ctrl+C) |
| i | Insert mode — type a query |
| Enter | Submit the query (insert mode) |
| Shift+Enter | Newline in the input |
| Esc | Leave insert mode / back to the input panel |
| Tab / BackTab | Cycle panels |
| Up / Down | Scroll — or move the agent cursor in the Agents panel; input history in the input |
| Left / Right | Collapse / expand an agent subtree (Agents panel) |
| t | Toggle the thinking panel |
| c | Clear output |
| y / n | Approve / deny a pending side-effect tool call |
| ? | Keymap help overlay |
| Ctrl+V | Paste mode (bracketed paste) |
Panels
Live agent tree: coordinator, sub-agents, statuses. Cursor navigation, subtrees collapse with Left/Right.
The final assembled output, streamed token-by-token as the writer produces it.
Event log: agent spawns, tool calls with timings, warnings and findings.
Durable background jobs submitted via jobs submit — state and attempts at a glance.
Recent records from the semantic memory store, refreshed live.
Query input with history navigation (Up/Down) and a dedicated paste mode.
Output structure
Every run writes the same layout into its output directory — plus optional PDF/HTML/JSON/DOCX exports when configured.
output/
├── index.md # table of contents + metadata
├── summary.md # final synthesis
├── findings/ # findings per subtask
│ ├── finding-1.md
│ ├── finding-2.md
│ └── finding-3.md
├── sources.md # source list
└── .research.db # session SQLite database