DEV Community

Cover image for Understanding Valyu: AI-Native Search, and a CLI Tool to Experiment Faster
Abednego Edet
Abednego Edet

Posted on

Understanding Valyu: AI-Native Search, and a CLI Tool to Experiment Faster

#rag #ai #opensource

AI systems are increasingly judged not by how well they generate text, but by how accurately they retrieve and reason over information. This is where search infrastructure becomes critical. Traditional search APIs were built for humans. Valyu is built for AI.

This article introduces what Valyu is, what it enables, and then walks through an unofficial CLI tool I built to make experimenting with Valyu faster and more practical from the command line.

What is Valyu?

Valyu is an AI-native search and retrieval platform designed specifically for modern AI workloads such as:

  • Retrieval-Augmented Generation (RAG)
  • AI agents
  • Research automation
  • Data-grounded LLM applications

Instead of returning loosely ranked links, Valyu focuses on structured, relevance-optimized results that are easier for AI systems to consume and reason over.

At a high level, Valyu provides:

  • Unified access to web, academic, proprietary, and structured data
  • Results optimized for LLM context windows
  • Rich metadata and content extraction
  • A single API designed to replace fragmented search pipelines

The core idea is simple: if AI systems are going to reason accurately, they need search results that are already structured, filtered, and relevance-aware.

Why Valyu Matters for Developers

When building AI systems today, developers often spend significant time stitching together:

  • Web search APIs
  • Scrapers
  • Embedding pipelines
  • Ranking and filtering logic

Valyu reduces that complexity by acting as a search abstraction layer for AI. Instead of optimizing for human browsing, it optimizes for downstream reasoning.

This makes it especially useful when:

  • Building RAG pipelines
  • Powering autonomous agents
  • Running repeatable research tasks
  • Experimenting with AI workflows that depend on up-to-date or external knowledge

Experimenting with Valyu

Valyu provides SDKs and APIs that integrate cleanly into applications. However, when you’re still exploring the platform, writing code for every experiment can slow things down. This is where quick, disposable workflows become valuable.

New Valyu users receive $10 in free credits, which makes it easy to experiment, test ideas, and understand how the platform behaves before committing it to production use. That free tier pairs well with lightweight tools that reduce setup friction.

To make experimentation easier, I built an unofficial command-line tool called valyu-cli.

This tool is not an official Valyu product. It exists purely to simplify the process of interacting with Valyu during exploration, testing, and local workflows.

Instead of writing a script or setting up a full project, the CLI lets you issue queries, extract content, and run research tasks directly from your terminal.

GitHub logo ed3t / valyu-cli

CLI for Valyu DeepSearch API

∇ Valyu CLI

npm License Release

CLI for Valyu's DeepSearch API.
Search, extract contents, and run DeepResearch from the terminal. Built on the official valyu-js SDK.

Installation

yarn global add valyu-cli
# or
npm install -g valyu-cli
Enter fullscreen mode Exit fullscreen mode

Run without installing:

npx valyu-cli search "your query"
Enter fullscreen mode Exit fullscreen mode

Requirements: Node.js 18+

Quick Start

# Set your API key (or use --api-key)
export VALYU_API_KEY="your-api-key"

# Search
valyu search "machine learning transformers" --max 5

# Extract content from URLs
valyu contents https://example.com --summary

# Create a DeepResearch task and wait for the result
valyu deep-research create "AI safety research summary" --wait
Enter fullscreen mode Exit fullscreen mode

Get your API key: Valyu Platform

Authentication

Environment variable (recommended):

export VALYU_API_KEY="your-api-key"
Enter fullscreen mode Exit fullscreen mode

Config file: Create ~/.valyu/config or .valyu/config in your project:

apiKey=your-api-key

Or use VALYU_API_KEY=your-api-key as the key name. The CLI reads apiKey or VALYU_API_KEY from the file.

Override per run:

valyu search "query
…
Enter fullscreen mode Exit fullscreen mode
View on GitHub

What the CLI Tool Does

