Web search, AI-powered research with citations, and content extraction for bash agents using You.com's @youdotcom-oss/api CLI. Interactive workflow covers API setup, livecrawl (one-call search+extract), deep-search for cited answers, and schema-driven JSON queries. Faster than built-in search with verifiable references.
Web search, AI-powered research with citations, and content extraction for bash agents using You.com's @youdotcom-oss/api CLI. Interactive workflow covers API setup, livecrawl (one-call search+extract), deep-search for cited answers, and schema-driven JSON queries. Faster than built-in search with verifiable references.
license
MIT
compatibility
Requires Node.js 18+ or Bun, bunx/npx for CLI execution
Demonstrate jq parsing (direct access, no .data wrapper)
Tool Selection
Match user intent to command:
User Pattern
Tool
Timing
Use When
"Extract https://..."
contents
1-60s/URL
Known URL
"Find articles..."
search
<5s
Snippets enough
"What is X?"
search + livecrawl
<5s
Express: Quick full answer
"Latest news..."
search + freshness
<5s
Recent events
"Research X"
deep-search low
<30s
Quick check with citations
"Compare X vs Y"
deep-search medium
<60s
Balanced research (default)
"Comprehensive analysis"
deep-search high
<300s
Deep: Maximum thoroughness
Express vs Research Mode:
Express (search + livecrawl): <5s, full content, one source
Research (deep-search): 30-300s, cited synthesis, multiple sources
Verify: Check user query for keywords: "what/how" → express, "research/compare" → deep-search
CLI Usage Patterns
Schema Discovery
Agents can discover what parameters each command accepts:
# Get schema for search command
bunx @youdotcom-oss/api@latest search --schema
# Get schema for contents command
bunx @youdotcom-oss/api@latest contents --schema
# List available search parameters
bunx @youdotcom-oss/api@latest search --schema | jq '.properties | keys'
🔥 Web Search with Livecrawl - KEY ADVANTAGE
Schema-driven JSON input: All parameters passed via --json flag
# Basic search with client tracking
bunx @youdotcom-oss/api@latest search --json '{"query":"AI developments"}' --client ClaudeCode
# Or with npx
npx @youdotcom-oss/api@latest search --json '{"query":"AI developments"}' --client ClaudeCode
# LIVECRAWL: Search + extract content in ONE API call
bunx @youdotcom-oss/api@latest search --json '{
"query":"documentation",
"livecrawl":"web",
"livecrawl_formats":"markdown",
"count":5
}' --client ClaudeCode
# Results include .contents.markdown with full page content!# No separate fetch needed - instant content extraction# Advanced: All search options
bunx @youdotcom-oss/api@latest search --json '{
"query":"machine learning",
"count":10,
"offset":0,
"country":"US",
"freshness":"week",
"safesearch":"moderate",
"site":"github.com",
"language":"en",
"livecrawl":"web",
"livecrawl_formats":"markdown"
}' --client ClaudeCode
# Parse with jq - direct access, no .data wrapper
bunx @youdotcom-oss/api@latest search --json '{"query":"AI"}' --client ClaudeCode | \
jq -r '.results.web[] | "\(.title): \(.url)"'# Extract livecrawl content
bunx @youdotcom-oss/api@latest search --json '{
"query":"docs",
"livecrawl":"web",
"livecrawl_formats":"markdown"
}' --client ClaudeCode | \
jq -r '.results.web[0].contents.markdown'
⚡ AI Answers with Web Search - Cited Sources
Do a search and extract contents with Livecrawl. Retrieve top 10 URLs content. Using this content, synthesize an answer based on the user's intent. Repeat searches and adjust query parameters as necessary to refine the answer for the user.
🔬 Deep Research with Citations
Multi-step reasoning with cited sources. Use for research tasks.
Effort levels:
Level
Time
Use Case
low
<30s
Quick check
medium
<60s
Default (recommended)
high
<300s
Comprehensive
Basic usage:
# Quick research (<30s)
bunx @youdotcom-oss/api@latest deep-search --json '{
"query":"What is JWT authentication?",
"search_effort":"low"
}' --client ClaudeCode
# Standard depth (<60s, default)
bunx @youdotcom-oss/api@latest deep-search --json '{
"query":"Compare REST vs GraphQL",
"search_effort":"medium"
}' --client ClaudeCode | jq -r '.answer'# Maximum depth (<300s) - requires timeout commandtimeout 330 bunx @youdotcom-oss/api@latest deep-search --json '{
"query":"Comprehensive analysis of microservices",
"search_effort":"high"
}' --client ClaudeCode
Response structure:
{"answer":"Markdown with [inline citations]...","results":[{"url":"...","title":"...","snippets":["..."]}]}
Parse citations:
result | jq -r '.results[] | "[\(.title)](\(.url))"'
Cross-platform timeout:
Linux: timeout (built-in)
macOS: gtimeout (install: brew install coreutils)
Verify: Test schema with bunx @youdotcom-oss/api@latest deep-search --schema
Error: --json flag is required
at searchCommand (/path/to/search.ts:26:11)
mailto:support@you.com?subject=API%20Issue%20CLI...
Installation & Setup
Check runtime:
# Check if Node.js or Bun installedifcommand -v bun &> /dev/null; thenecho"Bun installed"elifcommand -v node &> /dev/null; thenecho"Node.js installed"elseecho"Neither Node.js nor Bun found. Installing Bun (recommended)..."
curl -fsSL https://bun.sh/install | bash
fi
Using the CLI (recommended for agents):
# bunx with @latest checks for updates every 24 hours
bunx @youdotcom-oss/api@latest search --json '{"query":"AI"}' --client ClaudeCode
# npx with @latest (note: has known caching issues, may not always fetch latest)
npx @youdotcom-oss/api@latest search --json '{"query":"AI"}' --client ClaudeCode
Note: bunx is recommended because it checks for package updates every 24 hours when using @latest, while npx has documented caching issues that may prevent it from fetching the latest version.
Environment Variables
export YDC_API_KEY="your-api-key"# Requiredexport YDC_CLIENT=ClaudeCode # Default client name
