Flag reference

This page is the authoritative flag reference. spanly run and spanly proxy share most flags; differences are called out below.

Both subcommands

Buffer & retry

Flag	Default	Description
`--buffer-size`	`10000`	Max packets buffered when ingest is unreachable. Oldest are dropped when full.
`--collect-max-attempts`	`4`	Max POST attempts per packet (deprecated alias: `--retry-max-attempts`).
`--retry-backoff`	`1s`	Initial retry backoff (exponential).
`--retry-max-backoff`	`30s`	Cap on retry backoff.
`--shutdown-grace`	`10s`	Time to flush in-flight telemetry on shutdown (SIGINT/SIGTERM).

Multi-tenant tagging

Flag	Default	Description
`--context-header`	none	`HEADER=field` mapping. Repeatable. Fields: `environmentId`, `projectId`, `organisationId`.

Example:

spanly run --port 3000 \
  --context-header=X-Tenant=environmentId \
  --context-header=X-Org=organisationId \
  -- ./srv

Header redaction (HTTP / proxy only)

Flag	Default	Description
`--redact-header`	none	Additional header to redact from captured telemetry. Repeatable.

Authorization, Cookie, Set-Cookie, Proxy-Authorization, X-Api-Key, X-Auth-Token, X-Amz-Security-Token and X-Forwarded-Authorization are always redacted: their values are replaced with [REDACTED] in the captured packet. The proxied request and response keep their original headers.

Example:

spanly run --port 3000 --redact-header=X-Custom-Token -- ./srv

Inspection scope (HTTP / proxy only)

Flag	Default	Description
`--inspect-prefix`	`/mcp,/sse`	Comma-separated path prefixes to inspect. Empty = inspect all paths.

End-user identity (HTTP / proxy only)

Flag	Default	Description
`--identity-jwt`	off	Decode the bearer JWT with the default claim mapping: id from `sub`, email from `email`, name from `name`. No signature verification.
`--identity-jwt-claim`	none	`field=claim` mapping override, repeatable. Fields: `id`, `email`, `name`, `accountId`, `accountName`. Dot-paths supported. Implies `--identity-jwt`.
`--identity-resolver-url`	none	URL of your token-to-user resolver endpoint.
`--identity-resolver-secret`	none	Shared secret sent as `X-Spanly-Identity-Secret`. Also via `SPANLY_IDENTITY_RESOLVER_SECRET` (the flag wins).
`--no-auth-fingerprint`	off	Disable the anonymous bearer-token fingerprint attached to telemetry in HTTP mode.

Attributes captured sessions to your end users. See Identify your users for the setup guide and the resolver protocol for the endpoint contract. In stdio mode these flags are ignored with a warning (no auth headers to read).

Example:

spanly run --port 3000 \
  --identity-jwt \
  --identity-jwt-claim=accountId=org_id \
  -- ./srv

Session ID injection (HTTP / proxy only)

Flag	Default	Description
`--inject-session-id`	`true`	Assign a synthetic `Mcp-Session-Id` on initialize responses when the upstream does not set one.

When the upstream server runs sessionless, its initialize responses carry no Mcp-Session-Id, so Spanly cannot group requests into sessions. With this flag enabled (the default), the proxy assigns a synthetic session ID (prefixed spanly-) on initialize responses that don't already have one. The client echoes it on subsequent requests and the proxy strips it before forwarding upstream, so the upstream never sees a header it didn't create. Servers that assign their own session IDs are untouched. See Session tracking.

Disable with:

spanly run --port 3000 --inject-session-id=false -- ./srv

Admin endpoints

Flag	Default	Description
`--admin-addr`	disabled	If set (e.g. `:9090`), exposes `/healthz`, `/readyz`, `/metrics`.

Endpoints when enabled:

GET /healthz: 200 if the listener is up.
GET /readyz: 200 if the upstream is reachable (1s cache).
GET /metrics: Prometheus text format. Counters: packets collected / sent / dropped / failed, retry attempts, buffer depth, request counts by inspection class.

`spanly run` only

Flag	Default	Description
`--port`	`0`	If set, run in HTTP mode (wrapper takes this port; child gets a random one). Default `0` = stdio.
`--child-port`	`0`	Port the child binds in HTTP mode. `0` = pick random unused port.
`--child-port-env`	`PORT`	Env var passed to child with the chosen port.
`--child-startup-timeout`	`30s`	Max wait for child to listen.

proxy does not accept these. The bind address is positional.

Environment variables

Variable	Required	Description
`SPANLY_API_KEY`	yes	Region detected from prefix (`spanly_us_…` / `spanly_eu_…`).
`SPANLY_INGEST_URL`	no	Override ingest base URL (local development against a non-production stack).

Per-request headers

The CLI recognizes the following inbound headers on every captured request:

Header	Effect
`X-Spanly-Monitor-Id`	Override `spanlyMonitorId` for this request. Useful for joining many requests under one logical session.
Any header named in `--context-header`	Maps to the matching context field on the captured packet.

`spanly version`

spanly version

Prints the CLI version.

Flag reference

On this page