### Start Kubefirst Console Locally

Source: https://context7.com/konstructio/kubefirst/llms.txt

Downloads necessary tools, creates a local k3d cluster named `kubefirst-console`, installs the Kubefirst Helm chart, generates a local TLS certificate, and opens the console in the browser. Extra Helm values can be passed using `--helm-flag`.

```bash
# Basic usage:
kubefirst launch up

# Pass extra Helm values (e.g. to override the API image tag):
kubefirst launch up --helm-flag "kubefirst-api.image.tag=v0.136.0"

# Expected: browser opens at https://console.kubefirst.dev
# To tear down:
kubefirst launch down
```

--------------------------------

### Create Local GitOps Platform with k3d

Source: https://context7.com/konstructio/kubefirst/llms.txt

A self-contained local provisioner that runs the entire GitOps bootstrap inline, including Git setup, Terraform, k3d cluster creation, ArgoCD, Vault, and Minio. It uses a Bubbletea progress UI and requires a GitHub or GitLab token to be set as an environment variable.

```bash
export GITHUB_TOKEN=ghp_xxxxxxxxxxxx

kubefirst k3d create \
  --git-provider github \
  --github-org my-github-org \
  --cluster-name local-dev \
  --git-protocol ssh

# With GitLab:
export GITLAB_TOKEN=glpat-xxxxxxxxxxxx
kubefirst k3d create \
  --git-provider gitlab \
  --gitlab-group my-gitlab-group \
  --cluster-name local-dev
```

--------------------------------

### Launch Console Cluster with Kubefirst

Source: https://context7.com/konstructio/kubefirst/llms.txt

Manages the lifecycle of the console cluster. `Up` downloads tooling, creates a k3d cluster, installs the Helm chart, generates TLS certs, and opens the browser. `Down` deletes the cluster and cleans up local state.

```go
// launch.Up is called internally by provision.ProvisionManagementCluster.
// Called directly by `kubefirst launch up`.
err := launch.Up(ctx, []string{"kubefirst-api.image.tag=v0.136.0"}, false, true)
// inCluster=false → opens browser; inCluster=true → skip browser (used during provisioning)
// useTelemetry=true → sets global.useTelemetry=true in Helm values

// launch.Down deletes the k3d cluster named "kubefirst-console"
err = launch.Down(false)
// Runs: k3d cluster delete kubefirst-console
// Removes ~/.k1/kubefirst-console/
// Clears viper keys: kubefirst, flags, launch
```

--------------------------------

### Kubefirst console API cluster operations in Go

Source: https://context7.com/konstructio/kubefirst/llms.txt

Wraps the Kubefirst console API for CRUD operations on clusters. All calls are proxied through the `/api/proxy` endpoint. Supports creating, getting, listing, deleting, and resetting cluster progress.

```go
// CreateCluster submits a POST /api/proxy with body {url: "/cluster/<name>", body: ClusterDefinition}
err := cluster.CreateCluster(apiTypes.ClusterDefinition{
    ClusterName:   "prod",
    CloudProvider: "aws",
    CloudRegion:   "us-east-1",
})
```

```go
// GetCluster fetches a single cluster by name (returns ErrNotFound on 404)
c, err := cluster.GetCluster("prod")
if errors.Is(err, cluster.ErrNotFound) {
    fmt.Println("cluster not yet created")
}
```

```go
// GetClusters fetches all clusters
clusters, err := cluster.GetClusters()
for _, c := range clusters {
    fmt.Printf("%s: %s (%s)\n", c.ClusterName, c.Status, c.CloudProvider)
}
```

```go
// DeleteCluster sends DELETE /api/proxy?url=/cluster/<name>
err = cluster.DeleteCluster("old-workload")
```

```go
// ResetClusterProgress resets an errored cluster back to pending
cluster.ResetClusterProgress("prod")
```

```go
// Override the console URL for local development:
// export K1_LOCAL_DEBUG=true
// export K1_CONSOLE_REMOTE_URL=http://localhost:3000
```

--------------------------------

### Build Kubefirst Binary

Source: https://github.com/konstructio/kubefirst/blob/main/CLAUDE.md

