CLI docs

Updated June 12, 2026

The CLI wraps the same API used by the frontend and downstream agents.

Public base URL: https://researcher.now.

Local use

The CLI is for local/repository use: pnpm cli ... or pnpm exec tsx apps/cli/index.ts ....

Customer agents should not guess an npm package name or run npm install -g researcher-cli. There is no public CLI package required for onboarding. Use the direct HTTP API unless the customer has already installed this repository's CLI.

Environment

RESEARCHER_BASE_URL: Use https://researcher.now for remote access; local runs can point at a dev server.
RESEARCHER_TOKEN: Admin bearer token or customer rk_... API key for every authenticated API call.
RESEARCHER_API_KEY: Optional alias for customer rk_... API keys. The CLI treats it like RESEARCHER_TOKEN.

Customers can log in and create keys at https://researcher.now/account/.

Customer agent quickstart

First-time agents use the API flow, not CLI installation. The full machine contract is at researcher.now/agent.txt.

Keyless (no key, no human) — a wallet-native agent provisions itself:

1. POST https://researcher.now/v1/runs (or /v1/analyze, or /v1/entities/:slug/chat) with NO Authorization
2. You get 402 + an MPP session challenge; authorize it from your wallet and retry with the credential
3. The first paid call provisions an account and returns a durable rk_ key in the X-Researcher-Agent-Key header
4. Reuse that key (Authorization: Bearer rk_...) for reads, management, and more runs

