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

```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)