CLI Code Structure

Purpose: For contributors, provides CLI package layout, key interfaces, and module responsibilities.

Package layout

openCenter-cli/
├── cmd/                    # Cobra command definitions (~50 files)
│   ├── root.go             # Root command, global flags
│   ├── cluster.go          # `opencenter cluster` parent command
│   ├── cluster_init.go     # `opencenter cluster init`
│   ├── cluster_configure.go# `opencenter cluster configure`
│   ├── cluster_validate.go # `opencenter cluster validate`
│   ├── cluster_generate.go # `opencenter cluster generate`
│   ├── cluster_deploy.go   # `opencenter cluster deploy`
│   ├── cluster_destroy.go  # `opencenter cluster destroy`
│   ├── cluster_describe.go # `opencenter cluster describe`
│   ├── cluster_doctor.go   # `opencenter cluster doctor`
│   ├── cluster_active.go   # `opencenter cluster active`
│   ├── cluster_normalize.go# `opencenter cluster normalize`
│   ├── cluster_import.go   # `opencenter cluster import`
│   ├── cluster_migrate.go  # `opencenter cluster migrate-layout`
│   ├── settings.go         # `opencenter settings` parent command
│   ├── secrets.go          # `opencenter secrets` parent command
│   ├── secrets_keys.go     # Secret key management
│   ├── secrets_sync.go     # Secret synchronization
│   ├── version.go          # `opencenter version`
│   ├── plugins.go          # Plugin management
│   └── ...                 # Additional subcommands
├── internal/               # Private packages (~30 packages)
│   ├── ansible/            # Kubespray inventory generation
│   ├── cloud/              # Cloud provider API clients
│   ├── cluster/            # Cluster lifecycle operations
│   ├── config/             # Configuration structs, loading, validation
│   │   ├── v2/             # Schema v2.0 types
│   │   └── services/       # Per-service config definitions
│   ├── core/               # Shared domain types, validation
│   │   └── validation/     # Validation framework
│   │       └── validators/ # Custom validators
│   ├── di/                 # Dependency injection container
│   ├── gitops/             # FluxCD manifest generation
│   ├── operations/         # Drift detection, backup, import
│   ├── plugins/            # Plugin discovery and execution
│   ├── provision/          # Infrastructure provisioning per provider
│   ├── resilience/         # Retry, circuit breaker, lock manager
│   ├── secrets/            # SOPS key management, encryption
│   ├── security/           # Input validation, credential masking, audit
│   ├── services/           # Platform service catalog and configuration
│   ├── sops/               # SOPS Age key lifecycle
│   ├── template/           # Go template rendering engine
│   ├── tofu/               # OpenTofu/Terraform generation
│   ├── ui/                 # Charmbracelet TUI components
│   └── util/               # Shared utility functions
├── schema/                 # Generated JSON schemas
├── tests/features/         # BDD feature files (Gherkin)
├── testdata/               # Test fixtures
├── bin/                    # Build output
├── main.go                 # Entry point
├── go.mod                  # Go module (go 1.26.3)
├── VERSION                 # Version file (1.0.0)
└── .mise.toml              # Tool versions + task runner

Code Metrics

~226,000 LOC
~710 Go files
~350 test files
30+ internal packages
50+ command files
19 direct dependencies

Key packages

`cmd/` — Command layer

Each file in cmd/ defines one Cobra command. Commands are thin: they parse flags, call into internal/ packages, and format output. Business logic does not live here.

Naming conventions:

cluster_<action>.go for cluster subcommands
secrets_<action>.go for secrets subcommands
settings.go for CLI settings management

`internal/config/` — Configuration

Defines the ClusterConfig struct and all nested types. Current schema version: 2.0. Uses yaml struct tags for serialization and validate struct tags (go-playground/validator) for validation.

Config loading pipeline (5 stages):

Parse YAML → intermediate representation
Normalize → canonicalize provider names, resolve aliases
Resolve References → expand ${ref:path}, ${env:VAR}, ${file:path} with cycle detection
Apply Defaults → hydrate from provider-region defaults registry
Validate → schema + business rules + provider + deployment + services

`internal/di/` — Dependency injection

Wires together all internal packages. Commands resolve dependencies from the DI container rather than constructing them directly. Tests swap implementations for fakes.

`internal/template/` — Template engine

Renders Go templates with Sprig functions. Templates in provider packages produce Terraform files, Kubespray inventories, and FluxCD manifests. Uses //go:embed to compile templates into the binary.

`internal/provision/` — Provider implementations

Each subdirectory implements infrastructure provisioning for a specific provider:

openstack/ — Automated VM provisioning via Terraform/OpenTofu
vmware/ — Pre-provisioned VM configuration
baremetal/ — Pre-provisioned host configuration
kind/ — Local Kind cluster bootstrap

`internal/ui/` — Terminal UI

Uses Charmbracelet libraries (bubbletea, bubbles, lipgloss) for interactive prompts, selection lists, and progress indicators. The cluster configure --guided command uses this for interactive editing.

`internal/security/` — Security components

Input validation, command sanitization, credential masking, and audit logging. Audit entries are HMAC-SHA256 signed for tamper detection. 30-day retention, 100 MB max with automatic rotation.

Key dependencies

Package	Purpose
`spf13/cobra` v1.10.2	CLI framework
`go-playground/validator/v10` v10.30.2	Struct validation
`charmbracelet/bubbletea` v1.3.10	Terminal UI framework
`charmbracelet/lipgloss` v1.1.0	Terminal styling
`gophercloud/gophercloud` v1.14.1	OpenStack API client
`vmware/govmomi` v0.53.1	VMware vSphere SDK
`filippo.io/age` v1.3.1	Age encryption for SOPS
`cucumber/godog` v0.15.1	BDD test framework
`leanovate/gopter` v0.2.11	Property-based testing
`sirupsen/logrus` v1.9.4	Structured logging
`redis/go-redis/v9` v9.18.0	Distributed locks
`zalando/go-keyring` v0.2.8	OS keyring integration
`stretchr/testify` v1.11.1	Test assertions

Extension Points

Extension	Location	Pattern
New provider	`internal/cloud/<provider>/` + `internal/provision/<provider>/`	Implement provider interface
New service	`internal/config/services/<service>.go` + templates	Add service config + embedded templates
New command	`cmd/cluster_<action>.go`	Register in parent command
New validator	`internal/core/validation/validators/`	Implement validator interface
External plugin	Executable named `opencenter-<name>` in PATH or plugins dir	Auto-discovered at runtime

Build Tasks (via Mise)

mise install              # Install tool versions
mise run build            # Build binary → ./bin/opencenter
mise run build-all        # Multi-platform builds
mise run test             # Unit tests
mise run godog            # BDD tests (Godog/Gherkin)
mise run test-properties  # Property-based tests
mise run lint             # Lint code
mise run fmt              # Format code
mise run schema           # Generate JSON schema
mise run release v1.0.0   # Create release
mise run gitea-up         # Local Gitea for testing

Package layout​

Code Metrics​

Key packages​

cmd/ — Command layer​

internal/config/ — Configuration​

internal/di/ — Dependency injection​

internal/template/ — Template engine​

internal/provision/ — Provider implementations​

internal/ui/ — Terminal UI​

internal/security/ — Security components​

Key dependencies​

Extension Points​

Build Tasks (via Mise)​