Use this command to create the `kubefirst` executable binary.

```bash
go build
```

--------------------------------

### Create an on-premises K3s cluster with kubefirst

Source: https://context7.com/konstructio/kubefirst/llms.txt

Provisions a GitOps platform on existing bare-metal or VM servers via SSH. Requires GitHub and Cloudflare tokens for full functionality. Custom K3s arguments can be passed using `--servers-args`.

```bash
export GITHUB_TOKEN=ghp_xxxxxxxxxxxx
export CF_API_TOKEN=xxxxxxxxxx   # required for Cloudflare DNS

kubefirst k3s create \
  --alerts-email ops@example.com \
  --domain-name example.com \
  --servers-private-ips 10.0.0.1,10.0.0.2,10.0.0.3 \
  --servers-public-ips 203.0.113.1,203.0.113.2,203.0.113.3 \
  --ssh-privatekey ~/.ssh/id_rsa \
  --ssh-user ubuntu \
  --dns-provider cloudflare \
  --git-provider github \
  --github-org my-org \
  --cluster-name on-prem-cluster
```

```bash
# With custom k3s server arguments:
kubefirst k3s create \
  --alerts-email ops@example.com \
  --domain-name example.com \
  --servers-private-ips 10.0.0.1 \
  --ssh-privatekey ~/.ssh/id_rsa \
  --servers-args "--disable traefik,--write-kubeconfig-mode 644,--node-taint dedicated=master:NoSchedule"
```

--------------------------------

### Display Kubefirst Environment Information

Source: https://context7.com/konstructio/kubefirst/llms.txt

Prints a summary table of OS, architecture, Go runtime version, config file path, K1 folder path, and the CLI version.

```bash
kubefirst info
# Output (tabwriter formatted):
# Name                   | Value
# ---                    | ---
# Operational System     | darwin
# Architecture           | arm64
# Golang version         | go1.23.0
# Kubefirst config file  | /Users/user/.kubefirst
# Kubefirst config folder| /Users/user/.k1
# Kubefirst Version      | v2.7.12
```

--------------------------------

### Create k3d cluster with catalog apps

Source: https://context7.com/konstructio/kubefirst/llms.txt

Use this command to create a local k3d cluster with pre-validated applications from the kubefirst/gitops-catalog.

```bash
kubefirst k3d create \
  --git-provider github \
  --github-org my-org \
  --install-catalog-apps "datadog,external-secrets-operator"
```

--------------------------------

### Print Kubefirst CLI Version

Source: https://context7.com/konstructio/kubefirst/llms.txt

Displays the current build version string of the Kubefirst CLI.

```bash
kubefirst version
# Output:
#  kubefirst-cli golang utility version: v2.7.12
```

--------------------------------

### Use Local Kubefirst API

Source: https://github.com/konstructio/kubefirst/blob/main/CLAUDE.md

Configure the CLI to communicate with a locally running Kubefirst API. Ensure both the API and console are running.

```bash
export K1_CONSOLE_REMOTE_URL="http://localhost:3000"
```

--------------------------------

### Run Compiled Kubefirst Binary

Source: https://github.com/konstructio/kubefirst/blob/main/CLAUDE.md

Execute the compiled `kubefirst` binary after building it. This is the standard way to run the application.

```bash
./kubefirst
```

--------------------------------

### Create k3d cluster with custom gitops template

Source: https://context7.com/konstructio/kubefirst/llms.txt

Use this command to create a local k3d cluster using a custom gitops template from a specified Git repository and branch.

```bash
kubefirst k3d create \
  --git-provider github \
  --github-org my-org \
  --gitops-template-url https://github.com/my-org/custom-gitops-template.git \
  --gitops-template-branch main
```

--------------------------------

### Create Civo management cluster

Source: https://context7.com/konstructio/kubefirst/llms.txt

Use this command to create a Civo management cluster. Ensure GITHUB_TOKEN and CIVO_TOKEN environment variables are set.

