OpenFrame is on your phone now! · iOS and Android apps are live. Get alerts and handle tickets on the go!

OpenFrame Documentation

Deployment guides, the CLI reference, architecture and admin guides for OpenFrame

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

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

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:

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.