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

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.

Common knowledge-work recipes:

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

Search types (for valyu search <type>)

Deep research modes

Common mistakes

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