docs: add Sunbeam CLI documentation — The Remote Control 💅✨
Infrastructure lifecycle, service management, build/deploy, all service-specific subcommands, OAuth2 PKCE login, self-update.
This commit is contained in:
279
docs/cli.md
Normal file
279
docs/cli.md
Normal file
@@ -0,0 +1,279 @@
|
||||
# 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 <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`
|
||||
|
||||
```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 <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.
|
||||
|
||||
```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 <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
|
||||
|
||||
```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 <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:
|
||||
|
||||
```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)
|
||||
Reference in New Issue
Block a user