S2 CLI

The official command-line interface for S2, the durable streams API. S2 is a serverless datastore for real-time, streaming data.

Installation

brew install s2-streamstore/s2/s2
# or
cargo install --locked s2-cli
# or
curl -fsSL https://raw.githubusercontent.com/s2-streamstore/s2/main/install.sh | bash

Authentication

# Preferred: environment variable
export S2_ACCESS_TOKEN="your_access_token"

# Alternative: write to config file
s2 config set access_token "your_access_token"

Quick Start

# 1. Configure auth
s2 config set access_token "$S2_ACCESS_TOKEN"

# 2. Create a basin and stream
s2 create-basin my-basin --create-stream-on-append
s2 create-stream s2://my-basin/my-stream

# 3. Append records
printf "hello\nworld\n" | s2 append s2://my-basin/my-stream --format text

# 4. Read records back
s2 read s2://my-basin/my-stream --seq-num 0 --format text

# 5. Follow live data
s2 tail s2://my-basin/my-stream --follow

# 6. Local emulation (no account required)
s2 lite --port 8080 &
export S2_ACCOUNT_ENDPOINT="http://localhost:8080"
export S2_BASIN_ENDPOINT="http://localhost:8080"
export S2_ACCESS_TOKEN="ignored"

S2 URI Format

Most stream commands accept an S2 URI:

s2://basin-name            # basin only
s2://basin-name/stream     # basin + stream
s2://basin-name/prefix/    # basin + prefix (for listing)

Interactive Mode

s2 --interactive   # or: s2 -i

References

• Configuration — Auth, endpoints, compression, environment variables
• Basins — Create, delete, list, reconfigure basins
• Streams — Create, delete, list, reconfigure, check-tail
• Records — Append, read, tail; formats and start-position options
• Fencing & Trim — Fencing tokens and stream trimming
• Access Tokens — Issue, list, revoke scoped tokens
• Metrics — Account, basin, and stream metrics
• Benchmarking — Throughput benchmarks
• S2 Lite — Self-hosted S2 API server for local development