boilstream-admin CLI

The boilstream-admin CLI tool provides cluster management, observability, and administrative operations for BoilStream deployments.

Beta

The boilstream-admin CLI is in beta. Commands and options may change in future releases.

Installation

Download alongside the main binary:

# Linux/macOS (x64, arm64)
curl -L -o boilstream-admin https://www.boilstream.com/binaries/darwin-aarch64/boilstream-admin-0.8.0
chmod +x boilstream-admin

Authentication

The CLI requires authentication to connect to BoilStream:

# Login with email/password (prompts for MFA)
boilstream-admin auth login --endpoint https://your-server.com --email admin@example.com

# Login with bootstrap token
boilstream-admin auth login --endpoint https://your-server.com --token <bootstrap-token>

# Using S3-based cluster discovery
boilstream-admin auth login --s3 s3://cluster-state-bucket/

Cluster Management

View Cluster Status

# Get cluster overview
boilstream-admin cluster status

# Output:
# Cluster Status
# ==============
# Leader: node-abc123
# Host: leader.example.com:443
# Last Heartbeat: 2s ago
#
# Brokers (3 active):
#   node-abc123 (leader) - active - last seen 2s ago
#   node-def456          - active - last seen 5s ago
#   node-ghi789          - active - last seen 3s ago

Broker Management

# List all brokers
boilstream-admin cluster brokers

# Update broker state (for rolling updates)
boilstream-admin cluster broker update <node-id> --state draining
boilstream-admin cluster broker update <node-id> --state active

# Graceful leader stepdown
boilstream-admin cluster leader stepdown
boilstream-admin cluster leader stepdown --preferred <node-id>

Broker States

State	Description
active	Normal operation, accepting traffic
draining	Finishing current work, rejecting new connections
retiring	Preparing for shutdown
shutdown	Node is shutting down

DuckLake Management

# List all DuckLake catalogs
boilstream-admin ducklakes list

# Create a new DuckLake
boilstream-admin ducklakes create my_analytics --description "Analytics catalog"

# Create a streaming DuckLake
boilstream-admin ducklakes create events__stream --description "Event streaming"

# Transfer catalog ownership
boilstream-admin ducklakes transfer my_catalog --to user@example.com

User Management

# List users
boilstream-admin users list

# Search users
boilstream-admin users search --email user@example.com

# Delete user (cascades: sessions, MFA, role assignments, catalogs)
boilstream-admin users delete user@example.com

Role Management

# List BoilStream roles
boilstream-admin roles list

# Create a role
boilstream-admin roles create data-engineers --access-level writer

# Assign role to user
boilstream-admin roles assign data-engineers --user user@example.com

# Assign role to SAML group
boilstream-admin roles assign data-engineers --group "Engineering Team"

Cloud Resources

# List cloud accounts
boilstream-admin cloud-accounts list

# List S3 buckets
boilstream-admin s3-buckets list

Hydration Management

Cold-to-hot tier data promotion:

# Service status
boilstream-admin hydration stats
boilstream-admin hydration queue
boilstream-admin hydration health

# Hydrate a table
boilstream-admin hydration table -d <ducklake_id> -n <table_name>
boilstream-admin hydration table -d <ducklake_id> -n <table_name> -p high

# Monitor progress
boilstream-admin hydration list -d <ducklake_id>
boilstream-admin hydration status -d <ducklake_id> -t <topic_id>
boilstream-admin hydration pending -d <ducklake_id>

# Eviction
boilstream-admin hydration flush -d <ducklake_id> -t <topic_id>
boilstream-admin hydration flush-all -d <ducklake_id> --yes
boilstream-admin hydration cancel -d <ducklake_id> -t <topic_id>

See Cold Tier Hydration for details.

Session Management

# List active sessions
boilstream-admin sessions list

# Revoke a session
boilstream-admin sessions revoke <session-id>

# Revoke all sessions for a user
boilstream-admin sessions revoke --user user@example.com

Configuration

# View server configuration (sensitive fields redacted)
boilstream-admin config show

Environment Variables

Variable	Description
BOILSTREAM_ENDPOINT	Default server endpoint
BOILSTREAM_AUTH_PORT	Auth server port (default: 443)
BOILSTREAM_TOKEN	Bootstrap token for authentication

Configuration File

The CLI stores session state in ~/.boilstream/config.yaml:

endpoint: https://your-server.com
auth_port: 443
session_token: <encrypted>

Common Workflows

Rolling Update

# 1. Drain a node
boilstream-admin cluster broker update node-123 --state draining

# 2. Wait for connections to finish
# 3. Stop the node, update, restart

# 4. Re-activate the node
boilstream-admin cluster broker update node-123 --state active

Leader Migration

# Graceful leader stepdown to specific node
boilstream-admin cluster leader stepdown --preferred node-456

Next Steps

• Cluster Mode - Horizontal scaling architecture
• Multi-Tenancy - Tenant isolation features
• Web Auth GUI - Browser-based administration