Valyu CLI

Install the Valyu CLI to search the web and specialist sources, extract URLs and run DeepResearch from your terminal, with JSON output for coding agents.

Use the CLI to search, extract URLs and run research from your terminal. Commands also return JSON for scripts and coding agents. For automatic installation and login, use Onboard your agents.

Installation

cURL (macOS/Linux)

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

Homebrew

brew install valyuAI/cli/valyu

npm

npm install -g @valyu/cli

Requires Node.js 20+.

PowerShell (Windows)

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

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

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 company 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

Make your first call

valyu search web "battery recycling companies in Europe" -n 5

Inspect the source URLs and returned content. Then choose Search for individual retrievals or DeepResearch when you want a finished report.

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> - Cap on the cost of the whole request; see pricing

Contents

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 synchronously. For 11-50 URLs, add --async --watch to submit a job and wait for its results.

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, standard, heavy, and max. Duration depends on the task and mode; see DeepResearch for mode guidance.

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 your balance in dollars (minimum $10):

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 the balance

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), research and retrieval commands 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

Browse data sources for coverage, or run valyu sources to inspect the live catalogue.

Additional resources

GitHub Repository

Source code, issues, and releases

npm Package

Install via npm

Get API Key

Sign up for $10 free credits ($20 with a company email)

API Reference

Full Valyu API documentation