flamingo-stack · github-actions · Jun 4, 2026 · Jun 4, 2026 · Jun 4, 2026 · Jun 4, 2026
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
diff --git a/README.md b/README.md
@@ -12,197 +12,265 @@
 
 # OpenFrame CLI
 
-OpenFrame CLI is a modern, interactive command-line tool for managing OpenFrame Kubernetes clusters and development workflows. It provides seamless cluster lifecycle management, chart installation with ArgoCD, and developer-friendly tools for service intercepts and scaffolding.
+**OpenFrame CLI** is a modern, interactive command-line tool written in Go that bootstraps and manages OpenFrame Kubernetes environments. It is the primary entry point for spinning up fully functional, production-grade [OpenFrame](https://openframe.ai) deployments on local or remote Kubernetes clusters — in minutes, not days.
 
-[![OpenFrame Preview Webinar](https://img.youtube.com/vi/bINdW0CQbvY/maxresdefault.jpg)](https://www.youtube.com/watch?v=bINdW0CQbvY)
+OpenFrame CLI automates the full lifecycle of an OpenFrame environment: cluster provisioning, GitOps installation via ArgoCD, interactive Helm values configuration, and developer tooling for Telepresence intercepts and Skaffold hot-reload workflows.
 
-## What is OpenFrame CLI?
+It is part of the broader [OpenFrame](https://openframe.ai) platform — the unified, AI-driven MSP operations suite built by [Flamingo](https://flamingo.run).
 
-OpenFrame CLI is part of the broader [OpenFrame](https://openframe.ai) ecosystem - an AI-powered MSP platform that replaces expensive proprietary software with open-source alternatives enhanced by intelligent automation. The CLI serves as the entry point for developers and operators to bootstrap, manage, and develop on OpenFrame environments.
+---
 
-## Key Features
+[![OpenFrame v0.5.2: Live Demo of AI-Powered IT Management for MSPs](https://img.youtube.com/vi/a45pzxtg27k/maxresdefault.jpg)](https://www.youtube.com/watch?v=a45pzxtg27k)
 
-### 🚀 Complete Environment Bootstrapping
-- **One-command setup**: Bootstrap entire OpenFrame environments with `openframe bootstrap`
-- **Multi-mode deployment**: Support for OSS tenant, SaaS tenant, and SaaS shared modes
-- **Automated cluster creation**: Creates K3D clusters with all necessary components
-- **ArgoCD integration**: Automatic chart installation and application management
+---
 
-### 🔧 Cluster Management
-- **Lifecycle operations**: Create, delete, list, and monitor Kubernetes clusters
-- **K3D integration**: Lightweight Kubernetes for development and testing
-- **Status monitoring**: Real-time cluster health and resource monitoring
-- **Easy cleanup**: Remove clusters and associated resources with simple commands
+## ✨ Features
 
-### 📦 Chart & Application Management
-- **Helm chart installation**: Streamlined chart deployment with dependency management
-- **ArgoCD applications**: GitOps-based application lifecycle management
-- **App-of-apps pattern**: Hierarchical application management for complex deployments
-- **Synchronization monitoring**: Track deployment progress with detailed logging
+| Feature | Description |
+|---|---|
+| **One-command bootstrap** | `openframe bootstrap` provisions a cluster and installs all charts end-to-end |
+| **Interactive wizard** | Guided Helm values configuration — branch, Docker registry, ingress, deployment mode |
+| **K3D cluster management** | Create, delete, list, status, and cleanup local K3D clusters |
+| **ArgoCD GitOps** | Installs ArgoCD and deploys app-of-apps patterns with health monitoring |
+| **Telepresence intercepts** | Route live Kubernetes traffic to your local machine for rapid iteration |
+| **Skaffold hot-reload** | Rebuild and sync containers on code change within a running cluster |
+| **Non-interactive / CI mode** | All commands support `--non-interactive` flags for CI/CD pipelines |
+| **Cross-platform** | Supports macOS, Linux, and Windows (WSL2) |
+| **Prerequisite auto-installer** | Automatically detects and guides installation of Docker, k3d, kubectl, Helm, and more |
 
-### 🛠 Development Tools
-- **Service intercepts**: Local development with Telepresence integration
-- **Scaffolding**: Generate boilerplate code and configurations
-- **Live debugging**: Debug services running in Kubernetes from your local environment
-- **Hot reload**: Rapid development cycles with instant feedback
+---
 
-## Architecture Overview
+## 🏗️ Architecture
 
 ```mermaid
 graph TB
-    subgraph "CLI Commands"
-        Bootstrap[openframe bootstrap]
-        Cluster[openframe cluster]
-        Chart[openframe chart]
-        Dev[openframe dev]
+    subgraph CLI["CLI Layer (cmd/)"]
+        Root["openframe (root)"]
+        BootstrapCmd["bootstrap"]
+        ClusterCmd["cluster"]
+        ChartCmd["chart"]
+        DevCmd["dev"]
     end
-
-    subgraph "Core Services"
-        ClusterSvc[Cluster Management]
-        ChartSvc[Chart Installation]
-        DevSvc[Development Tools]
+
+    subgraph Services["Internal Services"]
+        BootstrapSvc["Bootstrap Service"]
+        ClusterSvc["Cluster Service"]
+        ChartSvc["Chart Service"]
+        DevSvc["Dev Services"]
     end
-
-    subgraph "External Tools"
-        K3D[K3D Clusters]
-        Helm[Helm Charts]
-        ArgoCD[ArgoCD Apps]
-        Telepresence[Service Intercepts]
+
+    subgraph Providers["External Tool Providers"]
+        K3D["K3D"]
+        Helm["Helm"]
+        ArgoCD["ArgoCD"]
+        Git["Git"]
+        Telepresence["Telepresence"]
+        Skaffold["Skaffold"]
     end
-    
-    subgraph "Target Environment"
-        K8s[Kubernetes]
-        Apps[Applications]
-        Services[Microservices]
+
+    subgraph Target["Deployed Environment"]
+        K8s["Kubernetes Cluster"]
+        Apps["ArgoCD Applications"]
+        Services2["OpenFrame Microservices"]
     end
-
-    Bootstrap --> ClusterSvc
-    Bootstrap --> ChartSvc
-    Cluster --> ClusterSvc
-    Chart --> ChartSvc
-    Dev --> DevSvc
-
+
+    Root --> BootstrapCmd
+    Root --> ClusterCmd
+    Root --> ChartCmd
+    Root --> DevCmd
+
+    BootstrapCmd --> BootstrapSvc
+    ClusterCmd --> ClusterSvc
+    ChartCmd --> ChartSvc
+    DevCmd --> DevSvc
+
+    BootstrapSvc --> ClusterSvc
+    BootstrapSvc --> ChartSvc
+
     ClusterSvc --> K3D
     ChartSvc --> Helm
     ChartSvc --> ArgoCD
+    ChartSvc --> Git
     DevSvc --> Telepresence
-
+    DevSvc --> Skaffold
+
     K3D --> K8s
     Helm --> Apps
     ArgoCD --> Apps
-    Telepresence --> Services
+    Apps --> Services2
 ```
 
-## Quick Start
+---
+
+## 🖥️ Hardware Requirements
+
+| Tier | RAM | CPU Cores | Disk Space |
+|---|---|---|---|
+| **Minimum** | 24 GB | 6 cores | 50 GB |
+| **Recommended** | 32 GB | 12 cores | 100 GB |
 
-Get OpenFrame CLI up and running in 5 minutes!
+> K3D runs Kubernetes nodes as Docker containers. Insufficient memory is the most common cause of failed bootstraps — ensure Docker has access to at least 16 GB RAM.
 
-### System Requirements
+---
 
-| Resource | Minimum | Recommended |
-|----------|---------|-------------|
-| **RAM** | 24GB | 32GB |
-| **CPU Cores** | 6 cores | 12 cores |
-| **Disk Space** | 50GB free | 100GB free |
+## 🚀 Quick Start
 
-### Prerequisites
+### Step 1 — Install the CLI
 
-Before installation, ensure you have:
-- [Docker](https://docs.docker.com/get-docker/) 20.10+
-- [kubectl](https://kubernetes.io/docs/tasks/tools/) 1.25+
-- [Helm](https://helm.sh/docs/intro/install/) 3.10+
-- [K3D](https://k3d.io/v5.4.6/#installation) 5.0+
+#### macOS (Apple Silicon)
 
-### Installation
+```bash
+curl -L https://github.com/flamingo-stack/openframe-cli/releases/latest/download/openframe-cli_darwin_arm64.tar.gz | tar xz
+chmod +x openframe
+sudo mv openframe /usr/local/bin/
+```
+
+#### macOS (Intel)
 
-Choose your platform and install OpenFrame CLI:
+```bash
+curl -L https://github.com/flamingo-stack/openframe-cli/releases/latest/download/openframe-cli_darwin_amd64.tar.gz | tar xz
+chmod +x openframe
+sudo mv openframe /usr/local/bin/
+```
 
 #### Linux (AMD64)
+
 ```bash
-curl -fsSL https://github.com/flamingo-stack/openframe-cli/releases/latest/download/openframe-cli_linux_amd64.tar.gz | tar -xz
+curl -L https://github.com/flamingo-stack/openframe-cli/releases/latest/download/openframe-cli_linux_amd64.tar.gz | tar xz
+chmod +x openframe
 sudo mv openframe /usr/local/bin/
-chmod +x /usr/local/bin/openframe
 ```
 
-#### macOS (Apple Silicon)
+#### Linux (ARM64)
+
 ```bash
-curl -fsSL https://github.com/flamingo-stack/openframe-cli/releases/latest/download/openframe-cli_darwin_arm64.tar.gz | tar -xz
+curl -L https://github.com/flamingo-stack/openframe-cli/releases/latest/download/openframe-cli_linux_arm64.tar.gz | tar xz
+chmod +x openframe
 sudo mv openframe /usr/local/bin/
-chmod +x /usr/local/bin/openframe
 ```
 
-#### Windows (WSL2)
-1. Download: https://github.com/flamingo-stack/openframe-cli/releases/latest/download/openframe-cli_windows_amd64.zip
-2. Extract and move `openframe.exe` to a directory in your `PATH`
-3. Open WSL2 terminal and verify access
+#### Windows (AMD64)
 
-### Bootstrap Your Environment
+1. Download: [openframe-cli_windows_amd64.zip](https://github.com/flamingo-stack/openframe-cli/releases/latest/download/openframe-cli_windows_amd64.zip)
+2. Extract the zip archive
+3. Move `openframe.exe` to a directory in your `PATH` (e.g., `C:\Windows\System32\` or a custom tools folder)
 
-Create a complete OpenFrame environment with a single command:
+> **Windows users**: Run all commands from a WSL2 terminal for the best experience.
 
-```bash
-# Verify installation
-openframe --version
+---
 
-# Bootstrap complete environment
+### Step 2 — Bootstrap Your Environment
+
+```bash
+# Interactive bootstrap (recommended for first-time users)
 openframe bootstrap
 
+# Non-interactive (CI/CD)
+openframe bootstrap my-cluster --deployment-mode=oss-tenant --non-interactive
+```
+
+The `bootstrap` command will:
+
+1. Check and guide installation of any missing prerequisites (Docker, k3d, kubectl, Helm, Git, mkcert)
+2. Create a local K3D Kubernetes cluster
+3. Install ArgoCD via Helm
+4. Clone and deploy the app-of-apps GitOps chart
+5. Wait for all ArgoCD applications to become Healthy and Synced
+
+> Typical bootstrap time: **5–15 minutes** depending on network speed and hardware.
+
+---
+
+### Step 3 — Verify
+
+```bash
 # Check cluster status
-openframe cluster status
+openframe cluster status my-openframe
+
+# List all managed clusters
+openframe cluster list
 ```
 
-The bootstrap process creates:
-- K3D Kubernetes cluster
-- ArgoCD for GitOps deployment
-- Traefik ingress controller
-- Core monitoring and logging components
+---
+
+[![Getting Started with OpenFrame - Organization Setup Basics](https://img.youtube.com/vi/-_56_qYvMWk/maxresdefault.jpg)](https://www.youtube.com/watch?v=-_56_qYvMWk)
 
-## Core Commands
+---
+
+## 📦 Deployment Modes
+
+| Mode | Repository | Use Case |
+|---|---|---|
+| `oss-tenant` | `openframe-oss-tenant` | Default self-hosted OpenFrame deployment |
+| `saas-tenant` | `openframe-saas-tenant` | SaaS managed tenant deployment |
+| `saas-shared` | `openframe-saas-shared` | Shared SaaS infrastructure deployment |
+
+> For most operators getting started, `oss-tenant` is the recommended deployment mode.
+
+---
+
+## 🧰 CLI Command Reference
 
-| Command | Description | Example |
-|---------|-------------|---------|
-| `openframe bootstrap` | Complete environment setup | `openframe bootstrap my-cluster` |
-| `openframe cluster create` | Create Kubernetes cluster | `openframe cluster create --nodes 3` |
-| `openframe cluster delete` | Remove existing cluster | `openframe cluster delete my-cluster` |
-| `openframe cluster status` | Show cluster information | `openframe cluster status` |
-| `openframe chart install` | Install charts with ArgoCD | `openframe chart install` |
-| `openframe dev intercept` | Start service intercepts | `openframe dev intercept my-service` |
+| Command | Description |
+|---|---|
+| `openframe bootstrap [name]` | Full environment setup: cluster create + chart install |
+| `openframe cluster create [name]` | Create a K3D cluster |
+| `openframe cluster delete [name]` | Delete a cluster |
+| `openframe cluster list` | List all managed clusters |
+| `openframe cluster status [name]` | Show cluster health and ArgoCD app status |
+| `openframe cluster cleanup [name]` | Remove unused Docker images and resources |
+| `openframe chart install [name]` | Install ArgoCD + app-of-apps on a cluster |
+| `openframe dev intercept [service]` | Start a Telepresence intercept for local development |
+| `openframe dev skaffold [cluster]` | Run a Skaffold hot-reload workflow |
 
-## Technology Stack
+---
 
-OpenFrame CLI integrates with industry-standard tools:
+## 🔧 Technology Stack
+
+| Component | Technology |
+|---|---|
+| Language | Go |
+| CLI framework | [Cobra](https://github.com/spf13/cobra) |
+| Terminal UI | [pterm](https://github.com/pterm/pterm) |
+| Interactive prompts | [promptui](https://github.com/manifoldco/promptui) |
+| Kubernetes client | [client-go](https://pkg.go.dev/k8s.io/client-go) |
+| ArgoCD client | [argo-cd/v2](https://pkg.go.dev/github.com/argoproj/argo-cd/v2) |
+| YAML processing | [sigs.k8s.io/yaml](https://pkg.go.dev/sigs.k8s.io/yaml), [gopkg.in/yaml.v3](https://pkg.go.dev/gopkg.in/yaml.v3) |
+| Testing | [testify](https://github.com/stretchr/testify) |
+| Cluster provider | K3D |
+| GitOps | ArgoCD + Helm app-of-apps |
 
-- **Kubernetes**: Container orchestration with K3D for development
-- **ArgoCD**: GitOps continuous deployment
-- **Helm**: Package management for Kubernetes
-- **Telepresence**: Local development with remote services
-- **Docker**: Container runtime and image management
-- **Cobra**: Modern CLI framework with rich help and completion
+---
 
-## Documentation
+## 📚 Documentation
 
-📚 See the [Documentation](./docs/README.md) for comprehensive guides including:
+Comprehensive documentation is available in the [`docs/`](./docs/README.md) directory:
 
-- **Getting Started**: Prerequisites, installation, and first steps
-- **Development**: Local setup, architecture, and contribution guidelines  
-- **Reference**: Technical documentation, API specs, and configuration
-- **CLI Tools**: Links to external repositories and tools
+- **[Getting Started](./docs/README.md)** — Prerequisites, quick start, and first steps
+- **[Development Guides](./docs/README.md)** — Local setup, architecture, testing, contributing
+- **[Reference](./docs/README.md)** — Full architecture reference and component documentation
 
-## Community and Support
+---
 
-OpenFrame is built by the community for the community:
+## 🤝 Community & Support
 
-- **OpenMSP Slack**: [Join the community](https://join.slack.com/t/openmsp/shared_invite/zt-36bl7mx0h-3~U2nFH6nqHqoTPXMaHEHA) - Primary support channel
-- **Website**: [https://flamingo.run](https://flamingo.run)
-- **OpenFrame Platform**: [https://openframe.ai](https://openframe.ai)
+> **Support happens in Slack, not GitHub Issues.**
 
-> **Note**: We don't use GitHub Issues or Discussions. All support and community interaction happens in the OpenMSP Slack community.
+| Resource | Link |
+|---|---|
+| OpenMSP Community | [openmsp.ai](https://www.openmsp.ai/) |
+| Slack Invite | [Join OpenMSP Slack](https://join.slack.com/t/openmsp/shared_invite/zt-36bl7mx0h-3~U2nFH6nqHqoTPXMaHEHA) |
+| OpenFrame Platform | [openframe.ai](https://openframe.ai) |
+| Flamingo | [flamingo.run](https://flamingo.run) |
 
-## License
+---
 
-This project is licensed under the Flamingo AI Unified License v1.0 - see the [LICENSE.md](LICENSE.md) file for details.
+## 🤲 Contributing
+
+We welcome contributions! Please read our [Contributing Guidelines](./CONTRIBUTING.md) before opening a pull request.
 
 ---
+
 <div align="center">
   Built with 💛 by the <a href="https://www.flamingo.run/about"><b>Flamingo</b></a> team
-</div>
+</div>