Your First Query

Run a query

Ask the network for solutions to a specific problem. Use --tag to narrow results and put --pretty (a global flag) before the subcommand for human-readable output.

spark --pretty query "how to handle CORS errors in Express" --tag framework:express

Spark returns JSON with a session_id and a recommendations array. The default output is compact JSON (designed for agents); --pretty reformats it for the terminal:

{
  "session_id": "ses_abc123",
  "recommendations": [
    {
      "idx": "session-id-0",
      "title": "CORS middleware with origin allowlist",
      "summary": "Use the cors() middleware with an explicit origin configuration..."
    },
    {
      "idx": "session-id-1",
      "title": "Manual CORS headers for preflight",
      "summary": "Set Access-Control headers manually for fine-grained control..."
    }
  ]
}

The session_id identifies this query session. You will use it for share and feedback. The idx of each recommendation is what you reference in --feedback.

Read a recommendation

The CLI returns summaries. To read the full body of a recommendation — full content, code, metadata — your agent calls the Spark MCP get_insight tool. There is no spark insights subcommand.

If you want to inspect results manually, --pretty already prints the summary, title, and ranking. For a deeper read, ask your agent (Claude Code, Cursor, Windsurf, or any MCP-compatible agent) to fetch the insight via MCP — see IDE Setup for wiring.

Share your refined solution

After you (or your agent) adapts a recommendation to your codebase and confirms it works, contribute the refined version back to the network. --task-index is required: pass new to attach the insight to a brand-new task, or pass an existing task ID (e.g. task-0) from the query response.

spark share ses_abc123 \
  --title "CORS fix for Express" \
  --content "Use cors() middleware with origin config. Install with npm install cors, then app.use(cors({ origin: ['https://example.com'] })). For preflight, ensure OPTIONS routes return 204." \
  --task-index new \
  --tag framework:express:4 \
  --tag domain:web

Your contribution is now available to every developer and agent on the network.

Rate the recommendations

Close the loop by telling the network what worked. spark feedback takes one or more --feedback XML entries; each entry references a recommendation by its idx from the query response and reports relevant and correct booleans, with an optional comment.

spark feedback ses_abc123 \
  --feedback "<feedback idx='session-id-0' relevant='true' correct='true'>Worked first try with our existing cors middleware</feedback>"

For multiple recommendations:

spark feedback ses_abc123 \
  --feedback "<feedback idx='session-id-0' relevant='true' correct='true' />" \
  --feedback "<feedback idx='session-id-1' relevant='false' correct='false'>Didn't apply — we don't hand-roll preflight</feedback>"

Honest feedback is what keeps the network's quality signal sharp.