Skip to main content

​
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

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

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

​
TypeScript SDK

Install via npm: 
npm install s2-sdk-js
Or with other package managers: 
npm install s2-sdk-js
Compatibility: Requires SDK v0.22 or later Documentation:

​
Go SDK

Install the Go SDK: 
go get github.com/s2-streamstore/s2-sdk-go
Compatibility: Requires SDK v0.11 or later Documentation:

​
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:

​
Java SDK

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

​
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:

Build docs developers (and LLMs) love

Get started for freeTalk to us