Installation

The Spanly CLI is a small Go binary that captures MCP traffic from any server in any language, with no code changes.

Quick install (macOS, Linux)

curl -fsSL https://spanly.com/install.sh | sh

The script detects your OS and architecture, downloads the matching binary from GitHub Releases, verifies its checksum, and installs it onto your PATH. Pin a version with SPANLY_VERSION or pick a directory with SPANLY_INSTALL_DIR:

SPANLY_VERSION=0.1.0 SPANLY_INSTALL_DIR="$HOME/.local/bin" \
  sh -c "$(curl -fsSL https://spanly.com/install.sh)"

npm (recommended for MCP client configs)

npx -y @spanly/spanly run -- node ./server.js

npx fetches the right binary for your OS on first run and caches it. This is the recommended path for embedding the CLI directly in Claude Desktop, Cursor, Windsurf, and other MCP client configs. No install step required.

Homebrew (macOS, Linux)

brew install spanlyhq/tap/spanly
spanly run -- node ./server.js

Direct download

Grab the latest binary for your platform from the GitHub Releases page. Drop it on your PATH:

sudo install spanly /usr/local/bin/
spanly version

From source (Go)

go install github.com/spanlyhq/spanly/cli@latest

Installs into $(go env GOPATH)/bin as cli (the module path's last element), so rename it: mv $(go env GOPATH)/bin/cli $(go env GOPATH)/bin/spanly. Builds this way report dev for spanly version, since the version is only stamped on released binaries.

Docker

docker pull spanly/spanly:latest

See the Docker section for sidecar and compose patterns.

Configure the API key

The CLI reads SPANLY_API_KEY from the environment. The region is encoded in the prefix (spanly_us_… / spanly_eu_…) and auto-detected:

export SPANLY_API_KEY=spanly_us_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx

SPANLY_INGEST_URL overrides the ingest endpoint; you only need it for local development against a non-production Spanly stack.

Verify

spanly version
# 0.1.0

Platforms

Two modes

The CLI has two subcommands:

• spanly run: wraps your MCP server as a child process. Works for stdio and HTTP transports. This is the default path for most users.
• spanly proxy: a standalone HTTP/SSE reverse proxy. Use when you can't wrap the child (third-party services, declarative k8s sidecars, network-level interception).

Both subcommands share the same flag surface for buffering, retry, and admin endpoints. See the flag reference.