answersearch

answersearch

answersearch puts Perplexity's models within reach of a terminal or an agent. You can put a question to a search-grounded model and get an answer with its sources, pull ranked web results on their own, hand a hard problem to the reasoning model, or commission a slower, deeper research pass that reads widely before it writes. It runs as a small CLI or as an MCP server, and it needs a Perplexity API key.

Setup

Get a key from the Perplexity API portal and export it:

export PERPLEXITY_API_KEY=<redacted>

Without the variable set, every command and tool call fails with an error that names PERPLEXITY_API_KEY — nothing is sent anywhere.

Install

npx @reneturcios/answersearch ask "what changed in the latest Node LTS?"

Or run the container image:

docker run -i -e PERPLEXITY_API_KEY ghcr.io/cloudcorprecords/answersearch

The container defaults to the MCP server (see below). Pass CLI arguments to use it as a CLI instead.

CLI

# Conversational answer grounded in live web search (sonar-pro)
answersearch ask "who won the marathon last weekend?"

# Ranked search results only, with optional budgets
answersearch search "composting basics" --max-results 5 --max-tokens 4000 --max-tokens-per-page 512

# Step-by-step reasoning (sonar-reasoning-pro)
answersearch reason "prove that the square root of two is irrational"

# Deep, multi-source research (sonar-deep-research) — this one takes a while
answersearch research "compare the failure modes of lithium and sodium batteries"

answersearch --version

Successful calls print the API's JSON response. Exit codes: 0 on success, 1 when the API call fails (including a missing key), 2 for usage errors.

MCP server

One bin serves both faces. The mcp subcommand starts a stdio MCP server:

npx -y @reneturcios/answersearch mcp

MCP client configuration:

{
  "mcpServers": {
    "answersearch": {
      "command": "npx",
      "args": ["-y", "@reneturcios/answersearch", "mcp"],
      "env": { "PERPLEXITY_API_KEY": "your-key-here" }
    }
  }
}

Tools

Tool	Input	What it does
perplexity_ask	messages (array of {role, content}, required)	Conversational answer with live web search, via the sonar-pro model on the chat-completions endpoint.
perplexity_search	query (string, required), max_results, max_tokens, max_tokens_per_page (integers, optional)	Direct call to the Search API; returns its ranked results and metadata as returned upstream.
perplexity_reason	messages (required, same shape)	Analytical reasoning via sonar-reasoning-pro.
perplexity_research	messages (required, same shape)	Deep research via sonar-deep-research; expect a longer wait than the other tools.

Tool results are the upstream JSON, pretty-printed as text. Upstream failures (bad key, quota, HTTP errors) come back as tool errors carrying the status and the API's own message.

Development

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, no network (fake fetch fixtures)
npm run dev     # run the CLI from source via tsx

License

MIT — see LICENSE.