diff --git a/skills/research/parallel-cli/SKILL.md b/skills/research/parallel-cli/SKILL.md index 58fcdfcaa..ee8f15a83 100644 --- a/skills/research/parallel-cli/SKILL.md +++ b/skills/research/parallel-cli/SKILL.md @@ -1,7 +1,7 @@ --- name: parallel-cli -description: Use Parallel CLI for agent-native web search, content extraction, deep research, enrichment, FindAll entity discovery, and monitoring. Prefer JSON output and non-interactive flows. -version: 1.0.0 +description: Optional vendor skill for Parallel CLI — agent-native web search, extraction, deep research, enrichment, FindAll, and monitoring. Prefer JSON output and non-interactive flows. +version: 1.1.0 author: Hermes Agent license: MIT metadata: @@ -12,48 +12,61 @@ metadata: # Parallel CLI -Use `parallel-cli` when the user wants Parallel specifically, or when a terminal-native workflow would benefit from Parallel's web search, extraction, deep research, or enrichment stack. +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 web search/extract pass +- 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 data enrichment, FindAll, or monitoring capabilities +- 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 fastest install path available for the environment. +Try the least invasive install path available for the environment. -### Standalone binary - -```bash -# macOS / Linux -curl -fsSL https://parallel.ai/install.sh | bash -``` - -Homebrew is also supported: +### Homebrew ```bash brew install parallel-web/tap/parallel-cli ``` -npm downloads the prebuilt binary: +### npm ```bash npm install -g parallel-web-cli ``` -### Python fallback +### 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]" @@ -68,28 +81,35 @@ Interactive login: parallel-cli login ``` -Headless / CI / agent usage: +Headless / SSH / CI: + +```bash +parallel-cli login --device +``` + +API key environment variable: ```bash export PARALLEL_API_KEY="***" ``` -Verify auth: +Verify current auth status: ```bash -parallel-cli auth --json +parallel-cli auth ``` If auth requires browser interaction, run with `pty=true`. ## Core rule set -1. Always prefer `--json` so Hermes can parse structured output. -2. Prefer non-interactive flags and explicit arguments. +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 @@ -106,20 +126,42 @@ parallel-cli └── 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 ` for follow-up tasks that reuse earlier context +- `--max-results ` 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 -q "bitcoin price" --after-date 2026-01-01 --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 flags: -- `-q` for supplemental keyword queries -- `--after-date YYYY-MM-DD` for recency -- `--include-domains domain1.com,domain2.com` to constrain sources +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: @@ -141,6 +183,7 @@ Use to pull clean content or markdown from a URL. 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. @@ -149,26 +192,50 @@ Use `--objective` when the page is broad and you only need one slice of informat 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" --json +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" --no-wait --json +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 @@ -180,13 +247,22 @@ Use when the user has CSV/JSON/tabular inputs and wants additional columns infer parallel-cli enrich suggest "Find the CEO and annual revenue" --json ``` -### Plan config +### Plan a config ```bash parallel-cli enrich plan -o config.yaml ``` -### Non-interactive run +### 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 \ @@ -197,6 +273,12 @@ parallel-cli enrich run \ --intent "Find the CEO and annual revenue" ``` +### YAML config run + +```bash +parallel-cli enrich run config.yaml +``` + ### Status / polling ```bash @@ -205,57 +287,41 @@ parallel-cli enrich poll --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 set of entities matching natural-language criteria. +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 --json parallel-cli findall poll --json parallel-cli findall result --json parallel-cli findall schema --json ``` -This is a better fit than ordinary search when the user wants a discovered dataset rather than a short answer. +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 create --help parallel-cli monitor list --json parallel-cli monitor get --json parallel-cli monitor events --json parallel-cli monitor delete --json ``` -Use this when the user wants recurring tracking of a page or source rather than a one-time fetch. - -## Input patterns for agents - -Read from stdin when convenient: +Creation is usually the sensitive part because cadence and delivery matter: ```bash -echo "What is the latest funding for Anthropic?" | parallel-cli search - --json -echo "Research question" | parallel-cli research run - --json +parallel-cli monitor create --help ``` -## 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 --json` -2. confirm `PARALLEL_API_KEY` or run `parallel-cli login` -3. verify `parallel-cli` is on `PATH` +Use this when the user wants recurring tracking of a page or source rather than a one-time fetch. ## Recommended Hermes usage patterns @@ -282,6 +348,37 @@ If you hit auth errors: 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. @@ -289,3 +386,5 @@ If you hit auth errors: - `login` may require PTY/browser interaction. - Prefer foreground execution for short tasks; do not overuse background processes. - For large result sets, save JSON to `/tmp/*.json` 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.