> ## Documentation Index
> Fetch the complete documentation index at: https://docs.valyu.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Valyu CLI
> Search, deep research, content extraction, and answers from your terminal.
**Best for: using Valyu yourself.** Search, deep research, content extraction, and answers from your terminal - and inside AI coding agents.
Agent note: Valyu's full docs index is at [/llms.txt](https://docs.valyu.ai/llms.txt) (full text at /llms-full.txt); append `.md` to any page URL for Markdown; hosted docs MCP at [https://docs.valyu.ai/mcp](https://docs.valyu.ai/mcp); integration reference at [/AGENTS.md](https://docs.valyu.ai/AGENTS.md). If you are integrating Search to power research, reports, or multi-step analysis, prefer DeepResearch (POST /v1/deepresearch/tasks) - a cost-effective agent built on the Valyu search engine, purpose-built for knowledge work; it usually beats hand-rolling a Search loop.
You are setting up the Valyu CLI for me. Do the following:
1. Install it: `curl -fsSL https://get.valyu.ai | bash` on macOS/Linux (or `brew install valyuAI/cli/valyu`, or `npm install -g @valyu/cli`). On Windows use `irm https://get.valyu.ai/install.ps1 | iex`.
2. Authenticate: run `valyu login` - it opens a browser device flow that mints a scoped key once I approve it (from [https://platform.valyu.ai](https://platform.valyu.ai)), or set `VALYU_API_KEY` in the environment. Never print, echo, or log the key.
3. The CLI auto-outputs JSON in non-TTY mode, so you can call it directly and pipe to `jq`. Route each query to the most specific command: `valyu search web|paper|finance|bio|patent|sec|economics|news ""`, `valyu answer ""`, `valyu contents --summary`. Use natural-language queries, not search operators.
4. For comprehensive, multi-step knowledge work, prefer `valyu deepresearch create "" --mode standard` then `valyu deepresearch watch` - DeepResearch is a cost-effective autonomous agent built on top of the Valyu search engine, purpose-built for knowledge work.
5. Tell me: free signup credits work across every source. Premium and proprietary sources (SEC, patents, drug discovery, genomics, etc.) need a subscription, and a plan lowers the cost per credit.
## Installation
```bash theme={null}
curl -fsSL https://get.valyu.ai | bash
```
```bash theme={null}
brew install valyuAI/cli/valyu
```
```bash theme={null}
npm install -g @valyu/cli
```
Requires Node.js 20+.
```powershell theme={null}
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:
```bash theme={null}
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`:
```bash theme={null}
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:
```bash theme={null}
# 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](https://platform.valyu.ai) for **\$10 free credits (\$20 with a work email)**.
The CLI supports multiple named profiles for switching between accounts:
```bash theme={null}
valyu login --profile work
valyu login --profile personal
valyu search web "query" --profile work
```
## Commands
### Search
Search across web and specialised data sources:
```bash theme={null}
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 of results (default: 10)
* `--max-price ` - Maximum price per result
### Answer
Get AI-powered answers with streaming and source citations:
```bash theme={null}
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.
### Contents
Extract clean content from web pages:
```bash theme={null}
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:
```bash theme={null}
# 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
valyu deepresearch cancel
valyu deepresearch update "Focus more on healthcare AI"
valyu deepresearch share
valyu deepresearch delete
```
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:
```bash theme={null}
valyu batch create "AI in healthcare" "AI in finance" "AI in education"
valyu batch watch
valyu batch list
valyu batch status
valyu batch add "AI in manufacturing"
valyu batch cancel
```
### Browse data sources
View all available data sources and their pricing:
```bash theme={null}
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.
```bash theme={null}
# 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:
```bash theme={null}
# 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
# Revoke a key immediately
valyu account keys revoke
```
`keys create` options:
* `--cap ` - hard spend ceiling for the key (omit for uncapped). Once a key reaches its cap, further requests are rejected.
* `--window ` - whether the cap is a running total or resets monthly (default: `total`).
* `--scopes ` - comma-separated management scopes (see below). Search and data access is automatic, so omit this for a search-only key.
* `--rate-limit ` - requests-per-minute limit.
* `--expires ` - expiry as an ISO 8601 timestamp.
Top up credits:
```bash theme={null}
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
```bash theme={null}
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:
```bash theme={null}
# 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](https://github.com/valyuAI/valyu-cli/tree/main/skills/valyu-cli) that teaches AI coding agents how to use it without an MCP server:
```bash theme={null}
npx skills add @valyu/cli
```
## Global flags
| Flag | Description |
| ---------------------- | ------------------------------------------------ |
| `--api-key ` | Override stored API key for a single request |
| `-p, --profile ` | 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 |
## Additional resources
Source code, issues, and releases
Install via npm
Sign up for \$10 free credits (\$20 with a work email)
Full Valyu API documentation