CLI overview

Command-line interface for managing S2 streams and basins

The S2 CLI is a command-line tool for interacting with the S2 stream store. It provides comprehensive management of basins, streams, access tokens, and records, along with benchmarking and monitoring capabilities.

Installation

The S2 CLI is distributed as a standalone binary:

# Download and install the latest version
curl -fsSL https://install.s2.dev | sh

# Verify installation
s2 --version

Quick start

Configure your access token:

s2 config set access_token YOUR_ACCESS_TOKEN

List available basins:

s2 list-basins

Create a basin and stream:

s2 create-basin my-basin
s2 create-stream s2://my-basin/events

Command structure

The CLI follows a hierarchical command structure:

s2 [COMMAND] [SUBCOMMAND] [OPTIONS] [ARGUMENTS]

Common patterns

S2 URIs - Most stream operations use the format s2://{basin}/{stream}:

s2 append s2://my-basin/events
s2 read s2://my-basin/events
s2 delete-stream s2://my-basin/events

Listing with filters - Support prefix filtering and pagination:

s2 list-basins --prefix "prod" --limit 100
s2 list-streams my-basin --prefix "events/" --start-after "events/2024"

Output formats - Record operations support multiple formats:

s2 read s2://basin/stream --format text
s2 read s2://basin/stream --format json
s2 read s2://basin/stream --format json-base64

Command categories

Basin management

• list-basins - List all basins
• create-basin - Create a new basin
• delete-basin - Delete a basin
• get-basin-config - View basin configuration
• reconfigure-basin - Update basin settings

Stream management

• list-streams - List streams in a basin
• create-stream - Create a new stream
• delete-stream - Delete a stream
• get-stream-config - View stream configuration
• reconfigure-stream - Update stream settings
• check-tail - Check the tail position of a stream

Record operations

• append - Append records to a stream
• read - Read records from a stream
• tail - Show the last N records (like Unix tail)
• trim - Set a trim point to delete old records
• fence - Set a fencing token for write coordination

Access control

• list-access-tokens - List access tokens
• issue-access-token - Create a new access token
• revoke-access-token - Revoke an access token

Monitoring

• get-account-metrics - Retrieve account-level metrics
• get-basin-metrics - Retrieve basin-level metrics
• get-stream-metrics - Retrieve stream-level metrics

Utilities

• ls - List basins or streams (convenience command)
• apply - Apply declarative spec files
• bench - Run performance benchmarks
• lite - Run local S2 Lite server

Interactive mode

Launch the interactive TUI (Terminal User Interface):

s2 -i
# or
s2 --interactive

The TUI provides a visual interface for browsing basins and streams.

Global options

s2 --help              # Show help for any command
s2 --version           # Display CLI version

Environment variables

All configuration values can be set via environment variables with the S2_ prefix:

export S2_ACCESS_TOKEN="your-token"
export S2_ACCOUNT_ENDPOINT="https://account.s2.dev"
export S2_BASIN_ENDPOINT="https://basin.s2.dev"
export S2_COMPRESSION="zstd"
export S2_SSL_NO_VERIFY="false"

Environment variables override configuration file values.

Exit codes

• 0 - Success
• 1 - General error
• 2 - Invalid arguments or usage

Next steps

Configuration

Configure authentication and endpoints

Basin management

Create and manage basins

Stream management

Create and manage streams

Record operations

Append and read records