The CLI wraps common Valyu API operations into simple terminal commands. Its main capabilities include:

  • Searching Valyu directly from the command line
  • Extracting structured content from URLs
  • Running DeepResearch tasks and waiting for results
  • Outputting results as JSON for scripting or storage

It is intentionally minimal and designed for developers who want fast feedback loops.

Installing the CLI

You can install the tool globally or run it on demand.

npm install -g valyu-cli
# or
yarn global add valyu-cli
Enter fullscreen mode Exit fullscreen mode

You can also run it without installing:

npx valyu-cli search "your query"
Enter fullscreen mode Exit fullscreen mode

Authentication

Set your Valyu API key as an environment variable:

export VALYU_API_KEY="your-api-key"
Enter fullscreen mode Exit fullscreen mode

Or via a config file:

~/.valyu/config
apiKey=your-api-key
Enter fullscreen mode Exit fullscreen mode

You can also override the key per command:

valyu -k "your-api-key" search "your query"
Enter fullscreen mode Exit fullscreen mode

Example Usage

Search Valyu 

valyu search "latest AI research trends" --max 5
Enter fullscreen mode Exit fullscreen mode

More advanced search (custom sources, filtering, and JSON output):

valyu search "transformer architecture improvements" \
  --type proprietary \
  --sources valyu/valyu-arxiv \
  --relevance 0.7 \
  --max 10 \
  --json --save search.json
Enter fullscreen mode Exit fullscreen mode

Extract structured content from a page 

valyu contents https://example.com --summary
Enter fullscreen mode Exit fullscreen mode

Custom summary prompt and longer extraction:

valyu contents https://example.com \
  --summary-prompt "Provide 5 key takeaways as bullet points." \
  --length medium
Enter fullscreen mode Exit fullscreen mode

Run DeepResearch and wait for completion 

valyu deep-research create "Overview of quantum computing" --wait
Enter fullscreen mode Exit fullscreen mode

Request markdown + PDF (the CLI prints the markdown output and the PDF URL if available):

valyu deep-research create "AI safety research summary" \
  --model heavy \
  --format markdown,pdf \
  --wait
Enter fullscreen mode Exit fullscreen mode

Check the status of a DeepResearch task later:

valyu deep-research status <task-id>
Enter fullscreen mode Exit fullscreen mode

All commands can output raw JSON, which makes the tool useful in shell scripts or lightweight pipelines. I built this CLI because I didn’t want to write code every time I wanted to understand how Valyu would respond to a query.

When you’re evaluating infrastructure tools, speed matters. Being able to run a command, inspect the output, tweak a query, and run it again makes it much easier to form an opinion about whether a platform fits your use case.

This tool exists purely to support that phase of work. If you end up using Valyu in production, the SDKs are the right place to be. If you’re still exploring, the CLI keeps things simple.

Advanced options (quick reference)

The CLI supports additional flags beyond the examples above.

Global flags (all commands):

  • -k, --api-key <key>: override API key for a single command
  • --json: output raw JSON (useful for scripting)
  • --save <path>: write output to a file
  • -v, --verbose: log request details to stderr
  • -q, --quiet: minimal output

Search flags:

  • -t, --type <all|web|proprietary|news>
  • -n, --max <1-100>
  • --sources <comma,separated> / --exclude-sources <comma,separated>
  • --relevance <0-1>
  • --max-price <number>
  • --start-date <YYYY-MM-DD> / --end-date <YYYY-MM-DD>
  • --length <short|medium|large|max>

Contents flags:

  • --summary / --summary-prompt "<instruction>"
  • --effort <normal|high|auto>
  • --length <short|medium|large|max>
  • --max-price <number> (USD)

DeepResearch flags:

  • -m, --model <fast|heavy>
  • --format markdown,pdf
  • --wait
  • --poll-interval <ms>

Final thoughts

Valyu solves a real problem in the AI ecosystem: search designed for reasoning systems, not browsers. If retrieval quality matters to your application, it’s worth understanding how it works.

The valyu-cli tool is a small, unofficial addition meant to make that exploration faster. Combined with Valyu’s free credits, it lowers the barrier to actually testing ideas instead of just reading documentation.

Links

Top comments (0)