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-clirepository 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 byopenframe 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.
| Document | What it covers |
|---|---|
| Environment Setup | Preparing your machine (Go toolchain, required external tools) before building the CLI |
| Local Development | Building, running, and iterating on the CLI locally |
| Architecture | How cmd/, internal/cluster, internal/chart, internal/app, and shared packages fit together |
| Testing | How the test suite under tests/ and tests/testutil/ is organized and run |
| Contributing Guidelines | Conventions and process for submitting changes |
| Security | Security-relevant practices in the codebase (signature verification, credential handling, etc.) |
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.
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.
Before opening a pull request:
- Confirm your change builds and passes the suite described in Testing.
- Follow the conventions in Contributing Guidelines.
- 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.