# 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 ```bash # 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. ```bash # 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. ```bash 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. ```bash 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 ```bash 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` ```bash 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 ``` 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` ```bash 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` ```bash sunbeam chat rooms # list joined Matrix rooms sunbeam chat send "hey" # send a message sunbeam chat users # 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. ```bash 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 ```bash # Drive sunbeam drive list sunbeam drive upload ./asset.png /game-assets/ sunbeam drive download ./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 ```bash # 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 # 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: ```bash sunbeam k8s get pods -n matrix # kubectl passthrough sunbeam bao secrets list # bao CLI inside OpenBao pod ``` --- ## Self-Update ```bash 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](../cli)