```bash
export GITHUB_TOKEN=ghp_xxxxxxxxxxxx
export CIVO_TOKEN=xxxxxxxxxxxxxxxx

kubefirst civo create \
  --alerts-email ops@example.com \
  --domain-name example.com \
  --cloud-region LON1 \
  --git-provider github \
  --github-org my-org \
  --cluster-name my-civo-cluster \
  --node-type g4s.kube.medium \
  --node-count 3
```

--------------------------------

### Generate GitOps App Scaffolds

Source: https://context7.com/konstructio/kubefirst/llms.txt

Renders Helm chart stubs for each environment using Go's embed.FS and text/template. Template variables include AppName, DeploymentName, Environment, Namespace, and Description. Use for custom environments.

```go
// Generate scaffolding for "my-service" in custom environments:
err := generate.AppScaffold(
    "my-service",
    []string{"dev", "staging", "prod"},
    "./registry/environments",
)
// Creates:
//   ./registry/environments/dev/my-service/Chart.yaml
//   ./registry/environments/dev/my-service/values.yaml
//   ./registry/environments/dev/my-service.yaml
//   ./registry/environments/staging/...
//   ./registry/environments/prod/...
//
// ScaffoldData used in templates:
// {
//   AppName:        "my-service",
//   DeploymentName: "dev-environment-my-service",
//   Description:    "my-service example application",
//   Environment:    "dev",
//   Namespace:      "dev",
// }
```

--------------------------------

### Scaffold GitOps app manifests with kubefirst

Source: https://context7.com/konstructio/kubefirst/llms.txt

Generates Helm chart stub files and an ArgoCD Application manifest for a specified application name and environments. If `--environments` is omitted, it defaults to development, staging, and production.

```bash
# Generate scaffolding for an app called "my-service" in three environments:
kubefirst generate app-scaffold \
  --name my-service \
  --environments development,staging,production \
  --output-path ./registry/environments
```

```bash
# Default environments (if --environments omitted):
kubefirst generate app-scaffold --name my-service
# Creates development, staging, production directories
```

--------------------------------

### Stream Provisioning Logs

Source: https://context7.com/konstructio/kubefirst/llms.txt

Opens a Bubbletea TUI to tail the current session log file (`~/.k1/logs/log_<cluster>.log`) with live updates. Use this command in a separate terminal while a `kubefirst create` process is running.

```bash
# In a second terminal while kubefirst create is running:
kubefirst logs
```

--------------------------------

### Run Kubefirst from Source

Source: https://github.com/konstructio/kubefirst/blob/main/CLAUDE.md

Execute Kubefirst commands directly from the source code. Useful for development and testing specific commands.

```bash
go run .
# Example: go run . civo create
```

--------------------------------

### Development with K3d and Local API

Source: https://github.com/konstructio/kubefirst/blob/main/CLAUDE.md

Set up a replace directive in `go.mod` to use a local version of the `kubefirst-api` for k3d development. This bypasses module fetching for the specified path.

```go
github.com/konstructio/kubefirst-api vX.X.XX => /path-to/kubefirst-api/
```

--------------------------------

### Run Kubefirst CLI with GitOps Template

Source: https://github.com/konstructio/kubefirst/blob/main/CONTRIBUTING.md

Use this command to run the Kubefirst CLI, specifying a custom GitOps template URL and branch. This is useful for testing the latest changes from the gitops-template main branch.

```shell
go run . civo create --gitops-template-url https://github.com/konstructio/gitops-template --gitops-template-branch main
```

--------------------------------

### Format Code with Gofmt/Gofumpt

Source: https://github.com/konstructio/kubefirst/blob/main/CLAUDE.md

Format Go source files according to standard Go formatting. `gofumpt` is a stricter alternative.

```bash
gofmt -w .
# or
gofumpt -w .
```

--------------------------------

### Provision Management Cluster with Kubefirst

Source: https://context7.com/konstructio/kubefirst/llms.txt

Orchestrates the cloud-provider-agnostic provisioning flow, including Git validation, k3d cluster launch, and API polling for completion. Requires context, CLI flags, and catalog apps.

