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) ```bash # 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`. ```bash 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](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)** ```bash --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>`: ```json [ { "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:** | 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](references/deepresearch.md) ## Recipes by domain ### Private equity / DD ```bash # 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 ```bash 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 ```bash # 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 ```bash 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 ```bash 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 | |------|------|-------|-----| | `fast` | ~5 min | $0.10 | Quick lookups, structured extraction, high-volume batches | | `standard` | ~10-20 min | $0.50 | Most research tasks (default) | | `heavy` | ~60 min | $2.50 | Deep analysis, comparative reports, DD briefs | | `max` | up to ~2 hrs | $15.00 | 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](references/deepresearch.md) - **Workflows (reusable research templates)** → [references/workflows.md](references/workflows.md) - **Search (web / paper / finance / sec / bio / patent / economics / news)** → [references/search.md](references/search.md) - **AI answer (`answer`)** → [references/answer.md](references/answer.md) - **URL content extraction (`contents`)** → [references/contents.md](references/contents.md) - **Auth, profiles, login (device flow)** → [references/auth.md](references/auth.md) - **Account: keys, budget caps, balance, top-ups, datasets** → [references/account.md](references/account.md) - **Error codes** → [references/error-codes.md](references/error-codes.md)