sbbb/docs/cli.md

The Remote Control 💅✨

One CLI to rule them all. sunbeam is a single Rust binary that wraps kubectl, kustomize, helm, and every service API in The Super Boujee Business Box ✨ into one command. No more juggling twelve different tools to manage your stack.

It has kustomize and helm compiled into the binary. ~50MB, zero external dependencies. Install it, configure it, and you're running infrastructure.

We built this because typing kubectl port-forward svc/openbao-0 -n data 8200:8200 followed by vault kv put secret/... is not a vibe. sunbeam vault kv put is a vibe.

---

Installation

# From source (you'll need Rust)
git clone https://src.sunbeam.pt/studio/cli.git
cd cli
cargo install --path sunbeam

# Or grab the binary from Gitea releases
sunbeam update  # self-updates from latest mainline commit

Binary lands at ~/.cargo/bin/sunbeam. Config lives at ~/.sunbeam.json.

---

Configuration

Sunbeam uses named contexts (like kubectl) to manage multiple environments.

# Set up your local dev context
sunbeam config set \
  --domain 192.168.5.2.sslip.io \
  --infra-dir /path/to/sbbb \
  --acme-email ops@sunbeam.pt

# Set up production
sunbeam config set \
  --domain sunbeam.pt \
  --host admin@62.210.145.138 \
  --infra-dir /path/to/sbbb \
  --acme-email ops@sunbeam.pt

# Switch contexts
sunbeam config use-context production
sunbeam config get  # show current

Production contexts use SSH tunneling — sunbeam forwards localhost:16443 to the remote k3s API server automatically.

---

Infrastructure Lifecycle

The big commands. These are how you go from bare metal to running stack.

sunbeam up

Full cluster bring-up. Installs cert-manager, Gateway API CRDs, Linkerd (CRDs + control plane), and sets up mkcert CA for local TLS. Run this once on a fresh cluster.

sunbeam apply [namespace]

The deploy command. Builds kustomize overlays, substitutes your domain, and applies via server-side apply.

sunbeam apply              # everything
sunbeam apply lasuite      # just La Suite apps
sunbeam apply monitoring   # just the observatory

sunbeam seed

Generates and stores ALL credentials in OpenBao — PostgreSQL passwords, OIDC secrets, DKIM keys, Django secret keys. Run once after sunbeam up. Seeds the entire vault.

sunbeam verify

End-to-end test that OpenBao + Vault Secrets Operator are syncing correctly. Creates a test secret, watches for the K8s Secret to appear, validates the content.

sunbeam bootstrap

Creates Gitea organizations, repositories, and bootstraps services. The finishing touch after everything's deployed.

---

Service Management

Day-to-day operations. The stuff you actually use every morning.

sunbeam status                  # pod health across all namespaces
sunbeam status lasuite          # scoped to a namespace
sunbeam status lasuite/drive    # scoped to a service

sunbeam logs matrix/sol -f      # stream Sol☀️ logs
sunbeam logs data/postgres      # check the database

sunbeam restart lasuite/drive   # rolling restart
sunbeam restart monitoring      # restart entire namespace

sunbeam check                   # functional health probes (not just pod readiness)
sunbeam check matrix            # check Matrix + Sol☀️

sunbeam check goes beyond pod readiness — it actually hits health endpoints, tests S3 connectivity, validates OpenSearch cluster status, checks Kratos/Hydra/Gitea/Matrix APIs. Real functional probes, not just "is the container running."

---

Build & Deploy

sunbeam build proxy             # build proxy image
sunbeam build sol --push        # build + push to Gitea registry
sunbeam build drive --push --deploy  # build + push + rollout restart
sunbeam build messages          # builds all messages components

BuildKit under the hood. Images pushed to src.DOMAIN/studio/{name}:latest.

Available build targets

proxy, integration, kratos-admin, meet, docs-frontend, people-frontend, people, messages, messages-backend, messages-frontend, messages-mta-in, messages-mta-out, messages-mpa, messages-socks-proxy, tuwunel, calendars, projects, sol

---

Service-Specific Commands