```go
clusterClient := cluster.Client{}
watcher := provision.NewProvisionWatcher("my-cluster", &clusterClient)
stepper := step.NewStepFactory(os.Stderr)
provisioner := provision.NewProvisioner(watcher, stepper)

// ProvisionManagementCluster runs the full flow:
// 1. Validate git credentials (GITHUB_TOKEN / GITLAB_TOKEN)
// 2. Initialize git provider (check repos/teams don't already exist)
// 3. Launch kubefirst-console k3d cluster (calls launch.Up)
// 4. Wait for API health check
// 5. Submit CreateMgmtClusterRequest to the console API
// 6. Poll watcher.UpdateProvisionProgress() every 5s until complete
err := provisioner.ProvisionManagementCluster(ctx, &types.CliFlags{
    ClusterName:  "prod",
    GitProvider:  "github",
    GithubOrg:    "my-org",
    CloudRegion:  "us-east-1",
    DomainName:   "example.com",
    AlertsEmail:  "ops@example.com",
    UseTelemetry: true,
}, catalogApps)
```

--------------------------------

### Error Wrapping Pattern

Source: https://github.com/konstructio/kubefirst/blob/main/CLAUDE.md

Demonstrates the recommended pattern for wrapping errors with context using `fmt.Errorf`. This preserves the original error while adding meaningful information.

```go
fmt.Errorf("meaningful message: %w", err)
```

--------------------------------

### Run All Tests

Source: https://github.com/konstructio/kubefirst/blob/main/CLAUDE.md

Execute all tests within the project. The `-v` flag provides verbose output.

```bash
go test -v ./...
```

--------------------------------

### Lint Code with GolangCI-Lint

Source: https://github.com/konstructio/kubefirst/blob/main/CLAUDE.md

Run the linter to check for code quality and style issues. It uses the configuration defined in `.golangci.yaml`.

```bash
golangci-lint run
```

--------------------------------

### Use Development GitOps Template

Source: https://github.com/konstructio/kubefirst/blob/main/CLAUDE.md

Specify a custom GitOps template repository and branch for development purposes. This allows testing changes to the template without merging them.

```bash
--gitops-template-url https://github.com/konstructio/gitops-template --gitops-template-branch main
```

--------------------------------

### Validate Git Credentials and Initialize Git Provider

Source: https://context7.com/konstructio/kubefirst/llms.txt

Validates Git credentials and token permissions for GitHub and GitLab, and checks for the existence of required repositories and teams before provisioning. Handles both GitHub and GitLab providers.

```go
// Validate that GITHUB_TOKEN is set, has correct permissions,
// and the org exists before provisioning:
gitAuth, err := gitShim.ValidateGitCredentials("github", "my-org", "")
if err != nil {
    log.Fatal().Err(err).Msg("git credential validation failed")
}
// gitAuth.Token, gitAuth.Owner, gitAuth.User are populated.

// Check repos and teams don't already exist (prevents duplicate provisioning):
err = gitShim.InitializeGitProvider(&gitShim.GitInitParameters{
    GitProvider:  "github",
    GitToken:     gitAuth.Token,
    GitOwner:     "my-org",
    Repositories: []string{"gitops", "metaphor"},
    Teams:        []string{"admins", "developers"},
})
// Returns error listing all existing repos/teams that need removal.

// GitLab equivalent:
gitAuth, err = gitShim.ValidateGitCredentials("gitlab", "", "my-gitlab-group")
```

--------------------------------

### Validate GitOps catalog apps with Go

Source: https://context7.com/konstructio/kubefirst/llms.txt

Validates a comma-separated list of catalog app names by querying the `kubefirst/gitops-catalog` repository index. It checks for required environment variables and populates secret and config keys.

```go
// ValidateCatalogApps validates a comma-separated list of catalog app names.
// It queries https://github.com/kubefirst/gitops-catalog/index.yaml and
// checks that all required environment variables are set.
isValid, apps, err := catalog.ValidateCatalogApps(ctx, "datadog,external-secrets-operator")
if err != nil {
    log.Fatal().Err(err).Msg("catalog validation failed")
}
// apps is []apiTypes.GitopsCatalogApp, each containing SecretKeys and ConfigKeys
// populated from the matching environment variables.
```

--------------------------------

### Check Let's Encrypt certificate usage with kubefirst

Source: https://context7.com/konstructio/kubefirst/llms.txt

