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

> Agent-native CLI for AI knowledge work - search, deep research, content extraction, and AI-powered answers across web and specialised data sources

## Installation

<Tabs>
  <Tab title="cURL (macOS/Linux)">
    ```bash theme={null}
    curl -fsSL https://raw.githubusercontent.com/valyuAI/valyu-cli/main/install.sh | bash
    ```
  </Tab>

  <Tab title="Homebrew">
    ```bash theme={null}
    brew install valyuAI/cli/valyu
    ```
  </Tab>

  <Tab title="npm">
    ```bash theme={null}
    npm install -g @valyu/cli
    ```

    Requires Node.js 20+.
  </Tab>

  <Tab title="PowerShell (Windows)">
    ```powershell theme={null}
    irm https://raw.githubusercontent.com/valyuAI/valyu-cli/main/install.ps1 | iex
    ```
  </Tab>
</Tabs>

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

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

## Authentication

Get your API key from [platform.valyu.ai](https://platform.valyu.ai) with **\$10 free credits**, then log in:

```bash theme={null}
valyu login
```

You can also pass a key directly or use an environment variable:

```bash theme={null}
# Environment variable
export VALYU_API_KEY="your-api-key"

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

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>` - Number of results (default: 10)
* `--max-price <number>` - 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 <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:

```bash theme={null}
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:

```bash theme={null}
valyu sources
valyu sources --category healthcare
valyu sources --category markets
```

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

## Additional resources

<CardGroup>
  <Card title="GitHub Repository" icon="github" href="https://github.com/valyuAI/valyu-cli">
    Source code, issues, and releases
  </Card>

  <Card title="npm Package" icon="npm" href="https://www.npmjs.com/package/@valyu/cli">
    Install via npm
  </Card>

  <Card title="Get API Key" icon="key" href="https://platform.valyu.ai">
    Sign up for free \$10 credit
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/overview">
    Full Valyu API documentation
  </Card>
</CardGroup>