Source Code

Integrate You.com with Bash-Based AI Agents

Web search with livecrawl (search+extract) and content extraction for bash agents using You.com's @youdotcom-oss/api CLI.

Installation

# Check prerequisites
node -v  # Requires Node.js 18+ or Bun 1.3+
# or
bun -v

# Recommended: Global installation (available system-wide)
npm install -g @youdotcom-oss/api
# or
bun add -g @youdotcom-oss/api

# Verify installation
ydc --version

Quick Start

Get API key from https://you.com/platform/api-keys
Set environment variable:
```
export YDC_API_KEY="your-api-key-here"
```

Run commands using ydc:

# Basic search
ydc search --json '{"query":"AI news"}' --client YourAgentName

# Search with livecrawl (get full page content instantly)
ydc search --json '{
  "query":"documentation",
  "livecrawl":"web",
  "livecrawl_formats":"markdown"
}' --client YourAgentName

# Extract content from URL
ydc contents --json '{
  "urls":["https://example.com"],
  "formats":["markdown"]
}' --client YourAgentName

Update

# Update to latest version
npm update -g @youdotcom-oss/api
# or
bun update -g @youdotcom-oss/api

Workflow

1. Use --client Flag

Always include --client YourAgentName in all commands
Use your agent identifier (e.g., "ClaudeCode", "Cursor", "Codex")
This helps support respond to error reports (included in mailto links)
Example: ydc search --json '{"query":"..."}' --client ClaudeCode

2. Verify API Key

Check if YDC_API_KEY environment variable is set
If not set, guide user to get key from https://you.com/platform/api-keys
Provide command: export YDC_API_KEY="your-key"

3. Use --schema for Discovery

Use ydc search --schema to discover available parameters dynamically
Use ydc contents --schema to see content extraction options
Parse JSON schema to build queries programmatically
Example: ydc search --schema | jq '.properties | keys'

4. Tool Selection & Execution

IF user provides URLs → ydc contents with "urls" parameter
ELSE IF user needs search + full content → ydc search with "livecrawl":"web"
ELSE → ydc search without livecrawl

Requirements: Always include --json flag and --client YourAgentName
Exit codes: 0=success, 1=API error, 2=invalid args
Common filters: freshness, site, country parameters

Examples

Schema Discovery

# Discover search parameters
ydc search --schema | jq '.properties | keys'

# See full schema for search
ydc search --schema | jq

# Discover contents parameters
ydc contents --schema | jq '.properties | keys'

Search

# Basic search
ydc search --json '{"query":"AI news"}' --client YourAgent

# Search + extract full content (livecrawl)
ydc search --json '{"query":"docs","livecrawl":"web","livecrawl_formats":"markdown"}' --client YourAgent

# With filters
ydc search --json '{"query":"news","freshness":"week","site":"github.com"}' --client YourAgent

# Parse results
ydc search --json '{"query":"AI"}' --client YourAgent | jq -r '.results.web[] | "\(.title): \(.url)"'

# Extract from URL
ydc contents --json '{"urls":["https://example.com"],"formats":["markdown"]}' --client YourAgent

# Multiple URLs
ydc contents --json '{"urls":["https://a.com","https://b.com"],"formats":["markdown"]}' --client YourAgent | jq -r '.[0].markdown'

Troubleshooting

Exit codes: 0=success, 1=API error, 2=invalid args

Common fixes:

command not found: ydc → npm install -g @youdotcom-oss/api
--json flag is required → Always use --json '{"query":"..."}'
YDC_API_KEY required → export YDC_API_KEY="your-key"
401 error → Regenerate key at https://you.com/platform/api-keys
429 rate limit → Add retry logic with exponential backoff

Resources

Package: https://github.com/youdotcom-oss/dx-toolkit/tree/main/packages/api
API Keys: https://you.com/platform/api-keys

youdotcom-cli