Checks the ACME rate limit usage for a given domain against Let's Encrypt. This command requires the domain name as an argument.

```bash
kubefirst letsencrypt status --domain-name example.com
```

--------------------------------

### Retrieve platform credentials

Source: https://context7.com/konstructio/kubefirst/llms.txt

Reads ArgoCD, kbot, and Vault credentials from the running k3d cluster and optionally copies them to the clipboard.

```bash
kubefirst k3d root-credentials
```

```bash
kubefirst k3d root-credentials --argocd
```

```bash
kubefirst k3d root-credentials --vault
```

```bash
kubefirst k3d root-credentials --kbot
```

--------------------------------

### List Managed Kubefirst Clusters

Source: https://context7.com/konstructio/kubefirst/llms.txt

Queries the Kubefirst console API to retrieve and display a formatted table of managed clusters, including their name, creation time, status, type, and provider.

```bash
kubefirst launch cluster list
# NAME        CREATED AT            STATUS   TYPE   PROVIDER
# kubefirst   2024-11-15T10:00:00Z  active   mgmt   aws
```

--------------------------------

### Create GKE management cluster

Source: https://context7.com/konstructio/kubefirst/llms.txt

Use this command to create a Google Kubernetes Engine (GKE) management cluster. Ensure GITHUB_TOKEN is set and you have authenticated with `gcloud auth application-default login`.

```bash
export GITHUB_TOKEN=ghp_xxxxxxxxxxxx
# Requires Application Default Credentials: gcloud auth application-default login

kubefirst google create \
  --alerts-email ops@example.com \
  --domain-name example.com \
  --google-project my-gcp-project-id \
  --cloud-region us-east1 \
  --git-provider github \
  --github-org my-org \
  --cluster-name gke-mgmt \
  --node-type n2-standard-4
```

--------------------------------

### Retrieve AWS cluster credentials

Source: https://context7.com/konstructio/kubefirst/llms.txt

Prints ArgoCD password, kbot password, and Vault root token by reading from the Kubefirst console API for the cluster named in ~/.kubefirst.

```bash
kubefirst aws root-credentials
```

--------------------------------

### Destroy local k3d platform

Source: https://context7.com/konstructio/kubefirst/llms.txt

Tears down GitHub/GitLab resources, the k3d cluster, and clears local config. This command delegates to `common.Destroy`.

```bash
kubefirst k3d destroy
```

```bash
kubefirst local destroy
```

--------------------------------

### Run Specific Test

Source: https://github.com/konstructio/kubefirst/blob/main/CLAUDE.md

Execute a specific test case within a package. Replace `TestName` with the actual test function name.

```bash
go test -v ./path/to/package -run TestName
```

--------------------------------

### Run Short Tests

Source: https://github.com/konstructio/kubefirst/blob/main/CLAUDE.md

Execute tests that are not marked as long-running. This is typically used in CI environments.

```bash
go test -short -v ./...
```

--------------------------------

### Generate TLS certificate for local app

Source: https://context7.com/konstructio/kubefirst/llms.txt

Creates a TLS secret in the specified namespace for a locally running application, utilizing the cluster's existing certificate authority.

```bash
kubefirst k3d mkcert \
  --application my-app \
  --namespace my-namespace
```

--------------------------------

### Create AWS management cluster

Source: https://context7.com/konstructio/kubefirst/llms.txt

Validates AWS credentials and provisions an AWS management cluster. Ensure GITHUB_TOKEN and AWS_PROFILE (or AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY) environment variables are set.

```bash
export GITHUB_TOKEN=ghp_xxxxxxxxxxxx
export AWS_PROFILE=my-profile   # or AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY

kubefirst aws create \
  --alerts-email ops@example.com \
  --domain-name example.com \
  --git-provider github \
  --github-org my-org \
  --cloud-region us-east-1 \
  --cluster-name prod \
  --node-type m5.xlarge \
  --node-count 3 \
  --ami-type AL2_x86_64
```

```bash
export CF_API_TOKEN=xxxxx
kubefirst aws create \
  --alerts-email ops@example.com \
  --domain-name example.com \
  --dns-provider cloudflare \
  --subdomain dev \
  --git-provider github \
  --github-org my-org \
  --ecr   # Use ECR instead of ghcr.io
```

