Skip to content

README.md

Latest commit

 

History

History
280 lines (216 loc) · 11.6 KB

README.md

File metadata and controls

280 lines (216 loc) · 11.6 KB
Raw
OpenFrame

License

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 Preview Webinar

What is OpenFrame CLI?

OpenFrame CLI is part of the broader OpenFrame 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

🚀 Complete Environment Bootstrapping

  • One-command setup: Bootstrap entire OpenFrame environments with openframe bootstrap
  • OSS-tenant deployment: Installs the public openframe-oss-tenant chart — no credentials or mode selection needed
  • 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 teardown: cluster delete removes a cluster and its resources; cluster cleanup reclaims disk by pruning unused node images

📦 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

🛠 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

graph TB
    subgraph "CLI Commands"
        Bootstrap[openframe bootstrap]
        Cluster[openframe cluster]
        App[openframe app]
        Dev[openframe dev]
    end
    
    subgraph "Core Services"
        ClusterSvc[Cluster Management]
        ChartSvc[Chart Installation]
        DevSvc[Development Tools]
    end
    
    subgraph "External Tools"
        K3D[K3D Clusters]
        Helm[Helm Charts]
        ArgoCD[ArgoCD Apps]
        Telepresence[Service Intercepts]
    end
    
    subgraph "Target Environment"
        K8s[Kubernetes]
        Apps[Applications]
        Services[Microservices]
    end
    
    Bootstrap --> ClusterSvc
    Bootstrap --> ChartSvc
    Cluster --> ClusterSvc
    App --> ChartSvc
    Dev --> DevSvc
    
    ClusterSvc --> K3D
    ChartSvc --> Helm
    ChartSvc --> ArgoCD
    DevSvc --> Telepresence
    
    K3D --> K8s
    Helm --> Apps
    ArgoCD --> Apps
    Telepresence --> Services
Loading

Quick Start

Get OpenFrame CLI up and running in 5 minutes!

System Requirements

Resource Minimum Recommended
RAM 24GB 32GB
CPU Cores 6 cores 12 cores
Disk Space 50GB free 100GB free

Prerequisites

Before installation, ensure you have:

Installation

Choose your platform and install OpenFrame CLI:

Linux (AMD64)

curl -fsSL https://github.com/flamingo-stack/openframe-cli/releases/latest/download/openframe-cli_linux_amd64.tar.gz | tar -xz
sudo mv openframe /usr/local/bin/
chmod +x /usr/local/bin/openframe

macOS (Apple Silicon)

curl -fsSL https://github.com/flamingo-stack/openframe-cli/releases/latest/download/openframe-cli_darwin_arm64.tar.gz | tar -xz
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

Bootstrap Your Environment

Create a complete OpenFrame environment with a single command:

# Verify installation
openframe --version

# Bootstrap complete environment
openframe bootstrap

# Check cluster status
openframe cluster status

The bootstrap process creates:

  • K3D Kubernetes cluster
  • ArgoCD for GitOps deployment
  • Traefik ingress controller
  • Core monitoring and logging components

Core Commands

Command Description Example
openframe bootstrap Create a cluster and deploy OpenFrame openframe bootstrap my-cluster
openframe cluster create Create a k3d or cloud (EKS/GKE) cluster openframe cluster create dev --nodes 1
openframe cluster list List clusters openframe cluster list -o json
openframe cluster status Show cluster status openframe cluster status dev
openframe cluster delete Delete a cluster openframe cluster delete dev --force
openframe app install Install ArgoCD + app-of-apps openframe app install -c k3d-dev
openframe app upgrade Re-sync or move to a new ref openframe app upgrade -c k3d-dev --sync
openframe app status Report platform readiness openframe app status -c k3d-dev
openframe app access Show ArgoCD sign-in details openframe app access -c k3d-dev
openframe app uninstall Remove the app (keep the cluster) openframe app uninstall -c k3d-dev --yes
openframe prerequisites Check/install required tools openframe prerequisites install
openframe update Self-update the CLI openframe update check

Usage Examples

Cluster lifecycle:

openframe cluster create dev --type k3d --nodes 1 --skip-wizard
openframe cluster create my-gke --type gke --project my-project --region us-central1 --skip-wizard  # cloud (billed!)
openframe cluster create my-eks --type eks --region us-east-1 --skip-wizard  # cloud (billed!)
openframe cluster list                          # add -o json|yaml for scripts
openframe cluster status dev
openframe cluster delete dev --force

Deploy and manage the platform (OSS tenant deployment):

openframe app install                           # interactive: pick context
openframe app install dev --non-interactive     # reuse existing openframe-helm-values.yaml
openframe app install -c k3d-dev --ref v1.3.0   # deploy a specific release tag
openframe app status  -c k3d-dev                # -o json|yaml supported
openframe app status  -c k3d-dev --watch        # live view, refreshes in place (Ctrl+C to exit)
openframe app status  -c k3d-dev --interactive  # k9s-style TUI: navigate apps, inspect, trigger syncs
openframe app access  -c k3d-dev                # ArgoCD URL + admin credentials
openframe app upgrade -c k3d-dev --sync         # force ArgoCD to re-sync current ref
openframe app upgrade -c k3d-dev --ref v1.4.0   # move to a new release tag
openframe app uninstall -c k3d-dev --yes

Keep the CLI up to date (each release is checksum- and cosign-verified before it replaces the running binary; the previous version is kept for rollback):

openframe update            # update to the latest release
openframe update check      # report availability only (-o json|yaml)
openframe update v1.4.0     # switch to a specific release (up or down)
openframe update rollback   # revert to the previous version, offline

Terminal Output

On an interactive terminal the CLI renders live surfaces: a stage checklist with per-stage timings during bootstrap, an in-place dashboard during the application wait (progress bar, per-app health, slowest-apps timing), download progress bars, and a desktop notification when a long install finishes. Long operations under --verbose, --plain, or redirected output switch to timestamped sequential log lines that carry the same information (ready deltas, pending apps with their health).

Output controls:

  • --plain — sequential output with colors but no spinners or in-place redraws (for watch, script, tmux logging)
  • --silent — suppress everything except errors
  • --verbose — timestamped debug lines (helm/k3d command lines, wait internals)
  • NO_COLOR / CLICOLOR_FORCE=1 — strip / force ANSI styling
  • OPENFRAME_ASCII=1 — plain ASCII glyphs (also automatic under TERM=dumb or a non-UTF-8 locale)

In GitHub Actions, bootstrap stages fold into log groups, failures surface as job annotations, and the closing summary lands in the job's Step Summary.

Non-interactive flags (--non-interactive, --yes, --force, --skip-wizard) make every command scriptable; prompts are also skipped automatically in CI or when stdin is not a terminal. See Terminal output reference for the full behavior matrix.

Technology Stack

OpenFrame CLI integrates with industry-standard tools:

  • 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

📚 See the Documentation for comprehensive guides including:

  • 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

Community and Support

OpenFrame is built by the community for the community:

Note: We don't use GitHub Issues or Discussions. All support and community interaction happens in the OpenMSP Slack community.

License

This project is licensed under the Flamingo AI Unified License v1.0 - see the LICENSE.md file for details.

Built with 💛 by the Flamingo team