parallel-cli

# Parallel CLI Use `parallel-cli` when the user explicitly wants Parallel, or when a terminal-native workflow would benefit from Parallel's vendor-specific stack for web search, extraction, deep research, enrichment, entity discovery, or monitoring. This is an optional third-party workflow, not a Hermes core capability. Important expectations: - Parallel is a paid service with a free tier, not a fully free local tool. - It overlaps with Hermes native `web_search` / `web_extract`, so do not prefer it by default for ordinary lookups. - Prefer this skill when the user mentions Parallel specifically or needs capabilities like Parallel's enrichment, FindAll, or monitor workflows. `parallel-cli` is designed for agents: - JSON output via `--json` - Non-interactive command execution - Async long-running jobs with `--no-wait`, `status`, and `poll` - Context chaining with `--previous-interaction-id` - Search, extract, research, enrichment, entity discovery, and monitoring in one CLI ## When to use it Prefer this skill when: - The user explicitly mentions Parallel or `parallel-cli` - The task needs richer workflows than a simple one-shot search/extract pass - You need async deep research jobs that can be launched and polled later - You need structured enrichment, FindAll entity discovery, or monitoring Prefer Hermes native `web_search` / `web_extract` for quick one-off lookups when Parallel is not specifically requested. ## Installation Try the least invasive install path available for the environment. ### Homebrew ```bash brew install parallel-web/tap/parallel-cli ``` ### npm ```bash npm install -g parallel-web-cli ``` ### Python package ```bash pip install "parallel-web-tools[cli]" ``` ### Standalone installer ```bash curl -fsSL https://parallel.ai/install.sh | bash ``` If you want an isolated Python install, `pipx` can also work: ```bash pipx install "parallel-web-tools[cli]" pipx ensurepath ``` ## Authentication Interactive login: ```bash parallel-cli login ``` Headless / SSH / CI: ```bash parallel-cli login --device ``` API key environment variable: ```bash export PARALLEL_API_KEY="***" ``` Verify current auth status: ```bash parallel-cli auth ``` If auth requires browser interaction, run with `pty=true`. ## Core rule set 1. Always prefer `--json` when you need machine-readable output. 2. Prefer explicit arguments and non-interactive flows. 3. For long-running jobs, use `--no-wait` and then `status` / `poll`. 4. Cite only URLs returned by the CLI output. 5. Save large JSON outputs to a temp file when follow-up questions are likely. 6. Use background processes only for genuinely long-running workflows; otherwise run in foreground. 7. Prefer Hermes native tools unless the user wants Parallel specifically or needs Parallel-only workflows. ## Quick reference ```text parallel-cli ├── auth ├── login ├── logout ├── search ├── extract / fetch ├── research run|status|poll|processors ├── enrich run|status|poll|plan|suggest|deploy ├── findall run|ingest|status|poll|result|enrich|extend|schema|cancel └── monitor create|list|get|update|delete|events|event-group|simulate ``` ## Common flags and patterns Commonly useful flags: - `--json` for structured output - `--no-wait` for async jobs - `--previous-interaction-id <id>` for follow-up tasks that reuse earlier context - `--max-results <n>` for search result count - `--mode one-shot|agentic` for search behavior - `--include-domains domain1.com,domain2.com` - `--exclude-domains domain1.com,domain2.com` - `--after-date YYYY-MM-DD` Read from stdin when convenient: ```bash echo "What is the latest funding for Anthropic?" | parallel-cli search - --json echo "Research question" | parallel-cli research run - --json ``` ## Search Use for current web lookups with structured results. ```bash parallel-cli search "What is Anthropic's latest AI model?" --json parallel-cli search "SEC filings for Apple" --include-domains sec.gov --json parallel-cli search "bitcoin price" --after-date 2026-01-01 --max-results 10 --json parallel-cli search "latest browser benchmarks" --mode one-shot --json parallel-cli search "AI coding agent enterprise reviews" --mode agentic --json ``` Useful constraints: - `--include-domains` to narrow trusted sources - `--exclude-domains` to strip noisy domains - `--after-date` for recency filtering - `--max-results` when you need broader coverage If you expect follow-up questions, save output: ```bash parallel-cli search "latest React 19 changes" --json -o ~/.hermes/cache/scratch/react-19-search.json ``` When summarizing results: - lead with the answer - include dates, names, and concrete facts - cite only returned sources - avoid inventing URLs or source titles ## Extraction Use to pull clean content or markdown from a URL. ```bash parallel-cli extract https://example.com --json parallel-cli extract https://company.com --objective "Find pricing info" --json parallel-cli extract https://example.com --full-content --json parallel-cli fetch https://example.com --json ``` Use `--objective` when the page is broad and you only need one slice of information. ## Deep research Use for deeper multi-step research tasks that may take time. Common processor tiers: - `lite` / `base` for faster, cheaper passes - `core` / `pro` for more thorough synthesis - `ultra` for the heaviest research jobs ### Synchronous ```bash parallel-cli research run \ "Compare the leading AI coding agents by pricing, model support, and enterprise controls" \ --processor core \ --json ``` ### Async launch + poll ```bash parallel-cli research run \ "Compare the leading AI coding agents by pricing, model support, and enterprise controls" \ --processor ultra \ --no-wait \ --json parallel-cli research status trun_xxx --json parallel-cli research poll trun_xxx --json parallel-cli research processors --json ``` ### Context chaining / follow-up ```bash parallel-cli research run "What are the top AI coding agents?" --json parallel-cli research run \ "What enterprise controls does the top-ranked one offer?" \ --previous-interaction-id trun_xxx \ --json ``` Recommended Hermes workflow: 1. launch with `--no-wait --json` 2. capture the returned run/task ID 3. if the user wants to continue other work, keep moving 4. later call `status` or `poll` 5. summarize the final report with citations from the returned sources ## Enrichment Use when the user has CSV/JSON/tabular inputs and wants additional columns inferred from web research. ### Suggest columns ```bash parallel-cli enrich suggest "Find the CEO and annual revenue" --json ``` ### Plan a config ```bash parallel-cli enrich plan -o config.yaml ``` ### Inline data ```bash parallel-cli enrich run \ --data '[{"company": "Anthropic"}, {"company": "Mistral"}]' \ --intent "Find headquarters and employee count" \ --json ``` ### Non-interactive file run ```bash 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" ``` ### YAML config run ```bash parallel-cli enrich run config.yaml ``` ### Status / polling ```bash parallel-cli enrich status <task_group_id> --json parallel-cli enrich poll <task_group_id> --json ``` Use explicit JSON arrays for column definitions when operating non-interactively. Validate the output file before reporting success. ## FindAll Use for web-scale entity discovery when the user wants a discovered dataset rather than a short answer. ```bash parallel-cli findall run "Find AI coding agent startups with enterprise offerings" --json parallel-cli findall run "AI startups in healthcare" -n 25 --json parallel-cli findall status <run_id> --json parallel-cli findall poll <run_id> --json parallel-cli findall result <run_id> --json parallel-cli findall schema <run_id> --json ``` This is a better fit than ordinary search when the user wants a discovered set of entities that can be reviewed, filtered, or enriched later. ## Monitor Use for ongoing change detection over time. ```bash parallel-cli monitor list --json parallel-cli monitor get <monitor_id> --json parallel-cli monitor events <monitor_id> --json parallel-cli monitor delete <monitor_id> --json ``` Creation is usually the sensitive part because cadence and delivery matter: ```bash parallel-cli monitor create --help ``` Use this when the user wants recurring tracking of a page or source rather than a one-time fetch. ## Recommended Hermes usage patterns ### Fast answer with citations 1. Run `parallel-cli search ... --json` 2. Parse titles, URLs, dates, excerpts 3. Summarize with inline citations from the returned URLs only ### URL investigation 1. Run `parallel-cli extract URL --json` 2. If needed, rerun with `--objective` or `--full-content` 3. Quote or summarize the extracted markdown ### Long research workflow 1. Run `parallel-cli research run ... --no-wait --json` 2. Store the returned ID 3. Continue other work or periodically poll 4. Summarize the final report with citations ### Structured enrichment workflow 1. Inspect the input file and columns 2. Use `enrich suggest` or provide explicit enriched columns 3. Run `enrich run` 4. Poll for completion if needed 5. Validate the output file before reporting success ## Error handling and exit codes The CLI documents these exit codes: - `0` success - `2` bad input - `3` auth error - `4` API error - `5` timeout If you hit auth errors: 1. check `parallel-cli auth` 2. confirm `PARALLEL_API_KEY` or run `parallel-cli login` / `parallel-cli login --device` 3. verify `parallel-cli` is on `PATH` ## Maintenance Check current auth / install state: ```bash parallel-cli auth parallel-cli --help ``` Update commands: ```bash parallel-cli update pip install --upgrade parallel-web-tools parallel-cli config auto-update-check off ``` ## Pitfalls - Do not omit `--json` unless the user explicitly wants human-formatted output. - Do not cite sources not present in the CLI output. - `login` may require PTY/browser interaction. - Prefer foreground execution for short tasks; do not overuse background processes. - For large result sets, save JSON to `~/.hermes/cache/scratch/*.json` (the Hermes scratch dir) instead of stuffing everything into context. - Do not silently choose Parallel when Hermes native tools are already sufficient. - Remember this is a vendor workflow that usually requires account auth and paid usage beyond the free tier.