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. See the GitHub releases page for the latest version and platform-specific download links.

bash

# Example: Linux/macOS (check releases page for latest version)
curl -L -o boilstream-admin https://www.boilstream.com/binaries/darwin-aarch64/boilstream-admin-{VERSION}
chmod +x boilstream-admin

Authentication

The CLI requires authentication to connect to BoilStream:

bash

# 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/

Kubernetes / Helm deployments

When you install BoilStream via the Helm chart, the superadmin password and MFA secret live in Kubernetes Secrets in your release namespace. The CLI reads them out of local files; the standard workflow is to kubectl get secret ... | base64 -d them into a directory under ~/.boilstream/<profile>/ and point a CLI profile at those paths. This makes every subsequent CLI call fully non-interactive — no prompts, no TTY required — so the same commands work from a shell, a cron job, or a CI pipeline.

One-time setup (per cluster):

bash

# Replace: NS=namespace, PROFILE=your-profile-name,
#          SERVER=https://app.your-deployment.com
export NS=boilstream
export PROFILE=prod
export SERVER=https://app.your-deployment.com

mkdir -p ~/.boilstream/$PROFILE
chmod 700 ~/.boilstream/$PROFILE

# Pull the password and MFA secret out of the cluster.
# The chart puts them in these two Secrets by default; adjust if you
# deployed with --set superadmin.existingSecret / existingMfaSecret.
kubectl get secret -n $NS boilstream-superadmin \
  -o jsonpath='{.data.password}' | base64 -d \
  > ~/.boilstream/$PROFILE/password.txt
kubectl get secret -n $NS boilstream-superadmin-mfa \
  -o jsonpath='{.data.mfa_secret}' | base64 -d \
  > ~/.boilstream/$PROFILE/mfa_secret.txt
chmod 600 ~/.boilstream/$PROFILE/*.txt

# Point the profile at the cluster + those files.
boilstream-admin --profile $PROFILE config set auth_server $SERVER
boilstream-admin --profile $PROFILE config set password_path \
  ~/.boilstream/$PROFILE/password.txt
boilstream-admin --profile $PROFILE config set mfa_secret_path \
  ~/.boilstream/$PROFILE/mfa_secret.txt

# First login caches a session cookie.
boilstream-admin --profile $PROFILE auth login

Daily usage — session is reused until it expires (~1 h):

bash

boilstream-admin --profile $PROFILE catalog list
boilstream-admin --profile $PROFILE catalog credentials <catalog-id>
boilstream-admin --profile $PROFILE user list

What each file holds:

File	Source Secret / Key	Permissions
`~/.boilstream/$PROFILE/password.txt`	`boilstream-superadmin` / `password`	`0600`
`~/.boilstream/$PROFILE/mfa_secret.txt`	`boilstream-superadmin-mfa` / `mfa_secret`	`0600`
`~/.boilstream/$PROFILE/config.yaml`	written by `config set` commands	`0600`
`~/.boilstream/sessions/$PROFILE.json`	written by `auth login` (session cookie)	`0600`

Setting up your TOTP authenticator app (one-time, for the operator who installed the chart). The same base32 string in mfa_secret.txt is what you'd scan from a QR code — paste it into Authy/1Password/Google Authenticator as a manual entry (algorithm SHA-1, digits 6, period 30) and you can log in to https://app.your-deployment.com/ interactively too.

Rotating the superadmin password:

bash

kubectl delete secret -n $NS boilstream-superadmin
kubectl create secret generic boilstream-superadmin \
  --from-literal=password="$(openssl rand -base64 32)" \
  -n $NS
kubectl rollout restart statefulset/boilstream -n $NS
# Re-run the one-time setup above to refresh password.txt.

The MFA secret is sticky across pod restarts and helm upgrades (helm.sh/resource-policy: keep on the Secret) so authenticator apps keep working — rotate it only deliberately, and have the TOTP app rescan the new secret when you do.

Cluster Management

View Cluster Status

bash

# 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

bash

# 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

Multi-Raft (cp-metadata) Operations

The control-plane metadata catalog (cp-metadata) is the Quack Multi-Raft consistency layer used by clustered deployments. Consensus and leader forwarding are owned by quack-raft, so the CLI exposes status (from quack's quack_raft_status()) plus local multi-node config tooling.

bash

# cp-metadata (quack-raft) health from the selected server
boilstream-admin cp-metadata status

# Validate a set of per-node configs before standing up a cluster
boilstream-admin cp-metadata validate-config node0.yaml node1.yaml node2.yaml

# Generate deterministic local OS-process configs for N nodes
boilstream-admin cp-metadata generate-local-configs --nodes 3

In cp-metadata status, treat these as operational alarms:

Field	Alarm condition
`Health`	`not ok`
`Leader`	`-` (no known leader) for longer than a normal election
`Linearizable Read Safe`	`false` when linearizable reads are expected

See Multi-Raft for the consistency model, SQL interface, and configuration.

DuckLake Management

bash

# 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

bash

# 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

bash

# 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

bash

# List cloud accounts
boilstream-admin cloud-accounts list

# List S3 buckets
boilstream-admin s3-buckets list

Hydration Management

Cold-to-hot tier data promotion:

bash

# 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

bash

# 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

Server Management

bash

# Start/stop server
boilstream-admin server start --config local-dev.yaml
boilstream-admin server stop
boilstream-admin server status
boilstream-admin server logs --follow

# Check for updates
boilstream-admin server check-update

# Upgrade (shows platform-specific instructions)
boilstream-admin server upgrade --dry-run
boilstream-admin server upgrade --config local-dev.yaml

Config Upgrade

The server binary supports config migration between versions:

bash

# Preview changes (AI/human readable)
./boilstream --upgrade-config config.yaml --dry-run

# Apply upgrade (creates config-0.8.2.yaml)
./boilstream --upgrade-config config.yaml

Configuration

bash

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

yaml

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

Common Workflows

Rolling Update

bash

# 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

bash

# 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

boilstream-admin CLI ​

Installation ​

Authentication ​

Kubernetes / Helm deployments ​

Cluster Management ​

View Cluster Status ​

Broker Management ​

Broker States ​

Multi-Raft (cp-metadata) Operations ​

DuckLake Management ​

User Management ​

Role Management ​

Cloud Resources ​

Hydration Management ​

Session Management ​

Server Management ​

Config Upgrade ​

Configuration ​

Environment Variables ​

Configuration File ​

Common Workflows ​

Rolling Update ​

Leader Migration ​

Next Steps ​

boilstream-admin CLI

Installation

Authentication

Kubernetes / Helm deployments

Cluster Management

View Cluster Status

Broker Management

Broker States

Multi-Raft (cp-metadata) Operations

DuckLake Management

User Management

Role Management

Cloud Resources

Hydration Management

Session Management

Server Management

Config Upgrade

Configuration

Environment Variables

Configuration File

Common Workflows

Rolling Update

Leader Migration

Next Steps