Flag reference

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

Both subcommands

Flag	Default	Description
`--buffer-size`	`10000`	Max packets buffered when ingest is unreachable. Oldest are dropped when full.
`--retry-max-attempts`	`3`	Max POST attempts per packet.
`--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).

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

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

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 can ship telemetry to any OTLP/HTTP backend in parallel with shipping to Spanly. Spans follow the official MCP semantic conventions.

Flag	Default	Description
`--otlp-endpoint`	disabled	OTLP/HTTP endpoint (overrides `OTEL_EXPORTER_OTLP_ENDPOINT`). Only `http/protobuf` is supported.
`--otlp-header`	none	`KEY=VALUE` header on OTLP requests. Repeatable.

For gRPC backends, run an OTel Collector hop and point Spanly at its HTTP receiver.

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.

Variable	Required	Description
`SPANLY_API_KEY`	yes	Region detected from prefix (`spanly_us_…` / `spanly_eu_…`).
`SPANLY_INGEST_URL`	no	Override ingest base URL (self-hosted / local dev).
`OTEL_EXPORTER_OTLP_ENDPOINT`	no	Enable OTLP co-export. Equivalent to `--otlp-endpoint`.
`OTEL_EXPORTER_OTLP_HEADERS`	no	Comma-separated `k=v` headers added to OTLP requests.
`OTEL_SERVICE_NAME`	no	Override `service.name` on emitted spans. Default `spanly-cli`.
`OTEL_RESOURCE_ATTRIBUTES`	no	Standard OTel resource attribute overrides (`k=v,k=v`).

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

Prints the CLI version, git commit, and build date.