youdotcom-cli skill

---
name: youdotcom-cli
description: |
  Web search with livecrawl (search+extract) and content extraction for bash agents using You.com's @youdotcom-oss/api CLI.
  - MANDATORY TRIGGERS: You.com, youdotcom, YDC, @youdotcom-oss/api, web search CLI, livecrawl
  - Use when: web search needed, content extraction, URL crawling, real-time web data
license: MIT
compatibility: Requires Bun 1.3+ or Node.js 18+, and access to the internet
allowed-tools: Bash(bunx:@youdotcom-oss/api) Bash(npx:@youdotcom-oss/api) Bash(bunx:ydc) Bash(npx:ydc) Bash(jq:*)
metadata:
  author: youdotcom-oss
  version: "2.0.5"
  category: web-search-tools
  keywords: you.com,bash,cli,ai-agents,web-search,content-extraction,livecrawl,claude-code,codex,cursor
---

# 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

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

1. Get API key from https://you.com/platform/api-keys
2. Set environment variable:
   ```bash
   export YDC_API_KEY="your-api-key-here"
   ```
3. Run commands using `ydc`:
   ```bash
   # 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

```bash
# 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
```bash
# 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
```bash
# 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)"'
```

### Contents
```bash
# 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