Changelog · Oct 7, 2026 — Monocle Assess & Enforce, policy decision logging, and Install with AI.

Spur CLI

spur is Spur's official command-line client. Use it to look up IPs, check service tags, download data feeds and run filtered exports from your terminal or scripts. It also includes an MCP server, so AI assistants such as Claude can use Spur data directly.

The CLI is open source: github.com/spurintel/cli.

Install

Homebrew (macOS and Linux):

brew install spurintel/tap/spur

Go (Go 1.26.4 or later):

go install github.com/spurintel/cli/cmd/spur@latest

Prebuilt binaries for macOS, Linux and Windows (amd64 and arm64), with checksums, are on the releases page.

Check what you're running with spur version.

Authenticate

The CLI uses your Spur API token. Get one from Settings → API in the Spur app; see Get a token. The token's permissions decide which commands work: Context API for lookups, and a data feed permission for each feed you download or export (see Create a token).

Store it once in your operating system's keychain:

spur auth

The prompt hides what you type, so the token doesn't end up in your shell history. To remove it, run spur auth --logout.

The CLI looks for a token in this order:

1. The SPUR_TOKEN environment variable (useful in CI)
2. The config file (see Configuration)
3. The keychain, set by spur auth

Then check your access:

spur status

This shows whether your token is active, the queries left in your billing period, and your service tier.

Look up IPs

spur context 89.39.106.191
spur context 1.2.3.4 5.6.7.8
cat ips.txt | spur context

Each lookup is a Context API query and counts against your quota.

To pull IPs out of messy input, such as log lines or alert payloads, add --extract:

grep 'auth failure' /var/log/auth.log | spur context --extract

To see what Spur reported on a past date, add --date YYYYMMDD. Historical lookups need a Pro plan or above and a token with the Context API Historical Query permission. Without that permission the API returns 401.

Look up a service tag

Service tags such as OXYLABS_PROXY or PROTON_VPN appear in lookup results. spur tag explains a tag: its categories, whether the service anonymizes traffic, its platforms and protocols, and aggregate metrics.

spur tag OXYLABS_PROXY

Download data feeds

spur feed list                   # the supported feed types
spur feed status anonymous       # current file's date, generation time and size
spur feed download anonymous | head   # NDJSON on stdout
spur feed download anonymous -o anonymous.json.gz
spur feed download ipgeo -o ipgeo.mmdb

Without -o, a JSON feed is decompressed and streamed to stdout as newline-delimited JSON. With -o, the CLI writes the raw .json.gz; add --decompress to write plain JSON instead. MMDB files are always written raw and never printed to a terminal, so use -o for them.

Other useful flags: --date YYYYMMDD for a past release, --ipv6 and --realtime for a feed's variants, and --mmdb or --json to choose the format. You need a plan that includes the feed and a token with that feed's permission; see Data Feeds.

Export a filtered subset

spur export asks the Exports API for a filtered subset of a feed instead of the whole file:

# US-only anonymous residential IPs as CSV
spur export anonymous-residential --ccs US --csv-header -o us-resi.csv

# What changed since yesterday
spur export anonymous --diff

Filters include --ccs, --asns, --tags, --fields and --limit. Not every feed takes every filter: dch and ipgeo don't accept --tags or --limit, and dch doesn't accept --ccs. The CLI rejects an unsupported filter before it sends the request. Run spur export --help for the full list. The Exports API is rate-limited per token.

Output formats

At a terminal, results are a styled, readable report. When you pipe or redirect them, they're newline-delimited JSON, so they drop straight into scripts:

spur context 1.2.3.4 | jq .as.organization

Use --format text|json|csv to choose, and -o <file> to write to a file. (spur export is the exception: its --format sets the export file format, csv, json or mmdb, and defaults to csv.) Run spur <command> --help for every flag.

Use Spur in Claude and other AI assistants (MCP)

spur mcp runs a local Model Context Protocol server. It lets an AI assistant look up IPs, explain service tags, check your quota and work with feeds, using live Spur data and your own token. It runs on your machine and uses the same token as the CLI.

Claude Code

claude mcp add spur -e SPUR_TOKEN=your-token-here -- spur mcp

Claude Desktop

Add Spur to claude_desktop_config.json. On macOS it's in ~/Library/Application Support/Claude/, and on Windows in %APPDATA%\Claude\:

{
  "mcpServers": {
    "spur": {
      "command": "spur",
      "args": ["mcp"],
      "env": { "SPUR_TOKEN": "your-token-here" }
    }
  }
}

If you've already run spur auth, you can leave out the env block. If Claude Desktop can't find spur, use its full path, for example /opt/homebrew/bin/spur. Quit and reopen Claude Desktop after you edit the file.

Other MCP clients

Cursor, Codex CLI, LM Studio and other MCP clients work the same way: the command is spur, the argument is mcp, and the token goes in the environment.

What the assistant can do

The server also gives the assistant Spur's schemas and API docs to read, and an assess_ip prompt that runs a full assessment of one IP.

IP lookups the assistant makes are Context API queries and count against your quota.

Configuration

You don't need a config file. To override endpoints or keep named profiles, create ~/.config/spur/config.toml. If the file stores a token, keep it private (chmod 600). See the CLI README for the format.

Moving from spurctx

spur replaces the older spurctx tool, and spur mcp replaces the standalone spur-mcp server. Piped output is still one JSON object per IP, and SPUR_TOKEN still works. The migration table maps the old flags to the new commands.

Related

• Context API
• Endpoints
• Data Feeds · Exports API