> SpecStream is the live web data engine for teams and agents. This is the Markdown copy of https://specstream.ai/docs/integrations/snow-cli. Every page, with what SpecStream does and costs: https://specstream.ai/llms.txt

# Snow CLI

Give Snow CLI's web search a SpecStream engine: one `.mjs` file in `~/.snow/plugin/search_engines/` and one pick in the **Search Engine:** field. The `websearch-search` tool then gets its results from SpecStream's Search API, in place of the DuckDuckGo or Bing results page Snow CLI reads in a headless browser.

[SpecStream for Snow CLICoding agents](https://specstream.ai/integrations/snow-cli.md)

## What you need

-   Snow CLI, installed with `npm install -g snow-ai`.
-   A SpecStream key. [Get your key](https://specstream.ai/workspace/search?utm_source=snow-cli&utm_medium=howto) on the Search API screen of your SpecStream workspace. New accounts start with $10 of credit, no card.

1.  1

    ## 1. Put your key in the environment

    The engine reads the key from `SPECSTREAM_API_KEY`, so the key never sits in the engine file. Add the line to your shell profile, open a new terminal, and start Snow CLI from it. On Windows, run `setx SPECSTREAM_API_KEY "YOUR_SPECSTREAM_KEY"` and open a new terminal.

    ~/.zshrc or ~/.bashrc

    ```bash
    export SPECSTREAM_API_KEY="YOUR_SPECSTREAM_KEY"
    ```

2.  2

    ## 2. Add the engine file

    Snow CLI loads `.js`, `.mjs` and `.cjs` engine files from `~/.snow/plugin/search_engines/` and reloads them when a file changes, with no restart. Create the folder with `mkdir -p ~/.snow/plugin/search_engines` and save this file in it. If you set `SNOW_CONFIG_DIR`, the folder is `plugin/search_engines` under that directory.

    The engine has the `id`, `name` and `search(page, query, maxResults)` that Snow CLI's loader checks for. It returns an empty list on any failure, as Snow CLI's guide asks, and writes the reason to the log.

    ~/.snow/plugin/search\_engines/specstream.mjs

    ```javascript
    const ENDPOINT = 'https://api.specstream.ai/v1/web-search';
    
    export default {
      id: 'specstream',
      name: 'SpecStream',
    
      // Snow CLI passes a browser page; this engine calls the Search API and leaves the page unused.
      async search(page, query, maxResults) {
        const key = process.env.SPECSTREAM_API_KEY;
        if (!key) {
          console.warn('[specstream] SPECSTREAM_API_KEY is not set');
          return [];
        }
        const limit = Math.min(Math.max(maxResults || 10, 1), 20);
        const url = new URL(ENDPOINT);
        url.searchParams.set('q', query);
        url.searchParams.set('speed', 'fast');
        url.searchParams.set('num', String(limit));
        try {
          const reply = await fetch(url, {
            headers: {Authorization: `Bearer ${key}`},
            signal: AbortSignal.timeout(30000),
          });
          if (!reply.ok) {
            console.warn('[specstream] search failed', reply.status);
            return [];
          }
          const {data} = await reply.json();
          return (data?.sources || []).slice(0, limit).map(source => ({
            title: source.title || source.url,
            url: source.url,
            snippet: source.snippet || '',
            displayUrl: source.site || new URL(source.url).hostname,
          }));
        } catch (error) {
          console.warn('[specstream] search failed', error);
          return [];
        }
      },
    };
    ```

3.  3

    ## 3. Pick SpecStream in Search Engine

    Start `snow`, or type `/home` in a session to go back to the start menu, and open **Proxy & Browser Settings**. Move to **Search Engine:** with the arrow keys, press Enter, choose **SpecStream**, and press Ctrl+S or Esc to save and return.

    Snow CLI saves the choice in `~/.snow/proxy-config.json` as `"searchEngine": "specstream"`. You can also write that line in the file yourself.

4.  4

    ## 4. Ask something that needs the web

    Ask a question about something recent, so the agent calls `websearch-search`:

    In Snow CLI

    ```text
    Search the web for the latest Node.js LTS release and the date its support ends.
    ```

## What the engine changes

Snow CLI's `websearch-search` tool resolves the engine saved in `proxy-config.json`, opens a browser page and hands the search to the engine. The built-in `duckduckgo` and `bing` engines read a results page in that browser. The SpecStream engine calls `GET https://api.specstream.ai/v1/web-search` with `speed=fast` and `num` set to the tool's `maxResults`, and maps each of `data.sources` to Snow CLI's result fields: `title`, `url`, `snippet`, and `site` as `displayUrl`.

Snow CLI then applies your blocked site rules to the results as before, and `websearch-fetch` still opens the page the agent picks. Snow CLI still opens its browser page before it calls an engine, so keep a Chrome or Edge it can find, or set **Browser Path** on the same screen.

The Search API scores 97.9 F-score on all 1,000 SimpleQA Verified questions; scores and method are on the [benchmarks page](https://specstream.ai/benchmarks.md).

## What each search costs

The engine asks for the fast search: a search of up to 10 results is $0.001, $1 per 1,000. `websearch-search` asks for 10 results by default and at most 20, and a search of 20 results is $0.0022. A search that returns no results costs nothing.

Searches come out of your balance with no quote and no approval, and every call, charged or not, is in your account's request log. To cap what Snow CLI can spend, give the key a spending limit when you create it under **Agents & API**. Prices are on the [pricing page](https://specstream.ai/pricing.md).

## If searches come back empty

-   Look for a `[specstream]` line in Snow CLI's log. `SPECSTREAM_API_KEY is not set` means Snow CLI started from a shell without the key: open a new terminal and start `snow` again.
-   `search failed 401` means the key is wrong or revoked. Create a new one on the Search API screen.
-   `search failed 503` means the account used its calls for the minute. Nothing is charged; the next search goes through.
-   If **SpecStream** is not in the picker, check that the file ends in `.mjs` and look for `did not export a valid SearchEngine` in the log.

## Add the MCP server too

The engine gives Snow CLI search results. SpecStream's MCP server adds page reading and lists: `search_web`, `read_pages`, which reads up to 20 pages a call with the Extract API at $0.80 per 1,000 pages, and Deep Search, which returns every match on the live web as rows under a price you approve first.

Add it under `mcpServers` in `~/.snow/settings.json`, or in `.snow/settings.json` for one project. Merge it into the file's existing `mcpServers` rather than replacing the file. Snow CLI fills `${SPECSTREAM_API_KEY}` from the environment.

| Field | Value |
| --- | --- |
| `type` | `http` |
| `url` | `https://api.specstream.ai/mcp` |
| `headers` | `{"Authorization": "Bearer ${SPECSTREAM_API_KEY}"}` |

## Go back to DuckDuckGo or Bing

Open **Proxy & Browser Settings** and pick DuckDuckGo or Bing in **Search Engine:**. If you delete `specstream.mjs` while it is still the saved engine, Snow CLI uses DuckDuckGo. Questions: [support@specstream.ai](mailto:support@specstream.ai).

## More

[SpecStream for Snow CLI](https://specstream.ai/integrations/snow-cli.md) covers what it does in Snow CLI on one page. Every other tool has its guide in [Connect your tools](https://specstream.ai/docs/integrations.md). You see the most a request can cost before it starts, and the matches are paid from your balance. [Billing](https://specstream.ai/docs/billing.md) has the details. For help, email [support@specstream.ai](mailto:support@specstream.ai).