The S2 CLI stores configuration in a TOML file and supports environment variable overrides.
Configuration file location
Linux/macOS:
Windows:
Managing configuration
Set a value
s2 config set <key> <value>
s2 config set access_token YOUR_ACCESS_TOKEN
Get a value
Example:
s2 config get access_token
List all values
Output:
access_token = s2_abc123...
compression = zstd
ssl_no_verify = false
Unset a value
Example:
s2 config unset compression
Configuration keys
access_token
Required. Your S2 access token for authentication.
s2 config set access_token s2_abc123xyz...
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
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
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"
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
- Sign up at s2.dev
- Create an access token in the console
- 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"
deployments/ prefix in the prod basin.
Configuration priority
Configuration values are resolved in this order (highest to lowest priority):
- Environment variables (
S2_*)
- Configuration file (
~/.config/s2/config.toml)
- 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
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.