valyu-cli

Valyu CLI

Terminal access to grounded, cited answers for knowledge work — DD briefs, earnings analyses, drug candidate shortlists, clinical trial trackers, ICP account lists, patent landscapes, and competitive research. Runs synchronously for quick lookups (search, answer, contents) and asynchronously for deeper workflows (deepresearch).

Command tree

valyu
├── search <type> <query>               # one-shot search (web / paper / bio / finance / sec / patent / economics / news)
├── answer <query>                      # AI-synthesized answer with citations (streaming)
├── contents <urls...>                  # clean extraction from URLs (+ optional AI summary / structured schema)
├── deepresearch                        # async multi-step research agent
│   ├── create <query> [options]        # with steering, deliverables, HITL, structured output
│   ├── list / status / watch
│   ├── update / cancel / delete / share
├── workflows                           # reusable, versioned deepresearch templates
│   ├── list / get / versions           # discover curated (Valyu) + org templates
│   ├── preview <slug> [--param k=v]    # resolve template, no credits spent
│   ├── run <slug> [--param k=v]        # run template -> starts a deepresearch task
│   ├── create / update / delete        # manage your org's templates (file-based)
├── batch                               # parallel deepresearch jobs with shared config
├── sources                             # list available proprietary data sources
├── account                             # self-service: keys, balance, top-ups, datasets
│   ├── whoami                          # org, tier, calling key + budget
│   ├── keys list / create / revoke / rotate   # create --cap = budget-capped agent key
│   ├── balance / topup <amount>        # credits (topup charges card on file, else checkout URL)
│   ├── datasets                        # tier entitlements
├── login / logout / whoami             # auth (login defaults to browser device flow)
├── doctor                              # setup + connectivity check
├── upgrade                             # detect install source, show / run upgrade command
└── open                                # open platform / docs / API keys in browser

Agent protocol (key patterns)

# Every command supports JSON output. Non-TTY auto-detects, -q forces it.
valyu search paper "GLP-1 obesity trials" -q
valyu deepresearch status <id> -q

# Stdin supported for: search, answer, contents, batch
echo "Tesla Q4 earnings key takeaways" | valyu answer - -q

# Async deep research: create returns immediately, watch blocks until done
ID=$(valyu deepresearch create "..." -q | jq -r .deepresearch_id)
valyu deepresearch watch "$ID"          # internal 5s poll - DON'T loop status manually
valyu deepresearch update "$ID" "Also cover regulatory risk"   # mid-flight steering

# Exit codes: 0 = success, 1 = error
# Error JSON: {"error":{"message":"...","code":"..."}}

# Webhook-driven async (no polling at all)
valyu deepresearch create "..." --webhook-url https://your-app.com/hook -q

Self-provisioning (zero-to-first-call for agents)

valyu login defaults to the browser device flow - it mints and stores a scoped val_ key, so an agent never has to ask a human to paste a secret. In --json mode it streams line-delimited events (device_code → auth_waiting → auth_success); surface verification_uri_complete to a human and read lines until auth_success.

valyu login --json                       # drive device flow, parse NDJSON events
valyu account balance -q                 # check credit; topup if zero
valyu account keys create --name agent --cap 5 -q   # budget-capped sub-agent key
valyu search web "..." -q

Budget-capped agent keys are the headline account pattern: --cap 5 mints a key that can spend at most $5 before the data plane returns 402 spend_cap_reached. The secret is shown exactly once. Requested scopes/cap can never exceed the calling key's own (server-enforced). Full details: references/account.md.

Global flags

Flag	Description
--api-key <key>	Override API key for this invocation
-p, --profile <name>	Select stored profile
--json	Force JSON output
-q, --quiet	Suppress spinners (implies --json)

Auth resolves: --api-key flag > VALYU_API_KEY env > stored config (valyu login).

Deliverables — generated files alongside the report

deepresearch can produce CSV / XLSX / PPTX / DOCX / PDF files alongside the markdown report. Use this when the user wants both a narrative and machine-parseable data.

Passing deliverables — two shapes:

1. String (natural language, lets the agent pick the file type)

   --deliverable "CSV of Phase 3 CAR-T trials: NCT ID, sponsor, indication, phase, enrollment, endpoint, status"
   

2. Object in a JSON file (pin file type + columns) via --deliverables-file <path>:

   [
     { "type": "csv",  "description": "Top 20 Series A AI startups 2026",
       "columns": ["company", "founders", "hq_city", "round_size_usd", "round_date", "lead_investor"] },
     { "type": "xlsx", "description": "Investor landscape: top VCs leading AI Series A rounds" },
     "One-page PDF executive summary of the landscape"
   ]
   

   The array can mix objects and plain strings. Object type must be one of: csv, xlsx, pptx, docx, pdf.

--deliverable is repeatable and merges with --deliverables-file. Base mode price covers 1 deliverable; each additional adds $0.10 (16 credits).

Common knowledge-work recipes:

Use case	Example
PE / M&A target list	--deliverable "CSV of targets: company, HQ, revenue, EBITDA, owner, last financing"
Drug candidate shortlist	--deliverable "XLSX of molecules: name, target, MoA, developer, phase, NCT ID"
Clinical trial tracker	--deliverable "CSV of trials: NCT ID, sponsor, indication, phase, enrollment, endpoint, status"
Financial peer comp	--deliverable "XLSX comparing revenue, margin, growth across peer group"
GTM account list	--deliverable "CSV of accounts: company, website, HQ, signals, key people, last funding"
Competitive deck	--deliverable "PPTX one slide per competitor + positioning matrix + conclusion"
Patent landscape	--deliverable "CSV of patents: number, assignee, filing date, title, forward citations"

