OpenFrame Documentation

Overview

This section is the entry point for contributing to OpenFrame CLI, the Go-based command-line tool that provisions Kubernetes clusters (local k3d, or cloud GKE/EKS via Terraform) and deploys the OpenFrame platform onto them through ArgoCD's app-of-apps pattern.

OpenFrame CLI is published to the Go ecosystem as github.com/flamingo-stack/openframe-cli. Per the repository graph, it is a leaf/terminal artifact: it has no recorded upstream dependencies on other repositories in this organization, and no repository is currently recorded as consuming it. Its functional dependencies are third-party Go modules (Cobra, client-go, pterm, huh, bubbletea, sigstore-go) and external CLI tools it shells out to (Docker, k3d, Helm, Terraform, gcloud, aws), not sibling repositories.

Note on scope: This document is the development hub for the openframe-cli repository itself. The broader OpenFrame platform that this CLI installs onto a cluster lives in the separate flamingo-stack/openframe-oss-tenant repository. If you are looking to develop or modify the platform charts/services deployed by openframe app install, refer to that repository directly rather than assuming its code lives in a subdirectory here.

Use this page to find the right doc for the task in front of you — setting up a local environment, understanding the architecture, running tests, following contribution guidelines, or reviewing security practices.

Development documentation

Quick navigation guide

Use this guide to jump straight to what you need:

• New to the project? Start with Introduction, check Prerequisites, then follow the Quick Start and First Steps.
• Setting up your machine to build the CLI? Go to Environment Setup.
• Ready to build and run the code? Go to Local Development.
• Want to understand how the codebase is structured? Read Architecture, and for the full module-level breakdown see Architecture Overview and the diagrams index.
• Need to see how this repository relates to the rest of the organization? See Ecosystem.
• Writing or running tests? Go to Testing.
• About to open a change? Review Contributing Guidelines.
• Handling credentials, signatures, or sensitive data? Review Security.
• Trying the CLI end-to-end against a real cluster? The getting-started how-to guides walk through the full lifecycle: create a cluster, install the platform, check status, update the CLI, and uninstall / delete a cluster.

Repository layout at a glance

The codebase is organized around three core abstractions — cluster provisioning, app deployment via ArgoCD, and prerequisites verification — plus shared infrastructure:

cmd/              Cobra command definitions (bootstrap, cluster, app, prerequisites, update)
internal/cluster/ Cluster lifecycle: service.go, provider/ (k3d, EKS, GKE), discovery/, prerequisites/
internal/chart/   ArgoCD/Helm/Git providers and chart install orchestration (services/)
internal/app/     Platform status aggregation (status/) and uninstall (uninstall/)
internal/k8s/     Kubeconfig context resolution and cluster health/resource access
internal/prerequisites/ OS-aware check/install runner for required tools
internal/shared/  executor, errors, ui, download, selfupdate, wsllauncher
tests/            Integration tests and shared test utilities (tests/testutil/)
main.go           Entry point
go.mod            Module definition: github.com/flamingo-stack/openframe-cli, Go 1.26.0 (toolchain go1.26.5)

For the full component-by-component breakdown, dependency diagrams, and sequence diagrams (bootstrap flow, app status aggregation), see Architecture and Architecture Overview.

Working agreement

Before opening a pull request:

1. Confirm your change builds and passes the suite described in Testing.
2. Follow the conventions in Contributing Guidelines.
3. For anything touching credential handling, binary verification, or self-update integrity, check Security first.

This project does not use GitHub Issues or GitHub Discussions for coordination — day-to-day discussion happens on the OpenMSP Slack community.