Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/s2-streamstore/s2/llms.txt

Use this file to discover all available pages before exploring further.

The S2 CLI stores configuration in a TOML file and supports environment variable overrides.

​
Configuration file location

Linux/macOS: 
~/.config/s2/config.toml
Windows: 
%APPDATA%\s2\config.toml

​
Managing configuration

​
Set a value

s2 config set <key> <value>
Example: 
s2 config set access_token YOUR_ACCESS_TOKEN

​
Get a value

s2 config get <key>
Example: 
s2 config get access_token

​
List all values

s2 config list
Output: 
access_token = s2_abc123...
compression = zstd
ssl_no_verify = false

​
Unset a value

s2 config unset <key>
Example: 
s2 config unset compression

​
Configuration keys

​
access_token

Required. Your S2 access token for authentication. 
s2 config set access_token s2_abc123xyz...
Without an access token, most CLI commands will fail. You can obtain an access token from the S2 console or by using the issue-access-token command with a parent token.

​
account_endpoint

Custom account API endpoint URL. Must be set together with basin_endpoint. 
s2 config set account_endpoint https://account.s2.example.com
Both account_endpoint and basin_endpoint must be set to use custom endpoints. If only one is set, the CLI will fall back to default endpoints.

​
basin_endpoint

Custom basin API endpoint URL. Must be set together with account_endpoint. 
s2 config set basin_endpoint https://basin.s2.example.com

​
compression

Request/response compression algorithm. Options: gzip, zstd. 
s2 config set compression zstd
Default: No compression (none) Benefits:
  • Reduces network bandwidth
  • Faster for large payloads
  • zstd typically offers better compression ratios

​
ssl_no_verify

Disable SSL certificate verification. Options: true, false. 
s2 config set ssl_no_verify true
Default: false
Only use ssl_no_verify=true in development/testing environments. Disabling certificate verification in production is a security risk.

​
Environment variables

All configuration keys can be overridden using environment variables with the S2_ prefix: 
export S2_ACCESS_TOKEN="s2_abc123..."
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 take precedence over configuration file values.

​
Example: Using environment variables for CI/CD

#!/bin/bash
# deploy.sh

export S2_ACCESS_TOKEN="${CI_S2_TOKEN}"
export S2_COMPRESSION="zstd"

s2 append s2://prod/deployments <<EOF
{"version": "1.2.3", "timestamp": "$(date -Iseconds)"}
EOF

​
Example configuration file

# ~/.config/s2/config.toml

access_token = "s2_abc123xyz..."
compression = "zstd"
ssl_no_verify = false

# Custom endpoints (optional)
# account_endpoint = "https://account.s2.dev"
# basin_endpoint = "https://basin.s2.dev"

​
Authentication

The CLI uses the access token specified in access_token for all API requests. Tokens are included in the Authorization header: 
Authorization: Bearer s2_abc123...

​
Token management

Access tokens can have:
  • Expiration dates
  • Scoped permissions (basins, streams, operations)
  • Automatic stream prefixing
See Access tokens for details.

​
Obtaining your first token

  1. Sign up at s2.dev
  2. Create an access token in the console
  3. Configure the CLI:
s2 config set access_token YOUR_TOKEN

​
Creating scoped tokens from the CLI

Once you have a parent token configured, you can issue child tokens with restricted permissions: 
s2 issue-access-token \
  --id "ci-deployment-token" \
  --expires-in "90d" \
  --basins "prod" \
  --streams "deployments/" \
  --ops "append,read"
This creates a token that can only append and read from streams with the deployments/ prefix in the prod basin.

​
Configuration priority

Configuration values are resolved in this order (highest to lowest priority):
  1. Environment variables (S2_*)
  2. Configuration file (~/.config/s2/config.toml)
  3. Default values

​
Troubleshooting

​
Permission denied when writing config

Ensure the config directory exists and is writable: 
mkdir -p ~/.config/s2
chmod 700 ~/.config/s2

​
Invalid access token error

Verify your token is set correctly: 
s2 config get access_token
Ensure there are no extra spaces or quotes in the token value.

​
Certificate verification failed

If you’re using custom endpoints with self-signed certificates (development only): 
s2 config set ssl_no_verify true
Never disable SSL verification in production.

Build docs developers (and LLMs) love

Get started for freeTalk to us