--------------------------------

### Backup cert-manager TLS resources

Source: https://context7.com/konstructio/kubefirst/llms.txt

Backs up all Kubernetes resources related to TLS certificates from cert-manager for restoration in a new cluster. This includes external-dns, ingress-nginx, and cert-manager objects.

```bash
kubefirst civo backup-ssl
```

--------------------------------

### Remove Local Kubefirst State

Source: https://context7.com/konstructio/kubefirst/llms.txt

Deletes local state directories (`~/.k1/` and `~/.kubefirst`) and clears Viper keys to allow for a clean re-provisioning.

```bash
kubefirst reset
# Removes ~/.k1/ directory and ~/.kubefirst config file.
# Clears all state: argocd, github, gitlab, components, kbot, kubefirst-checks, kubefirst, secrets.
```

--------------------------------

### Check AWS service quotas

Source: https://context7.com/konstructio/kubefirst/llms.txt

Queries AWS Service Quotas and displays limits that are close to being exceeded for a specified cloud region.

```bash
kubefirst aws quota --cloud-region us-west-2
```

--------------------------------

### Export Vault secrets as environment variables with kubefirst

Source: https://context7.com/konstructio/kubefirst/llms.txt

Reads secrets from a Vault instance and writes them as shell export commands to a local file for Terraform. The default output file is `.env` if `--output-file` is not specified.

```bash
kubefirst terraform set-env \
  --vault-url https://vault.example.com \
  --vault-token hvs.xxxxxxxxxxxxxxxx \
  --output-file .env.terraform

# Then activate in shell:
source .env.terraform
```

```bash
# Default output file is .env if --output-file is omitted
kubefirst terraform set-env \
  --vault-url https://vault.kubefirst.dev \
  --vault-token $VAULT_ROOT_TOKEN
```

--------------------------------

### Destroy Kubefirst Console Cluster

Source: https://context7.com/konstructio/kubefirst/llms.txt

Deletes the `kubefirst-console` k3d cluster and removes the associated local configuration directory `~/.k1/kubefirst-console/`.

```bash
kubefirst launch down
# Output: Your kubefirst platform provisioner has been destroyed.
```

--------------------------------

### Unseal a sealed Vault instance

Source: https://context7.com/konstructio/kubefirst/llms.txt

Reads unseal shards from the `vault-unseal-secret` Kubernetes secret and passes them to the Vault API to unseal the instance.

```bash
kubefirst k3d unseal-vault
```

--------------------------------

### Parse Flags with GetFlags

Source: https://context7.com/konstructio/kubefirst/llms.txt

Parses Cobra command flags into a types.CliFlags struct, normalizes GitHub/GitLab owner strings, and persists values to Viper config. Handles provider-specific flags based on the cloud provider.

```go
// GetFlags is called at the start of every create command:
cliFlags, err := utilities.GetFlags(cmd, "aws")
// Returns types.CliFlags with all fields populated from cobra flags and written to viper.

// types.CliFlags fields:
// ClusterName, CloudRegion, CloudProvider, DomainName, SubDomainName
// DNSProvider, GitProvider, GitProtocol, GithubOrg, GitlabGroup
// GitopsTemplateURL, GitopsTemplateBranch
// NodeType, NodeCount, AlertsEmail
// UseTelemetry, InstallKubefirstPro, InstallCatalogApps
// Ci (k3d), ECR (aws), AMIType (aws), DNSAzureRG (azure)
// GoogleProject (google), K3sServersPrivateIPs/PublicIPs/SSHUser/SSHPrivateKey/Args (k3s)
```

--------------------------------

### Delete a Managed Kubefirst Cluster

Source: https://context7.com/konstructio/kubefirst/llms.txt

Sends a DELETE request to the Kubefirst console API to deprovision a specified cluster. Progress can be monitored using `kubefirst launch cluster list`.

```bash
kubefirst launch cluster delete my-workload-cluster
# Submitted request to delete cluster `my-workload-cluster`
# Follow progress with `kubefirst launch cluster list`
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.