Parallel CLI Skill for Hermes Agent: Reference Guide

Parallel CLI is an optional Hermes Agent skill that wraps Parallel's commercial web API in a terminal-native command set: search, page extraction, deep research runs, tabular enrichment, entity discovery, and change monitoring. You would reach for it when a user names Parallel explicitly, or when a task needs one of those heavier workflows rather than a single lookup. For ordinary fact-finding, Hermes already ships native web_search and web_extract, and this skill is not meant to replace them.

What it does

The skill gives the agent a single executable, parallel-cli, that covers six jobs. Search returns structured web results with domain and date filters. Extract pulls clean content or markdown from a URL, optionally narrowed by an objective. Research launches multi-step synthesis jobs that can run synchronously or in the background. Enrichment takes CSV, JSON, or other tabular input and infers new columns from web research. FindAll discovers sets of entities at web scale. Monitor watches a page or source over time for changes.

The design assumes an agent is driving, not a person at a keyboard. Every subcommand accepts --json for machine-readable output, commands are built to run without prompts, long jobs can be launched with --no-wait and checked later with status and poll, and follow-up tasks can reuse earlier context through --previous-interaction-id. That combination is what makes the tool usable inside an autonomous loop: the agent can start work, keep doing something else, and come back to collect results.

Before you start

Three things matter before the first command.

First, Parallel is a paid service with a free tier. It is not a fully free local tool, and usage beyond the free tier requires an account. Treat any plan that assumes unlimited calls as wrong until you have checked the account.

Second, the skill overlaps with Hermes native web_search and web_extract. The source is explicit that you should not prefer it by default for ordinary lookups. The native tools are the default; this skill is the exception.

Third, the skill is optional and installed on demand. It lives at optional-skills/research/parallel-cli, is version 1.1.0, authored by Hermes Agent under the MIT licence, and is listed for linux, macos, and windows. You need a working install of the CLI itself plus authentication before anything else works.

Installation

The source recommends trying the least invasive install path available for the environment. There are four primary routes plus an isolated Python option.

Homebrew

brew install parallel-web/tap/parallel-cli

npm

npm install -g parallel-web-cli

Python package

pip install "parallel-web-tools[cli]"

Standalone installer

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

If you want an isolated Python install, pipx can also work:

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

Pick the route that matches what the machine already has. A Homebrew host should use the tap; a Node-heavy environment can use npm; a Python environment can use pip or pipx. The standalone installer exists for hosts where none of those package managers are a good fit. The pipx path is the one to choose when you do not want the CLI's dependencies mixed into a project environment.

Authentication

Interactive login:

parallel-cli login

Headless / SSH / CI:

parallel-cli login --device

API key environment variable:

 export PARALLEL_API_KEY="***"

Verify current auth status:

parallel-cli auth

If auth requires browser interaction, run with pty=true.

The device flow is the one to use on a remote box or in CI, where no browser is available. The environment variable route suits automated runs where you inject the key from a secret store. parallel-cli auth is the check to run whenever a command fails unexpectedly, because an expired or missing credential will surface as an auth error rather than a data problem. The pty=true note matters for agent runtimes: a login that opens a browser needs a pseudo-terminal, and without one it can stall.

Core rule set

The source lays out seven rules for using the skill well. They are worth restating in full because most failures trace back to one of them.

Always prefer --json when you need machine-readable output.
Prefer explicit arguments and non-interactive flows.
For long-running jobs, use --no-wait and then status / poll.
Cite only URLs returned by the CLI output.
Save large JSON outputs to a temp file when follow-up questions are likely.
Use background processes only for genuinely long-running workflows; otherwise run in foreground.
Prefer Hermes native tools unless the user wants Parallel specifically or needs Parallel-only workflows.

Rules 4 and 7 are the ones that go wrong most often. Citing a URL the CLI did not return is fabrication, even if the page exists. Reaching for Parallel when a native lookup would do wastes money and adds latency for no gain.

Quick reference

The command tree, as the source presents it:

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

Note that extract and fetch are two names for the same operation. Research, enrich, and findall each follow the same shape: a run that starts work, then status and poll to check it. FindAll adds result and schema for retrieving the discovered dataset and its structure.

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:

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

The stdin form is useful when the query is already in a variable or a file and you do not want to deal with shell quoting. The - argument stands in for the query text.

Search

Use for current web lookups with structured results.

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

The domain filters are the difference between a usable result set and a pile of SEO pages. If you know the answer lives on a regulator's site or a vendor's own domain, --include-domains gets you there faster than any ranking tweak. --exclude-domains is the inverse: strip the domains that keep polluting a query. --after-date handles the case where the question is inherently about recent events. --mode one-shot and --mode agentic trade speed against depth for the search itself.

If you expect follow-up questions, save output:

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

The -o flag writes the JSON to a file, which is the right move when the agent will need to answer several questions from the same result set. Re-reading a file is cheaper than re-running the search.

Extraction

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.

A pricing page, a long documentation index, or a sprawling about page are all cases for --objective: you tell the extractor what you are after and get that slice rather than the whole document. --full-content is the opposite choice, for when you want everything and will do the filtering yourself. fetch is an alias for extract.

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

parallel-cli research run \
  "Compare the leading AI coding agents by pricing, model support, and enterprise controls" \
  --processor core \
  --json

Async launch + poll

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

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:

launch with --no-wait --json
capture the returned run/task ID
if the user wants to continue other work, keep moving
later call status or poll
summarize the final report with citations from the returned sources

The processor tier is the main cost and depth dial. A lite or base pass answers a narrow question cheaply; core and pro are for synthesis across several sources; ultra is for the jobs that justify the wait. The async pattern exists so the agent does not block on a long run: launch, keep the ID, do other work, then poll. Context chaining is what makes follow-ups cheap, because the second question builds on the first run's context instead of starting over. research processors lists the tiers available to the account.

Enrichment

Use when the user has CSV/JSON/tabular inputs and wants additional columns inferred from web research.

Suggest columns

parallel-cli enrich suggest "Find the CEO and annual revenue" --json

Plan a config

parallel-cli enrich plan -o config.yaml

Inline data

parallel-cli enrich run \
  --data '[{"company": "Anthropic"}, {"company": "Mistral"}]' \
  --intent "Find headquarters and employee count" \
  --json

Non-interactive file run

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

parallel-cli enrich run config.yaml

Status / polling

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.

The enrichment flow has two entry points. enrich suggest helps you work out which columns are worth adding for a given intent. enrich plan writes a config file you can inspect and reuse. From there you either pass inline data with --data, point at a CSV with --source and --target, or hand the whole thing a YAML config. The non-interactive file run is the one to use inside an agent: every column is described explicitly in JSON, so nothing depends on a prompt. The source's warning is direct: validate the output file before reporting success. An enrichment run that produced a malformed or empty target is a failure even if the command exited cleanly.

FindAll

Use for web-scale entity discovery when the user wants a discovered dataset rather than a short answer.

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.

The distinction from search is the shape of the output. Search answers a question; FindAll produces a dataset. If the user's next step is to filter, sort, or enrich the results, FindAll is the right primitive. -n sets how many entities to look for, and schema tells you what fields the run produced so you can work with the result programmatically.

Monitor

Use for ongoing change detection over time.

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:

parallel-cli monitor create --help

Use this when the user wants recurring tracking of a page or source rather than a one-time fetch.

Monitoring is the only capability here that is inherently long-lived. Listing, reading, and deleting existing monitors are safe, reversible operations. Creating one is where you slow down: the source points at monitor create --help because cadence and delivery are the decisions that matter, and getting them wrong means either noise or missed changes. Read the help before creating anything.

Recommended Hermes usage patterns

Fast answer with citations

Run parallel-cli search ... --json
Parse titles, URLs, dates, excerpts
Summarize with inline citations from the returned URLs only

URL investigation

Run parallel-cli extract URL --json
If needed, rerun with --objective or --full-content
Quote or summarize the extracted markdown

Long research workflow

Run parallel-cli research run ... --no-wait --json
Store the returned ID
Continue other work or periodically poll
Summarize the final report with citations

Structured enrichment workflow

Inspect the input file and columns
Use enrich suggest or provide explicit enriched columns
Run enrich run
Poll for completion if needed
Validate the output file before reporting success

These four patterns cover most real use. The common thread is that each one ends with a verification step: citations checked against returned URLs, the output file validated, the report summarized from the run's own sources. The agent should never report success on the strength of an exit code alone.

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:

check parallel-cli auth
confirm PARALLEL_API_KEY or run parallel-cli login / parallel-cli login --device
verify parallel-cli is on PATH

The exit codes let an agent branch without parsing output. A 2 means the command was malformed and retrying unchanged will fail again. A 3 means credentials, so check auth and the environment variable. A 4 is the API itself, which may be transient. A 5 is a timeout, which for a long research job may simply mean you should have used --no-wait. The auth checklist is ordered for a reason: confirm the credential first, then the install, then the path.

Maintenance

Check current auth / install state:

parallel-cli auth
parallel-cli --help

Update commands:

parallel-cli update
pip install --upgrade parallel-web-tools
parallel-cli config auto-update-check off

parallel-cli update is the built-in updater; the pip command covers installs that came from the Python package. The auto-update check can be turned off, which is worth doing on automated hosts where an unexpected update mid-run is unwelcome.

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.

When not to use it

For quick one-off lookups where the user has not asked for Parallel, use Hermes native web_search and web_extract. The source states this plainly: the skill overlaps with the native tools and should not be preferred by default. Reach for Parallel when the user names it, or when the task needs a capability the native tools do not cover: enrichment, FindAll entity discovery, or monitoring. If none of those apply, the native path is cheaper, faster, and needs no account.

Limits and gotchas

The limits here are mostly about discipline rather than hard caps. Parallel is a paid service with a free tier, so cost is real and the agent should not spend it on lookups a native tool would answer. Auth can require a browser, which means a pseudo-terminal on headless hosts. Long jobs need the async pattern; running them in the foreground ties up the agent for no reason. Large result sets belong in the scratch directory at ~/.hermes/cache/scratch/*.json rather than in context. And citations must come from the CLI output, never from memory or inference. The source's closing reminder is the one to keep in view: this is a vendor workflow that usually requires account auth and paid usage beyond the free tier.

Related skills

Two skills sit alongside this one. duckduckgo-search covers free web search when no paid account is involved. mcporter is the other related skill listed for this category. If you are weighing whether Parallel is worth the account, start with the free option and move here when a task genuinely needs enrichment, FindAll, or monitoring.

Parallel CLI Skill for Hermes Agent: Search, Research, Enrich