valyu-cli

Valyu CLI

通过终端获取有依据且附带引用的知识工作答案——包括 DD 简报、财报分析、候选药物清单、临床试验跟踪表、ICP 客户名单、专利全景分析和竞争研究。快速查询（search、answer、contents）采用同步运行，深入工作流（deepresearch）采用异步运行。

命令树

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 协议（关键模式）

# 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

自助配置（Agent 从零到首次调用）

valyu login 默认使用浏览器设备授权流程——它会生成并存储一个有范围限制的 val_ 密钥，因此 Agent 无需请求人工粘贴密钥。在 --json 模式下，它会流式输出由换行符分隔的事件（device_code → auth_waiting → auth_success）；向用户展示 verification_uri_complete，并持续读取各行，直到出现 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

受预算上限约束的 Agent 密钥是核心的 account 模式：--cap 5 会生成一个最多可支出 $5 的密钥，超过后数据平面会返回 402 spend_cap_reached。密钥只会显示一次。请求的范围和上限绝不会超过调用密钥自身的范围和上限（由服务器强制执行）。完整详情：references/account.md。

全局标志

标志	说明
--api-key <key>	覆盖本次调用使用的 API 密钥
-p, --profile <name>	选择已存储的配置文件
--json	强制使用 JSON 输出
-q, --quiet	隐藏加载动画（隐含 --json）

身份验证优先级：--api-key 标志 > VALYU_API_KEY 环境变量 > 已存储的配置（valyu login）。

交付物——与报告一同生成的文件

deepresearch 可以在 Markdown 报告旁生成 CSV / XLSX / PPTX / DOCX / PDF 文件。当用户同时需要叙述性内容和可供机器解析的数据时，请使用此功能。

传递交付物——两种形式：

1. 字符串（自然语言，由 Agent 选择文件类型）

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

2. JSON 文件中的对象（指定文件类型和列），通过 --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"
   ]
   

   数组可以混合包含对象和普通字符串。对象的 type 必须为以下之一：csv、xlsx、pptx、docx、pdf。

--deliverable 可重复使用，并会与 --deliverables-file 合并。基础模式价格包含 1 个交付物；每增加 1 个需加 $0.10（16 积分）。

常见知识工作用法：

用例	示例
PE / M&A 目标名单	--deliverable "CSV of targets: company, HQ, revenue, EBITDA, owner, last financing"
候选药物清单	--deliverable "XLSX of molecules: name, target, MoA, developer, phase, NCT ID"
临床试验跟踪表	--deliverable "CSV of trials: NCT ID, sponsor, indication, phase, enrollment, endpoint, status"
金融同业比较	--deliverable "XLSX comparing revenue, margin, growth across peer group"
GTM 客户名单	--deliverable "CSV of accounts: company, website, HQ, signals, key people, last funding"
竞争分析演示文稿	--deliverable "PPTX one slide per competitor + positioning matrix + conclusion"
专利全景分析	--deliverable "CSV of patents: number, assignee, filing date, title, forward citations"

详情和下载用法：references/deepresearch.md

按领域分类的用法

私募股权 / 尽职调查

# 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

金融 / 股票研究

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

医疗健康 / 生命科学

# 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 / 销售 / 招聘

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

竞争 / 市场研究

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

何时使用哪条命令

用户意图	命令
获取带引用的快速事实性回答	valyu answer "..."
查找某个主题的论文／申报文件／临床试验／专利	valyu search <type> "..."
从 URL 提取干净文本（或提取结构化数据）	valyu contents <url> [--structured]
开展全面研究并生成带引用的报告（可附交付物）	valyu deepresearch create "..."
使用已保存的模板重复开展研究（例如公司简介、投资委员会备忘录）	valyu workflows run <slug> --param key=value
查看可用的研究模板	valyu workflows list
使用共享配置并行执行多个深度研究任务	valyu batch create ...
查看可用的专有数据源	valyu sources list
为子 Agent 配置有预算上限的密钥	valyu account keys create --name agent --cap 5
查看额度余额／添加额度	valyu account balance / valyu account topup 25
查看此密钥可访问的数据集（遇到 403 时重新规划）	valyu account datasets
升级 CLI 本身	valyu upgrade

深度研究模式

模式	耗时	价格	用途
instant	不到 30 s	$0.05（8 credits）	快速回答并附简洁的引用报告（无需 HITL；不适用于批量任务）
fast	~5 min	$0.15625（25 credits）	快速查询、结构化提取、高并发批量任务
standard	~10-20 min	$0.625（100 credits）	大多数研究任务（默认）
heavy	~60 min	$3.125（500 credits）	深度分析、对比报告、尽职调查简报
max	最长约 2 hrs	$15.625（2,500 credits）	穷尽式研究，深度最高

常见错误

#	错误	修正方法
1	使用 valyu research	正确命令是 valyu deepresearch
2	以极短间隔轮询 status	使用 valyu deepresearch watch <id>（内部每 5 s 轮询一次）
3	同时使用 --structured 和 --output-format markdown	结构化输出会取代 markdown／PDF。若要同时获取“报告 + 结构化数据”，请使用 deliverables。只有 toon 可以与结构化 schema 搭配使用。
4	通过 --include-source 过度限定范围	让 Agent 自行选择数据源——它很擅长此事。仅在 必须 将范围缩小到特定数据集时才使用 --include-source，不要将其作为默认选项。
5	交付物描述含糊	明确指定列、单位和筛选条件（例如“ NCT ID、赞助方（公司）、入组人数（整数，实际值）”）
6	在管道中未使用 -q	-q 会隐藏加载动画并强制使用 JSON
7	期待深度研究同步完成	create 会立即返回；请使用 --watch 或轮询 status
8	监视已完成任务的 ID	watch 会立即返回最终结果

何时加载各参考文档

• 深度研究／交付成果／HITL／结构化输出 → references/deepresearch.md
• 工作流（可复用的研究模板） → references/workflows.md
• 搜索（网络／论文／金融／sec／生物／专利／经济学／新闻） → references/search.md
• AI 答案（answer） → references/answer.md
• URL 内容提取（contents） → references/contents.md
• 身份验证、配置文件、登录（设备流程） → references/auth.md
• 账户：密钥、预算上限、余额、充值、数据集 → references/account.md
• 错误代码 → references/error-codes.md