Valyu CLI

Best for: using Valyu yourself. Search, deep research, content extraction, and answers from your terminal - and inside AI coding agents.

Paste into your AI coding agent to install and use the Valyu CLI.

Open in Cursor

Installation

cURL (macOS/Linux)
Homebrew
npm
PowerShell (Windows)

curl -fsSL https://get.valyu.ai | bash

brew install valyuAI/cli/valyu

npm install -g @valyu/cli

Requires Node.js 20+.

irm https://get.valyu.ai/install.ps1 | iex

The cURL, Homebrew, and PowerShell methods install standalone binaries that do not require Node.js.

Overview

The Valyu CLI brings Valyu’s full platform to your terminal - search, deep research, content extraction, and AI-powered answers across web and specialised data sources. It’s agent-native, built for use inside AI coding agents like Claude Code, Cursor, and Windsurf, but equally powerful as a standalone tool for knowledge workers who prefer the terminal. Key features:

Deep research - Generate comprehensive research reports with human-in-the-loop review on plans, sources, and outlines
Batch research - Run multiple research queries in parallel
AI-powered answers - Streaming answers with real-time source citations
Content extraction - Pull clean content from any URL with optional summarization and structured output
Search - Web and specialised sources including academic, financial, biomedical, patents, SEC filings, economics, and news
Agent-native - Auto-detects non-TTY environments and outputs structured JSON for piping and scripting
Stdin support - Pipe queries from other tools directly into Valyu
Account management - Provision budget-capped API keys, check your balance, top up, and rotate or revoke keys, from the terminal or programmatically

Authentication

Run valyu login to authenticate. It opens your browser, you approve the request, and the CLI mints a scoped val_ key and stores it locally - there is nothing to copy and paste:

valyu login

Use --no-browser to print the URL and code instead (useful for headless or agent environments), or request specific management scopes with --scope:

valyu login --no-browser
valyu login --scope "account:read keys:read keys:write billing:read"

For CI or scripting, log in with an existing key or use an environment variable:

# Existing key
valyu login --key val_xxx

# Environment variable
export VALYU_API_KEY="val_xxx"

# Per-command override
valyu search web "query" --api-key val_xxx

Key precedence: --api-key flag, then your valyu login key, then VALYU_API_KEY. A logged-in key takes precedence over the environment variable, so you don’t need to unset VALYU_API_KEY after logging in.

Don’t have a key yet? Sign up at platform.valyu.ai for $10 free credits ($20 with a work email). The CLI supports multiple named profiles for switching between accounts:

valyu login --profile work
valyu login --profile personal
valyu search web "query" --profile work

Commands

Search

Search across web and specialised data sources:

valyu search web "latest AI developments"
valyu search paper "transformer architecture improvements"
valyu search finance "AAPL quarterly earnings"
valyu search bio "CRISPR gene therapy clinical trials"
valyu search patent "solid-state battery technology"
valyu search sec "Tesla 10-K risk factors"
valyu search economics "US unemployment rate trends"
valyu search news "tech industry updates"

Options:

-n, --limit <number> - Number of results (default: 10)
--max-price <number> - Maximum price per result

Answer

Get AI-powered answers with streaming and source citations:

valyu answer "What are the latest advances in quantum computing?"
valyu answer "Summarize recent FDA drug approvals" --fast

In TTY mode, the answer streams in real-time with formatted citations. In non-TTY mode (piping, scripts), it outputs a single JSON object.

Extract clean content from web pages:

valyu contents https://example.com/article
valyu contents https://example.com --summary
valyu contents https://example.com --summary "Focus on pricing" --length short
valyu contents https://example.com --structured '{"title": "string", "price": "number"}'

Accepts up to 10 URLs per request.

Deep research

Generate comprehensive research reports:

# Start a research task
valyu deepresearch create "AI market trends 2025" --mode standard

# Watch progress (auto-finds latest task)
valyu deepresearch watch

# List all tasks
valyu deepresearch list

# Other subcommands
valyu deepresearch status <id>
valyu deepresearch cancel <id>
valyu deepresearch update <id> "Focus more on healthcare AI"
valyu deepresearch share <id>
valyu deepresearch delete <id>

Research modes: fast (~5 min), standard (~10-20 min), heavy (~60 min), max (~90 min). The watch command supports human-in-the-loop interactions where the research agent pauses for your input on planning questions, research plans, sources, and report outlines.

Batch research

Run multiple research queries in parallel:

