📚 Tutorial: Parallel CLI - Parallel

The parallel-cli is a command-line tool for interacting with the Parallel API. It works interactively or fully via command-line arguments, making it the recommended way to use Parallel in standalone agents. For best results, pair the CLI with Agent Skills or Claude Code to give your agent structured access to search, extract, enrich, and research capabilities.

View the source and full README on GitHub.

Already have parallel-cli installed? Run parallel-cli update (standalone binary) or upgrade with your package manager to get the latest features and improvements. See Updating.

Installation

Install in an isolated environment so parallel-cli is on your PATH:

pipx install "parallel-web-tools[cli]" && pipx ensurepath

pipx ensurepath is only required on first-ever pipx use; including it here makes the command safe to copy-paste either way. For the minimal CLI without YAML configs / interactive planner, use pipx install parallel-web-tools.

uv is Astral’s faster modern alternative to pipx. It writes a PATH-aware shim on first run, so no ensurepath step is needed:

uv tool install "parallel-web-tools[cli]"

Requires uv to be installed first — see Astral’s install guide.

brew install parallel-web/tap/parallel-cli

Use pip when you’re embedding parallel-web-tools in a Python project (rather than using parallel-cli as a standalone tool — see the pipx tab for that):

# Minimal SDK
pip install parallel-web-tools

# With YAML config files and interactive planner
pip install parallel-web-tools[cli]

# With data integrations
pip install parallel-web-tools[duckdb]    # DuckDB
pip install parallel-web-tools[bigquery]  # BigQuery
pip install parallel-web-tools[spark]     # Apache Spark

# Everything
pip install parallel-web-tools[all]

npm install -g parallel-web-cli

Install the standalone binary (no Python or Node required):

curl -fsSL https://parallel.ai/install.sh | bash

This detects your platform (macOS/Linux, x64/arm64) and installs to ~/.local/bin.

Some agent skill registries flag the curl | bash pattern as a supply-chain risk. If you’re installing parallel-cli for use with Agent Skills, prefer pipx or Homebrew.

Authentication

# Device OAuth login (shows a code and opens browser)
parallel-cli login

# Don't auto-open the browser (SSH, containers, and CI are detected automatically)
parallel-cli login --no-browser

# Or set environment variable
export PARALLEL_API_KEY="your_api_key"

# Check auth status
parallel-cli auth

Get your API key from Platform.

Commands

Search

Search the web with natural language objectives or keyword queries.

# Natural language search
parallel-cli search "What is Anthropic's latest AI model?" --json

# Keyword search with date filter
parallel-cli search -q "bitcoin price" --after-date 2026-01-01 --json

# Search specific domains
parallel-cli search "SEC filings for Apple" --include-domains sec.gov --json

# Set search mode
parallel-cli search "latest AI research" --mode turbo --json

Option	Description
`-q, --query`	Keyword search query (repeatable)
`--mode`	`turbo` (fastest, ~200ms), `fast` (high-quality, ~700ms; recommended for most agents), `basic` (default; extended snippets per result), or `advanced` (highest quality). Deprecated Beta aliases map `one-shot` to `basic` and `agentic` to `advanced`
`--max-results`	Maximum requested results (server default: 10)
`--include-domains`	Only search these domains or domain/path prefixes (comma-separated or repeatable; paths require `fast`, `basic`, or `advanced` mode)
`--exclude-domains`	Exclude these domains or domain/path prefixes (comma-separated or repeatable; paths require `fast`, `basic`, or `advanced` mode)
`--after-date`	Only include results published on or after this date (YYYY-MM-DD)
`--excerpt-max-chars-per-result`	Maximum excerpt characters per result
`--excerpt-max-chars-total`	Maximum excerpt characters across all results (CLI default: 60,000)
`--max-age-seconds`	Maximum cache age before fetching live content; values below 600 are adjusted to 600 with a warning
`--timeout-seconds`	Timeout for fetching live content
`--disable-cache-fallback`	Return an error instead of stale cached content when live fetch fails or times out
`--location`	ISO 3166-1 alpha-2 country code for geo-targeted results
`--session-id`	Group related Search and Extract calls in one session
`--client-model`	Model generating the request and consuming the results
`--json`	Output as JSON
`-o, --output`	Save results to file

Direct API calls use a dynamic total excerpt budget when max_chars_total is omitted. The CLI sends 60000 by default unless --excerpt-max-chars-total is set.

Extract

Extract clean markdown content from URLs.

# Basic extraction
parallel-cli extract https://example.com --json

# Extract with a specific focus
parallel-cli extract https://company.com --objective "Find pricing info" --json

# Get full page content
parallel-cli extract https://example.com --full-content --json

