Installation

Install the S2 CLI and SDKs for your platform

Installation

This guide covers installing the S2 CLI and SDKs for various platforms and languages.

S2 CLI

The S2 CLI provides command-line access to S2 and includes S2 Lite embedded as the s2 lite subcommand.

The CLI is distributed as s2-cli in package managers but the binary is named s2.

Homebrew (macOS/Linux)

The recommended way to install on macOS and Linux:

brew install s2-streamstore/s2/s2

To upgrade to the latest version:

brew upgrade s2

Cargo (Rust)

Install using Cargo if you have Rust installed:

cargo install --locked s2-cli

The --locked flag ensures you get the exact dependency versions tested with the release.

This method works on any platform with Rust installed, including Windows.

Installation script (macOS/Linux)

Download and install the latest release binary:

curl -fsSL https://raw.githubusercontent.com/s2-streamstore/s2/main/install.sh | bash

To install a specific version:

VERSION=0.29.0 curl -fsSL https://raw.githubusercontent.com/s2-streamstore/s2/main/install.sh | bash

Latest version

curl -fsSL https://raw.githubusercontent.com/s2-streamstore/s2/main/install.sh | bash

See all available versions in the releases page.

Docker

Pull the S2 Docker image which includes both the CLI and S2 Lite:

docker pull ghcr.io/s2-streamstore/s2

Run S2 Lite in a container:

# In-memory mode
docker run -p 8080:80 ghcr.io/s2-streamstore/s2 lite

# With AWS S3
docker run -p 8080:80 \
  -e AWS_PROFILE=${AWS_PROFILE} \
  -v ~/.aws:/home/nonroot/.aws:ro \
  ghcr.io/s2-streamstore/s2 lite \
  --bucket ${S3_BUCKET} \
  --path s2lite

# With static credentials (Tigris, Cloudflare R2, etc.)
docker run -p 8080:80 \
  -e AWS_ACCESS_KEY_ID=${AWS_ACCESS_KEY_ID} \
  -e AWS_SECRET_ACCESS_KEY=${AWS_SECRET_ACCESS_KEY} \
  -e AWS_ENDPOINT_URL_S3=${AWS_ENDPOINT_URL_S3} \
  ghcr.io/s2-streamstore/s2 lite \
  --bucket ${S3_BUCKET} \
  --path s2lite

The in-memory mode is perfect for integration tests and local development.

Kubernetes (Helm)

Deploy S2 Lite to Kubernetes using Helm:

helm repo add s2 https://s2-streamstore.github.io/s2
helm install my-s2-lite s2/s2-lite-helm

See the Helm chart documentation for configuration options.

Verify installation

Check that the CLI is installed correctly:

s2 --version

You should see output like:

s2-cli 0.29.18

SDKs

S2 provides official SDKs for multiple languages.

Rust SDK

Add the S2 SDK to your Cargo.toml:

cargo add s2-sdk

You’ll also need async runtime dependencies:

cargo add tokio --features full
cargo add futures

Cargo.toml

[dependencies]
s2-sdk = "0.24"
tokio = { version = "1", features = ["full"] }
futures = "0.3"

Documentation:

• Crates.io
• API docs
• Examples

TypeScript SDK

Install via npm:

npm install s2-sdk-js

Or with other package managers:

npm

npm install s2-sdk-js

Compatibility: Requires SDK v0.22 or later

Documentation:

• GitHub repository
• npm package

Go SDK

Install the Go SDK:

go get github.com/s2-streamstore/s2-sdk-go

Compatibility: Requires SDK v0.11 or later

Documentation:

• GitHub repository
• pkg.go.dev

Python SDK

The Python SDK needs to be migrated to the v1 API. It currently only supports the older API version.

Install via pip:

pip install s2-sdk-python

Documentation:

• GitHub repository

Java SDK

The Java SDK needs to be migrated to the v1 API. It currently only supports the older API version.

Documentation:

• GitHub repository

Configuration

After installation, configure the CLI and SDKs with your credentials.

Using S2 cloud

For the managed S2 service:

1. Get access token

   Generate an access token from the S2 dashboard

2. Set environment variable

   Export your access token:

   export S2_ACCESS_TOKEN="your-access-token-here"
   
3. Test connection

   Verify the configuration:

   s2 list-basins
   

Using S2 Lite

For local development with S2 Lite:

# Start S2 Lite
s2 lite --port 8080

# In another terminal, configure the CLI
export S2_ACCOUNT_ENDPOINT="http://localhost:8080"
export S2_BASIN_ENDPOINT="http://localhost:8080"
export S2_ACCESS_TOKEN="ignored"

S2 Lite doesn’t require authentication for local use, but you still need to set S2_ACCESS_TOKEN to any non-empty value.

Configuration file

You can also create a configuration file at ~/.config/s2/config.toml:

access_token = "your-access-token"

# Optional: Override endpoints for S2 Lite
# account_endpoint = "http://localhost:8080"
# basin_endpoint = "http://localhost:8080"

Building from source

To build the CLI from source:

# Clone the repository
git clone https://github.com/s2-streamstore/s2.git
cd s2

# Build with Cargo
cargo build --release --package s2-cli

# The binary will be at target/release/s2
./target/release/s2 --version

Make sure you have Rust 1.70 or later installed. The project uses Rust edition 2024.

Next steps

Quick start

Create your first basin and stream

Concepts

Learn about basins, streams, and records

CLI reference

Explore all CLI commands

API reference

Browse the REST API documentation

Getting help

If you run into issues:

• Check the GitHub issues
• Join the Discord community
• Email support at [e-mail]