valyu batch create "AI in healthcare" "AI in finance" "AI in education"
valyu batch watch
valyu batch list
valyu batch status <id>
valyu batch add <id> "AI in manufacturing"
valyu batch cancel <id>

Browse data sources

View all available data sources and their pricing:

valyu sources
valyu sources --category healthcare
valyu sources --category markets

Account and API keys

Manage your organisation’s keys, balance, and budgets, all self-serve from the terminal. An agent can provision its own scoped, budget-capped key, use Valyu, and revoke it when it is done.

# Org, tier, calling key, and scopes
valyu account whoami

# Credit balance and usage
valyu account balance

# Datasets this key/org can reach, plus the tier ladder
valyu account datasets

Create and manage API keys:

# List keys for the organisation
valyu account keys list

# Create a budget-capped key - the headline pattern for agents
valyu account keys create --name agent --cap 5

# Rotate a key (revoke the old secret, mint a new one with the same settings)
valyu account keys rotate <id>

# Revoke a key immediately
valyu account keys revoke <id>

keys create options:

--cap <usd> - hard spend ceiling for the key (omit for uncapped). Once a key reaches its cap, further requests are rejected.
--window <total|monthly> - whether the cap is a running total or resets monthly (default: total).
--scopes <list> - comma-separated management scopes (see below). Search and data access is automatic, so omit this for a search-only key.
--rate-limit <rpm> - requests-per-minute limit.
--expires <iso> - expiry as an ISO 8601 timestamp.

Top up credits:

valyu account topup 25

Charges the card on file, or returns a Stripe Checkout link if there is none. Management scopes gate account management only - search and data access is always automatic:

Scope	Grants
`account:read`	Read org, tier, and datasets
`keys:read`	List keys
`keys:write`	Create, rotate, and revoke keys
`billing:read`	Read balance and usage
`billing:write`	Top up credits

A key can only create child keys with a subset of its own scopes and a cap within its remaining budget, so you can hand a scoped, budget-capped key to a sub-agent and trust it cannot exceed those limits.

Utility commands

valyu whoami          # Check authentication status
valyu doctor          # Run diagnostic checks
valyu open platform   # Open Valyu platform in browser
valyu open docs       # Open documentation

Agent integration

The CLI is designed to work seamlessly inside AI coding agents. When stdout is not a TTY (e.g. when called by an agent or piped), all commands automatically output structured JSON without needing the --json flag. This means agents can call Valyu directly:

# Agent calls - auto-outputs JSON
valyu search finance "AAPL" | jq '.results[].title'
echo "quantum computing breakthroughs" | valyu search paper
echo "https://example.com" | valyu contents --summary

The CLI also ships with an Agent Skill that teaches AI coding agents how to use it without an MCP server:

npx skills add @valyu/cli

Global flags

Flag	Description
`--api-key <key>`	Override stored API key for a single request
`-p, --profile <name>`	Use a named credential profile
`--json`	Force JSON output (automatic in non-TTY)
`-q, --quiet`	Suppress spinners and progress, implies `--json`
`-v, --version`	Show CLI version

Search types

Type	Description	Example sources
`web`	General web search	Real-time web content
`paper`	Academic papers	arXiv, PubMed, scholarly journals
`finance`	Financial data	Stock prices, earnings, balance sheets
`bio`	Biomedical research	PubMed, clinical trials, FDA drug labels, ChEMBL
`patent`	Patent databases	USPTO, global patent records
`sec`	SEC regulatory filings	10-K, 10-Q, 8-K documents
`economics`	Economic indicators	BLS, FRED, World Bank
`news`	News articles	Real-time news sources

Agents & MCP

Automation Platforms

Work Platforms

Framework SDKs

Community SDKs

LLM Providers

Installation

Overview

Authentication

Commands

Search

Answer

Contents

Deep research

Batch research

Browse data sources

Account and API keys

Utility commands

Agent integration

Global flags

Search types

Additional resources

GitHub Repository

npm Package

Get API Key

API Reference

​Installation

​Overview

​Authentication

​Commands

​Search

​Answer

​Contents

​Deep research

​Batch research

​Browse data sources

​Account and API keys

​Utility commands

​Agent integration

​Global flags

​Search types

​Additional resources

GitHub Repository

npm Package

Get API Key

API Reference

Installation

Overview

Authentication

Commands

Search

Answer

Contents

Deep research

Batch research

Browse data sources

Account and API keys

Utility commands

Agent integration

Global flags

Search types

Additional resources