Every major service in the stack has a dedicated subcommand. These talk directly to the service APIs.

Auth & Identity — sunbeam auth

sunbeam auth login              # OAuth2 PKCE login (opens browser)
sunbeam auth token              # get/refresh access token
sunbeam auth identity list      # list all identities
sunbeam auth identity create sienna@sunbeam.pt --name "Sienna"
sunbeam auth identity get <id>

The login flow spins up a local callback server, redirects you to Hydra, captures the auth code, exchanges for tokens, and caches everything at ~/.local/share/sunbeam/auth/. Also creates a Gitea PAT on first login.

Version Control — sunbeam vcs

sunbeam vcs repo list
sunbeam vcs repo search -q "proxy"
sunbeam vcs issue list -r studio/sbbb
sunbeam vcs issue create --repo studio/sbbb --title "Bug: thing broke"

Chat — sunbeam chat

sunbeam chat rooms              # list joined Matrix rooms
sunbeam chat send <room> "hey"  # send a message
sunbeam chat users <room>       # list room members

Project Management — sunbeam pm

Unified interface across Projects and Gitea. Ticket IDs use prefixes: p:42 for Projects, g:studio/cli#7 for Gitea.

sunbeam pm list                 # all tickets, all sources
sunbeam pm list --source gitea --state open
sunbeam pm show g:studio/cli#7
sunbeam pm create "New feature" --body "Details here" --target studio/sbbb
sunbeam pm close p:42
sunbeam pm assign g:studio/cli#7 sienna

La Suite Services

# Drive
sunbeam drive list
sunbeam drive upload ./asset.png /game-assets/
sunbeam drive download <id> ./local-copy.png

# Docs
sunbeam docs list
sunbeam docs search "design document"

# Mail
sunbeam mail send --to amber@sunbeam.pt --subject "hey" --body "brunch?"
sunbeam mail folders
sunbeam mail messages inbox

# Calendar
sunbeam cal events
sunbeam cal create --title "Standup" --date 2026-03-25

# Meet
sunbeam meet rooms
sunbeam meet room create --name "Playtest"

# Search (cross-service)
sunbeam find "deployment guide"

# People
sunbeam people list
sunbeam people search "Amber"

Infrastructure Services

# OpenSearch
sunbeam search indexes
sunbeam search query sol-archive "deployment"

# S3 Storage
sunbeam storage buckets
sunbeam storage objects sunbeam-drive
sunbeam storage put sunbeam-game-assets textures/hero.png ./hero.png

# LiveKit
sunbeam media rooms
sunbeam media participants <room>

# Monitoring
sunbeam mon prometheus query 'up{job="pingora"}'
sunbeam mon loki logs '{namespace="matrix"}'
sunbeam mon grafana dashboards

# Vault
sunbeam vault status
sunbeam vault kv get secret/sol
sunbeam vault kv list secret/

Passthrough

When you need the raw tools:

sunbeam k8s get pods -n matrix   # kubectl passthrough
sunbeam bao secrets list         # bao CLI inside OpenBao pod

---

Self-Update

sunbeam update

Pulls the latest binary from your Gitea instance's releases. Checks once per day by default. SHA256 verified. Atomic binary replacement.

---

Architecture

┌─────────────────────────────────┐
│  sunbeam binary (thin CLI)      │
│  clap parsing → verb dispatch   │
└──────────┬──────────────────────┘
           │
┌──────────▼──────────────────────┐
│  sunbeam-sdk (library crate)    │
├─────────────────────────────────┤
│ Core: config, client, errors    │
│ Kube: apply, exec, tools, ssh  │
│ Ops: status, logs, restart     │
│ Secrets: OpenBao client, seed  │
│ Build: BuildKit, mirroring     │
│ Auth: OAuth2 PKCE, tokens      │
├─────────────────────────────────┤
│ Service Clients (feature-gated) │
│ identity, matrix, search, s3   │
│ media, monitoring, lasuite     │
└─────────────────────────────────┘

Two-crate workspace: thin CLI binary + SDK library with all domain logic. Feature flags control which service clients are compiled in. 232 tests across the workspace.

Source: cli repository