Option	Description
`--objective`	Focus extraction on a specific goal
`-q, --query`	Keywords to prioritize (repeatable)
`--full-content`	Include complete page content
`--no-excerpts`	Exclude excerpts from output
`--json`	Output as JSON
`-o, --output`	Save results to file

Research

Run deep research on open-ended questions.

# Run deep research
parallel-cli research run "What are the latest developments in quantum computing?" --json

# Use a specific processor tier
parallel-cli research run "Compare EV battery technologies" --processor ultra --json

# Read query from file
parallel-cli research run -f question.txt -o report

# Async: launch then poll separately
parallel-cli research run "question" --no-wait --json    # returns run_id
parallel-cli research status trun_xxx --json              # check status
parallel-cli research poll trun_xxx --json                # wait and get result

# List available processors
parallel-cli research processors --json

Option	Description
`-p, --processor`	Processor tier: `lite`, `base`, `core`, `core2x`, `pro`, `ultra`, `ultra2x`, `ultra4x`, `ultra8x`, or a `-fast` variant such as `pro-fast` (default)
`--no-wait`	Return immediately after creating task
`--timeout`	Max wait time in seconds (default: 3600)
`-o, --output`	Output base path; writes `.json` (plus `.md` with `--text`). Default: `./parallel-research/<run_id>`
`--json`	Output as JSON

Enrich

Enrich CSV or JSON data with AI-powered web research.

# Let AI suggest output columns
parallel-cli enrich suggest "Find the CEO and annual revenue" --json

# Run enrichment directly
parallel-cli enrich run \
    --source-type csv \
    --source companies.csv \
    --target enriched.csv \
    --source-columns '[{"name": "company", "description": "Company name"}]' \
    --intent "Find the CEO and annual revenue"

# Enrich with inline data (no file needed)
parallel-cli enrich run \
    --data '[{"company": "Google"}, {"company": "Apple"}]' \
    --target output.csv \
    --intent "Find the CEO"

# Enrich a JSON file
parallel-cli enrich run \
    --source-type json \
    --source companies.json \
    --target enriched.json \
    --source-columns '[{"name": "company", "description": "Company name"}]' \
    --enriched-columns '[{"name": "ceo", "description": "CEO name"}]'

# Run from YAML config
parallel-cli enrich run config.yaml

# Async: launch then poll
parallel-cli enrich run config.yaml --no-wait --json
parallel-cli enrich status tgrp_xxx --json
parallel-cli enrich poll tgrp_xxx --json

Option	Description
`--source-type`	`csv` or `json`; Python installs with the relevant extras also support `duckdb` and `bigquery`
`--source`	Source file path
`--target`	Target file path
`--source-columns`	Source columns as JSON
`--enriched-columns`	Output columns as JSON
`--intent`	Natural language description (AI suggests columns)
`--processor`	Processor tier: `lite`, `base`, `core`, `pro`, `ultra`, `ultra2x`, `ultra4x`, `ultra8x`, or a `-fast` variant. Defaults to `core-fast`, or the suggested processor when using `--intent`
`--data`	Inline JSON data array
`--no-wait`	Return immediately
`--dry-run`	Preview without making API calls
`--json`	Output as JSON
`-o, --output`	Save results to a JSON file
`--previous-interaction-id`	Reuse context from a previous task

YAML configuration format

You can also define enrichment jobs in YAML:

source: input.csv
target: output.csv
source_type: csv
processor: core

source_columns:
  - name: company_name
    description: The name of the company

enriched_columns:
  - name: ceo
    description: The CEO of the company
    type: str
  - name: revenue
    description: Annual revenue in USD
    type: float

Create YAML configs interactively or programmatically:

# Interactive
parallel-cli enrich plan -o config.yaml

# Non-interactive (for scripts/agents)
parallel-cli enrich plan -o config.yaml \
    --source-type csv \
    --source companies.csv \
    --target enriched.csv \
    --source-columns '[{"name": "company", "description": "Company name"}]' \
    --intent "Find the CEO and annual revenue"

YAML config files and the interactive planner require pip install parallel-web-tools[cli].

FindAll

Discover entities from the web using natural language.

# Discover entities
parallel-cli findall run "AI startups in healthcare" --json

# Control generator tier and match limit
parallel-cli findall run "Find roofing companies in Charlotte NC" -g base -n 25 --json

# Exclude specific entities
parallel-cli findall run "Find AI startups" \
    --exclude '[{"name": "Example Corp", "url": "example.com"}]' --json

# Preview schema before running
parallel-cli findall run "Find YC companies in developer tools" --dry-run --json

# Fast, synchronous ranked entity search (no per-candidate verification)
parallel-cli findall entity-search "AI startups in San Francisco" \
    --entity-type companies --match-limit 25 --json

