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

エージェントプロトコル（主要なパターン）

# 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

セルフプロビジョニング（エージェント向けのゼロから最初の呼び出しまで）

valyu login はデフォルトでブラウザデバイスフローを使用します。スコープ付きの val_ キーを発行して保存するため、エージェントが人間にシークレットの貼り付けを求める必要はありません。--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

予算上限付きエージェントキーは、account の主要なパターンです。--cap 5 を指定すると、データプレーンが 402 spend_cap_reached を返すまでに最大 5 ドルを使用できるキーを発行します。シークレットは一度だけ表示されます。要求するスコープや上限は、呼び出し元のキーの権限を超えることはありません（サーバー側で適用されます）。詳細は、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 ファイルを生成できます。ナラティブと機械で解析可能なデータの両方が必要な場合に使用します。

成果物の指定方法 — 2 つの形式：

1. 文字列（自然言語。ファイル形式はエージェントが選択）

   --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 件分が含まれます。追加するごとに 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

ドメイン別レシピ

プライベートエクイティ / 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

金融 / 株式調査

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 "..."
保存済みテンプレート（例：企業プロフィール、IC メモ）を使った再現可能な調査	valyu workflows run <slug> --param key=value
利用可能な調査テンプレートを確認する	valyu workflows list
共通設定を使って多数の並列ディープリサーチタスクを実行する	valyu batch create ...
利用可能な独自データソースを確認する	valyu sources list
サブエージェント用に上限付き予算のキーを発行する	valyu account keys create --name agent --cap 5
クレジット残高を確認する／クレジットを追加する	valyu account balance / valyu account topup 25
このキーでアクセスできるデータセットを確認する（403 が発生したら計画を見直す）	valyu account datasets
CLI 自体をアップグレードする	valyu upgrade

検索タイプ（valyu search <type> 用）

タイプ	ソース	最適な用途
web	Web	一般的な検索、時事情報
news	ニュースメディア	速報、最近の報道
paper	arXiv, PubMed, bioRxiv, medRxiv	学術研究
bio	PubMed, bioRxiv, medRxiv, ClinicalTrials.gov, FDA labels	ライフサイエンス／臨床
finance	SEC filings, stocks, earnings, balance sheet, cashflow, insider, crypto, forex	金融データ
sec	SEC filings only	10-K / 10-Q / 8-K の調査
patent	Global patents	知的財産／特許の動向
economics	BLS, FRED, World Bank, USAspending	マクロ経済／経済指標

ディープリサーチのモード

モード	所要時間	料金	用途
instant	30 秒未満	$0.05（8 クレジット）	コンパクトな引用付きレポートによる簡単な回答（HITL なし。バッチでは利用不可）
fast	約 5 分	$0.15625（25 クレジット）	簡単な検索、構造化抽出、大量バッチ
standard	約 10～20 分	$0.625（100 クレジット）	ほとんどの調査タスク（デフォルト）
heavy	約 60 分	$3.125（500 クレジット）	詳細な分析、比較レポート、デューデリジェンス概要
max	最長約 2 時間	$15.625（2,500 クレジット）	徹底的な調査、最大限の深度

よくある間違い

#	間違い	対処法
1	valyu research を使う	コマンドは valyu deepresearch です
2	status を短い間隔で繰り返し確認する	valyu deepresearch watch <id> を使います（内部で 5 秒間隔で確認）
3	--structured と --output-format markdown を併用する	構造化出力は Markdown／PDF に置き換わります。「レポート＋構造化データ」には 成果物 を使います。構造化スキーマと併用できるのは toon のみです。
4	--include-source で範囲を絞り込みすぎる	ソースの選択はエージェントに任せてください。適切に選択されます。特定のデータセットに絞る必要がある場合に限って --include-source を使い、デフォルトでは使わないでください。
5	成果物の説明が曖昧	列、単位、フィルターを明確に指定します（例：「NCT ID、スポンサー（企業）、登録数（整数、実績値）」）。
6	パイプラインで -q を使わない	-q はスピナーを非表示にし、JSON を強制します
7	ディープリサーチが同期実行されると想定する	create はすぐに戻ります。--watch を使うか、status を確認してください
8	すでに完了した ID を指定して監視する	watch は最終結果を即座に返します

各リファレンスの読み込みタイミング

• 詳細な調査／成果物／HITL／構造化出力 → references/deepresearch.md
• ワークフロー（再利用可能な調査テンプレート） → references/workflows.md
• 検索（ウェブ／論文／金融／証券取引委員会／バイオ／特許／経済／ニュース） → references/search.md
• AI による回答（answer） → references/answer.md
• URL コンテンツの抽出（contents） → references/contents.md
• 認証、プロフィール、ログイン（デバイスフロー） → references/auth.md
• アカウント：キー、予算上限、残高、チャージ、データセット → references/account.md
• エラーコード → references/error-codes.md