Details + download recipe: references/deepresearch.md

Recipes by domain

Private equity / DD

# Target DD brief + management CSV
valyu deepresearch create \
  "<Target Co> - DD brief: management, loan book, regional position, regulatory posture" \
  --mode heavy \
  --deliverable "CSV of top management: name, title, tenure, prior roles, notable transactions" \
  --deliverable "CSV of loan book concentration: sector, geography, approximate % of portfolio" \
  --watch

Finance / equity research

valyu deepresearch create \
  "NVDA Q4 earnings: guidance, datacenter segment, gross margin trajectory, forward risks" \
  --report-format "Sell-side style 2-page brief with peer comparison table" \
  --watch

Healthcare / life sciences

# Drug candidate landscape + XLSX
valyu deepresearch create \
  "Clinical-stage oral GLP-1 agonists in obesity indication" \
  --research-strategy "Prioritize ClinicalTrials.gov, FDA labels, PubMed abstracts over press releases" \
  --deliverable "XLSX: molecule, developer, mechanism, phase, indication, enrollment, NCT ID, ChEMBL ID" \
  --deliverable "One-page PDF ranking top 5 by commercial promise" \
  --watch

# Clinical trial tracker
valyu deepresearch create \
  "Phase 3 CAR-T trials in solid tumors currently recruiting" \
  --mode fast \
  --deliverable "CSV: NCT ID, sponsor, indication, target antigen, phase, enrollment, start date, primary endpoint, status" \
  --watch

GTM / sales / recruiting

valyu deepresearch create \
  "Series A/B AI infrastructure startups in NYC hiring platform engineers" \
  --country US \
  --deliverable "CSV: company, website, founders, HQ, last round size/date/lead, product one-liner, open platform engineering roles" \
  --watch

Competitive / market research

valyu deepresearch create \
  "Competitive landscape of enterprise AI coding assistants" \
  --mode heavy \
  --deliverable "PPTX: title + one slide per competitor (product, pricing, funding, customers, differentiation) + positioning matrix + conclusion" \
  --deliverable "CSV feature matrix across 12 dimensions" \
  --watch

When to use which command

User intent	Command
Quick factual question with citations	valyu answer "..."
Find papers / filings / trials / patents on a topic	valyu search <type> "..."
Pull clean text from a URL (or extract structured data)	valyu contents <url> [--structured]
Comprehensive research + cited report (± deliverables)	valyu deepresearch create "..."
Repeatable research from a saved template (e.g. company profile, IC memo)	valyu workflows run <slug> --param key=value
Discover available research templates	valyu workflows list
Many parallel deepresearch tasks with shared config	valyu batch create ...
Discover available proprietary data sources	valyu sources list
Provision a budget-capped key for a sub-agent	valyu account keys create --name agent --cap 5
Check credit balance / add credits	valyu account balance / valyu account topup 25
See what datasets this key can reach (replan on 403)	valyu account datasets
Upgrade the CLI itself	valyu upgrade

Search types (for valyu search <type>)

Type	Sources	Best for
web	Web	General lookups, current events
news	News outlets	Breaking stories, recent coverage
paper	arXiv, PubMed, bioRxiv, medRxiv	Academic research
bio	PubMed, bioRxiv, medRxiv, ClinicalTrials.gov, FDA labels	Life sciences / clinical
finance	SEC filings, stocks, earnings, balance sheet, cashflow, insider, crypto, forex	Financial data
sec	SEC filings only	10-K / 10-Q / 8-K research
patent	Global patents	IP / patent landscape
economics	BLS, FRED, World Bank, USAspending	Macro / economic indicators

Deep research modes

Mode	Time	Price	Use
instant	under 30 s	$0.05 (8 credits)	Quick answers with a compact cited report (no HITL; not available for batches)
fast	~5 min	$0.15625 (25 credits)	Quick lookups, structured extraction, high-volume batches
standard	~10-20 min	$0.625 (100 credits)	Most research tasks (default)
heavy	~60 min	$3.125 (500 credits)	Deep analysis, comparative reports, DD briefs
max	up to ~2 hrs	$15.625 (2,500 credits)	Exhaustive research, maximum depth

Common mistakes

#	Mistake	Fix
1	Using valyu research	The command is valyu deepresearch
2	Polling status in a tight loop	Use valyu deepresearch watch <id> (5s internal poll)
3	--structured + --output-format markdown	Structured replaces markdown/PDF. Use deliverables for "report + structured data". Only toon can accompany a structured schema.
4	Over-scoping with --include-source	Let the agent pick sources — it picks well. Only use --include-source when you must narrow to a specific dataset, never as a default.
5	Vague deliverable descriptions	Specify columns, units, filters explicitly (e.g. "NCT ID, sponsor (company), enrollment (integer, actual)")
6	Not using -q in pipelines	-q suppresses spinners and forces JSON
7	Expecting synchronous deep research	create returns immediately; use --watch or poll status
8	Watching by ID that's already completed	watch returns instantly with the final result

When to load each reference

• Deep research / deliverables / HITL / structured output → references/deepresearch.md
• Workflows (reusable research templates) → references/workflows.md
• Search (web / paper / finance / sec / bio / patent / economics / news) → references/search.md
• AI answer (answer) → references/answer.md
• URL content extraction (contents) → references/contents.md
• Auth, profiles, login (device flow) → references/auth.md
• Account: keys, budget caps, balance, top-ups, datasets → references/account.md
• Error codes → references/error-codes.md