synthetic-search

A user-facing CLI for Synthetic web search, quotas, and local credential management.

Features

• Search the public web with Synthetic (/v2/search)
• View account usage and limits (/v2/quotas)
• Interactive local auth setup (auth login / auth logout / auth status)
• Readable terminal output by default
• --json output mode for scripts and automation
• Tolerant JSON parsing for malformed control characters in API responses

Requirements

• Node.js 18+
• Synthetic API key

Installation

npm install -g synthetic-search

Or run directly with npx:

npx -y synthetic-search --help

Authentication

SYNTHETIC_API_KEY always takes priority over saved config.

Environment variable (recommended for CI)

export SYNTHETIC_API_KEY=your_api_key_here

Saved local config

synthetic-search auth login

This validates the key via GET /v2/quotas before saving.

Skip validation:

synthetic-search auth login --no-validate

Check status:

synthetic-search auth status

Remove saved key:

synthetic-search auth logout
synthetic-search auth logout --force

Usage

Search

Root command and subcommand are equivalent:

synthetic-search latest model context protocol news
synthetic-search search latest model context protocol news

Read query from piped stdin:

echo "latest ai safety research" | synthetic-search search

JSON output:

synthetic-search search "latest mcp updates" --json

Client-side result limit:

synthetic-search search "latest mcp updates" --limit 2

Quotas

synthetic-search quotas
synthetic-search quotas --json

API Endpoints

• POST https://api.synthetic.new/v2/search
• GET https://api.synthetic.new/v2/quotas

Development

npm install
npm run test
npm run build

Run in dev mode:

npm run dev -- search "latest llm tooling"

License

MIT