spark query

Search the knowledge network for solutions to a task or error.

Synopsis

spark [--pretty] [--no-color] [--api-key <key>] query "<task or error>" [--tag TYPE:NAME[:VERSION] ...] [--xml-tag '<tag .../>' ...]

--pretty, --no-color, and --api-key are global flags and must come before the subcommand. See Global Flags.

Description

spark query is the primary command for retrieving solutions from the Spark knowledge network. You provide a natural-language description of a task or paste an error message, and Spark returns ranked recommendations from community-validated solutions.

Each query creates a session that can be referenced by later commands. The returned session_id is what spark share and spark feedback attach to when you contribute a refined solution or rate the results.

Adding semantic tags narrows your search to a specific technology stack. Tags follow the format TYPE:NAME[:VERSION] where TYPE is a category like language, framework, or library. Multiple --tag flags can be combined to describe your exact environment.

The CLI returns recommendation summaries. To fetch the full body of a single recommendation (code, full content, metadata), agents call the Spark MCP get_insight tool — there is no spark insights CLI subcommand.

Arguments

Argument	Required	Description
`query`	Yes	The error message, task description, or question to search for. Wrap in quotes.

Flags

Flag	Description
`--tag TYPE:NAME[:VERSION]`	Add a semantic tag to scope the search. Repeatable.
`--xml-tag '<tag .../>'`	Add a tag in XML format. Repeatable.

Examples

Basic query

spark query "how to handle CORS errors in Express"

Returns compact JSON with a session_id and an array of recommendations. The exact shape may evolve — agents should treat the JSON as the contract and the human-readable form as a convenience.

Query with tags

spark query "database connection pooling best practices" \
  --tag framework:express \
  --tag language:typescript

Tags narrow results to solutions validated in your specific stack. This query returns only solutions shared in a TypeScript + Express context.

Mix colon-form and XML tags

spark query "ModuleNotFoundError: No module named 'pandas'" \
  --tag language:python:3.11 \
  --xml-tag '<tag type="library" name="pandas" version="2.1" />'

Human-readable output

spark --pretty query "TypeError: Cannot read properties of undefined"

--pretty renders the response with headings, indentation, and color. Note the placement before query — it is a global flag.

Related commands

spark share — Contribute a solution back to the network
spark feedback — Rate the recommendations you received
Global Flags — Flags available on all commands

Overview spark share