Any x402 client (tempo CLI, mppx, or an x402 MCP client at https://researcher.now/mcp) does steps 1-2 for you.

Or with a key (human in the loop):

1. Send the customer to https://researcher.now/account/?setup=agent
2. Ask them to log in, press "Create agent key", and paste the one-time rk_... key back
3. export RESEARCHER_BASE_URL="https://researcher.now"
4. export RESEARCHER_TOKEN="${RESEARCHER_TOKEN:-$RESEARCHER_API_KEY}"
5. POST /v1/analyze for a single article, video, or podcast URL
6. POST /v1/runs with source.type=topic, url, feed, or video for deep research
7. Send the returned watchUrl/viewerUrl to the customer immediately

Never search dotfiles, shell history, backups, or the filesystem for keys.
Use direct HTTP with long request timeouts before falling back to anything else.

Commands

researcher health: Checks the service.
researcher run preflight: Runs a planning preflight, prints clarifying questions, and suggests the next create command.
researcher run plan: Returns the raw recommended setup before creation.
researcher run create ...: Creates a new research run directly. Use --sources-only to avoid broad web search and --skip-synthesis only when no final report should be generated.
researcher run continue <run-id>: Continues an existing run in place, optionally anchored to a specific event.
researcher run watch <id>: Streams live run snapshots and prints new activity milestones.
researcher run get <id>: Fetches run and job state with optional include and wait flags.
researcher run sources <id>: Fetches stored source rows, including captured markdown when available.
POST /v1/runs/:id/sources: The API can add one or more sources to an existing run with url or sources[]; source comments are supported in sources[].
DELETE /v1/runs/:id/sources: The API can prune multiple sources with sourceIds[], or prune one source with DELETE /sources/:sourceId.
researcher run export <id>: Writes a run into an Obsidian-ready folder with report, brief, manifest, and stored source notes.
researcher run eval <id>: Stores an evaluation record through /v1/runs/:id/iterate.
researcher run diff|tags|tag-add|tag-remove <id>: Compares runs and manages run tags.
researcher run prune-sources|source-redo <id>: Prunes source batches or re-analyzes one weak source.
researcher run chat-index|chat-index-rebuild <id>: Reads or rebuilds the run retrieval index.
researcher account ...: Reads balance, deposit addresses, and manages account API keys.
researcher collections ...: Lists collections, creates collections, and adds or removes runs.
researcher library list: Lists completed runs in the library with filters and search.
researcher library recall: Returns related runs, sources, and evidence for a topic.
researcher library sources: Searches reusable source rows across completed runs.
researcher library evidence: Searches extracted claims, facts, dates, laws, and other evidence across completed runs.
researcher library get <id>: Fetches a single library entry.

Example

export RESEARCHER_BASE_URL="https://researcher.now"
export RESEARCHER_TOKEN="shared-secret-or-rk-customer-key"

pnpm cli run plan \
  --topic "recent advances in battery recycling" \
  --mode collection

pnpm cli run preflight \
  --topic "Special Economic Zones in Australia: complete historical analysis" \
  --depth wide \
  --academic \
  --max-research-loops 4 \
  --question "What SEZ-like regimes has Australia attempted, why did they fail or remain proposals, and what explains non-adoption?" \
  --must-answer "implemented zones, proposals, timeline, legal constraints, political economy, stakeholder arguments, and evidence gaps" \
  --source-priorities "official Australian government records, NT legislation, parliamentary inquiries, Hansard, academic policy analysis" \
  --output "insight-heavy markdown report with chronology and comparison tables"

pnpm cli run create \
  --topic "recent advances in battery recycling" \
  --mode collection \
  --depth standard \
  --requested-by researcher \
  --academic \
  --max-research-loops 3 \
  --video-transcript "https://www.youtube.com/watch?v=VIDEO_ID|native|en"

pnpm cli run create \
  --org-id 00000000-0000-0000-0000-000000000000 \
  --requested-by researcher \
  --topic "recent advances in battery recycling" \
  --mode collection \
  --depth standard \
  --academic \
  --max-research-loops 3

pnpm cli run continue RUN_ID \
  --goal "deepen the strongest path from the parent run" \
  --event-id EVENT_ID \
  --mode analysis \
  --depth wide \
  --focus "close the main evidence gaps,compare leading options"

pnpm cli run watch RUN_ID

pnpm cli run source-analysis RUN_ID
pnpm cli run export RUN_ID --format obsidian --out ./ResearcherVault

Run creation returns a watchUrl for read-only live customer status. Send that URL to the customer immediately after creation succeeds, then keep run watch open and forward meaningful milestones as they happen.

Use --academic when academic or scholarly sources should be included. It writes sourcePolicy.academic: true into the API request.

Use --video-transcript URL|mode|lang only when the customer or calling agent has opted into analyzing that specific video. native uses existing captions; auto may spend AI transcription credits when captions are unavailable.

Live handoff

run watch connects to GET /v1/runs/:id/stream. It prints the customer-safe watchUrl first, then new activity rows for planning, acquisition, extraction, merge, quality review, synthesis, completion, pause, stop, deletion, failure, and cancellation.

run create prints the raw response plus a human receipt: run ID, current status, watch URL, viewer URL, effective config, and storage retention reference. Continuations reuse the same runId and requeue the existing run in place. Give that receipt to the customer immediately, then keep streaming updates.

researcher run watch <run-id>

researcher run watch <run-id> --json

Use --json when another agent or process should parse the full snapshot stream directly.

researcher run pause <run-id>
researcher run stop <run-id>
researcher run delete <run-id>

Use run pause or run stop only for active running jobs. Use run delete when the customer wants the run and stored artifacts removed from their account.

Stored sources

Use run sources when an agent needs the stored source material behind a run. Source rows include captured markdown and stored source URLs when available. Use run export to write the run directly into an Obsidian vault folder.

researcher run sources RUN_ID

researcher run export RUN_ID \
  --format obsidian \
  --out ~/Obsidian/Researcher

Planning conversation

Use run preflight when the customer gives a broad topic. The command calls the planning endpoint, shows the proposed setup, and prints the questions an agent should ask before spending budget. Rerun it with --instructions, --brief-file, or the structured brief flags until the plan names the success criteria, source priorities, must-answer questions, and output shape.

pnpm cli run preflight \
  --topic "Special Economic Zones in Australia" \
  --academic \
  --question "Why has Australia not adopted a durable SEZ regime?" \
  --must-answer "implemented cases, failed proposals, timeline, legal constraints, stakeholders" \
  --source-priorities "official records, legislation, inquiries, Hansard, academic policy analysis" \
  --output "markdown report with chronology and comparison tables"

Do not create a paid run from a vague topic if the preflight plan is generic.

Paid calls

Customer rk_... keys create runs directly using the customer's funded Researcher server wallet. Optional budget caps limit spend; billed is the metered amount settled or charged so far; cost is Researcher's raw internal provider cost.

pnpm cli run create \
  --topic "battery recycling" \
  --mode collection \
  --depth standard \
  --requested-by customer-agent \
  --sources-only

# Only if customer create returns 402 Payment Required:
# fund the Researcher server wallet at /account/, then retry.

Fetch context

pnpm cli run get <run-id> --include media,artifacts,context --wait

This returns the layered bundle. Agents should read agentBriefMarkdown first, then use the action manifest, corpus analysis, source extractions, claim-evidence map, and raw sources for deeper work.

Library

pnpm cli library list --limit 20 --q battery

pnpm cli library recall --limit 12 --q battery

pnpm cli library sources --limit 50 --q battery

pnpm cli library evidence --limit 50 --q battery

pnpm cli library get <run-id>