ssecat

ssecat is a Unix command-line tool for Server-Sent Events (SSE), similar to how curl works for regular HTTP responses.

Overview

• Streams SSE over HTTP/1.1 or HTTP/2 using Go's standard net/http stack.
• Parses SSE according to the WHATWG EventSource format.
• Writes only event payload (data) to stdout by default.
• Writes diagnostics and errors to stderr.
• Supports automatic reconnect with Last-Event-ID resume.

Installation

From source

go install github.com/flaviomartins/ssecat/cmd/ssecat@latest

From release artifacts

Download binaries from GitHub Releases and place ssecat in your PATH.

Building

make build

or:

go build -o ssecat ./cmd/ssecat

Usage

ssecat [flags] URL

Flags:

• --config
• --state-dir
• --no-resume
• --header (repeatable, format: Name: Value)
• --version
• --help

Examples

Basic stream

ssecat https://stream.wikimedia.org/v2/stream/recentchange

Pipe into jq

ssecat https://stream.wikimedia.org/v2/stream/recentchange | jq .

Pipe into grep

ssecat https://stream.wikimedia.org/v2/stream/recentchange | grep Wikipedia

Pipe into awk

ssecat https://stream.wikimedia.org/v2/stream/recentchange | awk 'NR<=10 {print}'

Configuration

Single config file:

~/.config/ssecat/.ssecatrc

Supported keys:

retry=true
retry-delay=2s
resume=true
user-agent=ssecat/0.1
accept=text/event-stream

State directory

ssecat stores Last-Event-ID in the user state directory:

• Linux: ~/.local/state/ssecat
• macOS: ~/Library/Application Support/ssecat
• Windows: system user state/config directory from Go

URL path mapping is direct (sanitized), for example:

https://stream.wikimedia.org/v2/stream/recentchange

becomes:

stream.wikimedia.org/
  v2/
    stream/
      recentchange.last-event-id

Last-Event-ID and reconnect behavior

• Initial retry delay is 3 seconds by default.
• retry: fields from the server update reconnect delay.
• Transport and HTTP failures use exponential backoff with jitter and cap at 30 seconds.
• Successful reconnect resets transport backoff.
• Reconnect requests include Last-Event-ID when available.

XDG directories

• Config: ~/.config/ssecat/.ssecatrc
• State: ~/.local/state/ssecat (or OS equivalent)

Comparison with curl

curl can stream bytes but does not natively parse SSE fields. ssecat is purpose-built for EventSource streams and reconnect semantics.

Development

make fmt
make vet
make test
make build

Contributing

Contributions are welcome. Please run formatting, vet, and tests before opening pull requests.

License

MIT (see LICENSE).