# Async workflow
parallel-cli findall run "AI startups" --no-wait --json
parallel-cli findall status findall_xxx --json
parallel-cli findall poll findall_xxx --json
parallel-cli findall result findall_xxx --json

# Cancel a running job
parallel-cli findall cancel findall_xxx

Option	Description
`-g, --generator`	Generator tier: `base`, `core` (default), or `pro`
`-n, --match-limit`	Max matched candidates, 5-1000 (default: 10)
`--exclude`	Entities to exclude as JSON array
`--metadata`	Run metadata as a JSON object
`--timeout`	Max polling time in seconds (default: 3600)
`--poll-interval`	Seconds between status checks (default: 30)
`--no-wait`	Return immediately
`--dry-run`	Preview schema without creating the run
`--json`	Output as JSON
`-o, --output`	Save results to a JSON file

--dry-run calls the ingest endpoint to preview the generated schema. It does not create a FindAll run with the API’s preview generator.

findall run normally ingests the objective, creates the run, applies enrichments suggested by ingest, and polls for results. With --no-wait, it returns after ingest and create; use findall enrich separately if you want to add enrichments to that asynchronous run.

Monitor

Continuously track the web for changes.

# Create a monitor
parallel-cli monitor create "Track price changes for iPhone 16" --json

# Set check frequency
parallel-cli monitor create "New AI funding announcements" --frequency 1h --json

# Track changes to a Task Run output
parallel-cli monitor create --type snapshot \
    --task-run-id trun_xxx --frequency 1d --json

# With webhook delivery
parallel-cli monitor create "SEC filings from Tesla" \
    --webhook https://example.com/hook --json

# Manage monitors
parallel-cli monitor list --json
parallel-cli monitor get mon_xxx --json
parallel-cli monitor update mon_xxx --frequency 1w --json
parallel-cli monitor cancel mon_xxx --json

# View events
parallel-cli monitor events mon_xxx --json
parallel-cli monitor events mon_xxx --event-group-id mevtgrp_xxx --json

# Run an off-schedule check
parallel-cli monitor trigger mon_xxx --json

trigger starts a real off-schedule run without changing the monitor’s regular frequency. It is not a synthetic webhook test, and cancelled monitors cannot be triggered. Cancellation is irreversible and permanently stops future runs; create a new monitor to resume monitoring.

Option	Description
`-f, --frequency`	Frequency in `<n><unit>` format using `h`, `d`, or `w`, such as `1h`, `1d`, or `1w` (`monitor create` default: `1d`). Aliases `hourly`, `daily`, `weekly`, and `every_two_weeks` are also accepted.
`--type`	Monitor type for `monitor create`: `event_stream` tracks a search query (default); `snapshot` tracks a Task Run output
`--task-run-id`	Task Run to track when creating a `snapshot` monitor
`--processor`	Monitor processor for `monitor create`: `lite` (default) or the more thorough, higher-cost `base`
`--webhook`	Webhook URL for event delivery
`--output-schema`	Output schema as a JSON string (`event_stream` only)
`--status`	Filter `monitor list` by `active` or `cancelled`; repeat to include both (default: active only)
`--event-group-id`	Filter `monitor events` to a specific Monitor execution
`--json`	Output as JSON

Non-Interactive Mode

All commands support --json output and can be fully controlled via CLI arguments, making the CLI ideal for use in scripts and by AI agents.

# Structured JSON output
parallel-cli search "query" --json

# Read input from stdin
echo "What is the latest funding for Anthropic?" | parallel-cli search - --json
echo "Research question" | parallel-cli research run - --json

# Exit codes
# 0 = success, 2 = bad input, 3 = auth error, 4 = API error, 5 = timeout

Updating

The standalone binary automatically checks for updates and will notify you when a new version is available. To update:

# pipx
pipx upgrade parallel-web-tools

# uv
uv tool upgrade parallel-web-tools

# Standalone binary
parallel-cli update

# Check for updates without installing
parallel-cli update --check

# Homebrew
brew upgrade parallel-cli

# npm
npm update -g parallel-web-cli

# pip
pip install --upgrade parallel-web-tools

To disable automatic update checks (standalone binary only):

parallel-cli config auto-update-check off

Getting started

Web Tools

Web Agents

Developer Tools

Platform Integrations

Data Integrations

Additional Resources

Parallel CLI

Installation

Authentication

Commands

Search

Extract

Research

Enrich

FindAll

Monitor

Non-Interactive Mode

Updating

​Installation

​Authentication

​Commands

​Search

​Extract

​Research

​Enrich

​FindAll

​Monitor

​Non-Interactive Mode

​Updating

Installation

Authentication

Commands

Search

Extract

Research

Enrich

FindAll

Monitor

Non-Interactive Mode

Updating