### Run Flipt Quickstart

Source: https://github.com/flipt-io/flipt/blob/v2/README.md

Initiates a wizard-driven setup for Flipt to get started quickly.

```bash
flipt quickstart
```

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

### Install and Bootstrap Development Environment

Source: https://github.com/flipt-io/flipt/blob/v2/CLAUDE.md

Use `mise` to install pinned Go and Node versions, then bootstrap development dependencies. This is the initial setup for contributing to the project.

```bash
mise install

# install dev dependencies
mise run bootstrap
```

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

### Get the Flipt Go SDK

Source: https://github.com/flipt-io/flipt/blob/v2/sdk/go/README.md

Installs the Flipt Go SDK using the go get command.

```sh
go get go.flipt.io/flipt/sdk/go
```

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

### Run Flipt Server

Source: https://github.com/flipt-io/flipt/blob/v2/README.md

Starts the Flipt server. Ensure the CLI is installed.

```bash
flipt server
```

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

### Flipt Configuration Example

Source: https://github.com/flipt-io/flipt/blob/v2/README.md

Example YAML configuration for Flipt, demonstrating Git-native storage with secrets management (file-based and Vault).

```yaml
# config.yml - Git-native setup with secrets management
secrets:
  providers:
    # File-based secrets (OSS)
    file:
      enabled: true
      base_path: "/etc/flipt/secrets"
    # HashiCorp Vault (Pro feature)
    vault:
      enabled: true
      address: "https://vault.example.com"
      auth_method: "token"
      token: "hvs.your_token"
      mount: "secret"

storage:
  type: git
  git:
    repository: "https://github.com/your-org/feature-flags.git"
    ref: "main"
    poll_interval: "30s"
    signature:
      enabled: true
      type: "gpg"
      key_ref:
        provider: "vault"  # Requires Pro license
        path: "flipt/signing-key"
        key: "private_key"
      name: "Flipt Bot"
      email: "bot@example.com"

environments:
  default:
    storage: git
  staging:
    storage: git
    directory: "staging"
```

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

### Render Content Section

Source: https://github.com/flipt-io/flipt/blob/v2/cmd/flipt/DESIGN.md

Example of how to instantiate and render a content section. Ensure to use applySectionSpacing for proper layout.

```go
section := &contentSection{
    badge:      BadgeInfoStyle,
    badgeText:  "CONFIG",
    heading:    "License Configuration",
    helperText: "Your current license settings",
    configItems: []string{
        renderKeyValue("Type", "Pro Annual"),
        renderKeyValue("Status", "Active"),
    },
}
fmt.Println(applySectionSpacing(section.render()))
```

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

### Example Success Screen Sections

Source: https://github.com/flipt-io/flipt/blob/v2/cmd/flipt/DESIGN.md

Illustrates how to populate success screen sections with data.

```go
sections := []successScreenSection{
    {BadgeSuccessStyle, "COMPLETE", "Setup Complete", summary, nil},
    {BadgeInfoStyle, "NEXT", "What to do next", nil, nextSteps},
    {BadgeInfoStyle, "RESOURCES", "Get Help", resources, nil},
}
```

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

### Install Flipt CLI

Source: https://github.com/flipt-io/flipt/blob/v2/README.md

Installs the Flipt command-line interface. Ensure you have curl installed.

```bash
curl -fsSL https://get.flipt.io/v2 | sh
```

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

### Install Dagger CLI

Source: https://github.com/flipt-io/flipt/blob/v2/build/CLAUDE.md

Install the Dagger command-line interface using Homebrew. This is a prerequisite for running Dagger commands.

```bash
brew install dagger/tap/dagger
```

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

### Install Pinned Go and Node Versions with Mise

Source: https://github.com/flipt-io/flipt/blob/v2/AGENTS.md

Installs the Go and Node.js versions specified in the .mise.toml configuration file. This is a prerequisite for setting up the development environment.

```bash
mise install
```

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

### Automated Release Command Example

Source: https://github.com/flipt-io/flipt/blob/v2/RELEASE.md

Example of how to invoke the release automation script with a specified version. Ensure the version is provided explicitly when using the agent command.

```text
Use .agents/commands/release.md for version 2.9.0.
```

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

### Install pre-commit for Linting

Source: https://github.com/flipt-io/flipt/blob/v2/DEVELOPMENT.md

Install the pre-commit tool for automatically linting commit messages according to Conventional Commits standards. This is a prerequisite for contributing to the project.

```shell
pip install pre-commit
```

```shell
brew install pre-commit
```

```shell
pre-commit install
```

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

### Run Flipt UI Development Server

Source: https://github.com/flipt-io/flipt/blob/v2/ui/index.dev.html

Executes the Flipt UI development server using the 'mise' tool. Ensure 'mise' is installed and configured for your project.

```bash
mise run ui:dev
```

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

### CI Cache Workflow Example

Source: https://github.com/flipt-io/flipt/blob/v2/build/CLAUDE.md

Illustrates the steps involved in building and utilizing a Docker registry cache within the CI pipeline for faster integration tests.

```yaml
build-cache:
  - Generate cache key from git commit + source file hashes
  - Check if cached image exists in GHCR
  - Build and push only if cache miss
  - Output image reference for test jobs

integration-tests:
  - Pull cached image from GHCR
  - Run tests using pre-built Flipt container
  - Maintain full test isolation and coverage
```

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

### Run Flipt Nightly Build with Docker

Source: https://github.com/flipt-io/flipt/blob/v2/README.md

Starts the Flipt server using the latest nightly build from Docker. Use for testing only, not recommended for production.

```bash
docker run --rm -p 8080:8080 -p 9000:9000 -t docker.flipt.io/flipt/flipt:v2-nightly
```

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

### Run Flipt with Docker

Source: https://github.com/flipt-io/flipt/blob/v2/README.md

Starts the Flipt server using Docker. This maps ports 8080 and 9000.

```bash
docker run --rm -p 8080:8080 -p 9000:9000 -t docker.flipt.io/flipt/flipt:v2
```

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

### Run Unit Tests

Source: https://github.com/flipt-io/flipt/blob/v2/build/README.md

Executes the unit test suite for Flipt. Ensure the Dagger CLI is installed and you are in the root of the Flipt repository.

```console
dagger call test --source=. unit
```

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

### Bootstrap Development Dependencies with Mise

Source: https://github.com/flipt-io/flipt/blob/v2/AGENTS.md

Installs all necessary development dependencies for the project using the 'bootstrap' task in mise. This should be run after installing the tool versions.

```bash
mise run bootstrap
```

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

### Progress Bar Example

Source: https://github.com/flipt-io/flipt/blob/v2/cmd/flipt/DESIGN.md

Visual representation of a progress bar. This is typically used in hero headers to show progress in wizard modes.

```text
▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬
```

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

### Run Flipt UI Development Server (npm)

Source: https://github.com/flipt-io/flipt/blob/v2/ui/CLAUDE.md

Starts the development server for the Flipt UI using npm. It runs on port 5173 and proxies API requests to the backend server running on port 8080.

```bash
npm run dev
```

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

### Running UI Development Server

Source: https://github.com/flipt-io/flipt/blob/v2/ui/AGENTS.md

Starts the development server for the Flipt UI. It runs on port 5173 and proxies API requests to the backend server running on port 8080.

```bash
mise run ui:dev
```

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

### Run Flipt Backend Development Server

Source: https://github.com/flipt-io/flipt/blob/v2/DEVELOPMENT.md

Starts the Flipt backend server, making it accessible on port 8080. This should be run in a separate terminal from the UI development server.

```shell
mise run dev
```

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

### Run Verbose Integration Tests

Source: https://github.com/flipt-io/flipt/blob/v2/build/CLAUDE.md

Use this command to run integration tests with verbose output, specifically targeting authentication cases. Ensure Dagger is installed and configured.

```bash
# Verbose test output
dagger call test --source=. integration --cases="authn" --verbose
```

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

### Example of Mock Verification in Go Tests

Source: https://github.com/flipt-io/flipt/blob/v2/AGENTS.md

Shows how to verify behavior in Go tests by asserting values flowing through mocks using mock.MatchedBy and then calling mock.AssertExpectations(t).

```go
mock.MatchedBy
mock.AssertExpectations(t)
```

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

### Setup Dev Container in VS Code

Source: https://github.com/flipt-io/flipt/blob/v2/DEVELOPMENT.md

Reopens the current repository in a VS Code Dev Container, which provides a pre-configured Linux environment with all necessary build tools and 'mise' for version management.

```shell
Dev Containers: Reopen in Container
```

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

### Run UI Integration Tests

Source: https://github.com/flipt-io/flipt/blob/v2/build/README.md

Runs the UI integration tests, which involve Playwright interacting with a running instance of Flipt. Ensure the Dagger CLI is installed.

```console
dagger call test --source=. ui
```

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

### Run Pre-commit Checks with Mise

Source: https://github.com/flipt-io/flipt/blob/v2/build/CLAUDE.md

Executes common pre-commit checks for formatting, linting, and code modernization using the 'mise' task runner. Ensure 'mise' is installed and configured.

```bash
mise run fmt          # Format Go code
mise run lint         # Lint Go code
mise run go:modernize # Update to modern Go style
mise run ui:fmt       # Format UI code
mise run ui:lint      # Lint UI code
```

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

### Example of Inline Error Checking in Go

Source: https://github.com/flipt-io/flipt/blob/v2/AGENTS.md

Illustrates the preferred Go idiom for checking errors immediately after a function call, allowing for concise error handling.

```go
if err := doSomething(); err != nil {
  // handle error
}
```

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

### Example of Using Custom Error Types in Go

Source: https://github.com/flipt-io/flipt/blob/v2/AGENTS.md

Demonstrates the use of custom error types like errs.ErrNotFoundf and errs.ErrInvalidf for specific error conditions. Falls back to fmt.Errorf for general errors.

```go
errs.ErrNotFoundf("flag %q not found", key)
errs.ErrInvalidf(...)
fmt.Errorf("...: %w", err)
```

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

### Contextual Help Section

Source: https://github.com/flipt-io/flipt/blob/v2/cmd/flipt/DESIGN.md

Creates a contextual help section with a badge, heading, and bullet points. Use `applySectionSpacing` for proper rendering.

```go
guidanceSection := &contentSection{
    badge:      BadgeInfoStyle,
    badgeText:  "HELP",
    heading:    "How to proceed",
    bulletItems: []string{"Step 1", "Step 2", "Step 3"},
}
fmt.Println(applySectionSpacing(guidanceSection.render()))
```

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

### Create Form with Theme

Source: https://github.com/flipt-io/flipt/blob/v2/cmd/flipt/DESIGN.md

Initializes a new form using the 'huh' library, specifying groups and applying the 'charm' theme. Program options for terminal interaction are also configured.

```go
form := huh.NewForm(groups...).WithTheme(huh.ThemeCharm())
form = form.WithProgramOptions(
    tea.WithOutput(os.Stdout),
    tea.WithAltScreen(),
    tea.WithReportFocus(),
)
```

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

### Run Flipt Server with Configuration

Source: https://github.com/flipt-io/flipt/blob/v2/DEVELOPMENT.md

Execute the Flipt server binary, optionally specifying a configuration file. The binary checks for user configuration at `{{ USER_CONFIG_DIR }}/flipt/config.yml` if no config flag is provided.

```shell
./bin/flipt server [--config ./config/local.yml]
```

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

### Input Validation Function

Source: https://github.com/flipt-io/flipt/blob/v2/cmd/flipt/DESIGN.md

Defines a validation function for form inputs. This example checks if a string field is empty and returns an error if it is.

```go
.Validate(func(s string) error {
    if s == "" {
        return fmt.Errorf("field is required")
    }
    return nil
})
```

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

### Run All Integration Tests with Dagger

Source: https://github.com/flipt-io/flipt/blob/v2/build/testing/integration/signing/README.md

Execute all integration tests for Flipt, including commit signing, using the Dagger CLI.

```bash
# From project root
dagger call test --source=. integration
```

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

### Build Flipt UI for Production (npm)

Source: https://github.com/flipt-io/flipt/blob/v2/ui/CLAUDE.md

Creates a production build of the Flipt UI using npm. The output is embedded directly into the Flipt server binary. This command also runs TypeScript compilation first, failing the build on type errors.

```bash
npm run build
```

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

### Building Production UI Assets

Source: https://github.com/flipt-io/flipt/blob/v2/ui/AGENTS.md

Creates a production build of the Flipt UI. These assets are embedded directly into the Flipt server binary.

```bash
mise run ui:build
```

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

### Complete Command Structure

Source: https://github.com/flipt-io/flipt/blob/v2/cmd/flipt/DESIGN.md

Defines a command structure with configuration, wizard state, and user inputs. Includes the main run logic for an interactive wizard.

```go
type myCommand struct {
    // Configuration
    configFile string
    
    // Wizard state
    currentStep WizardStep
    totalSteps  int
    
    // User inputs
    userInput string
}

func (c *myCommand) run(cmd *cobra.Command, args []string) error {
    // 1. Check TTY
    if !isatty.IsTerminal(os.Stdout.Fd()) {
        return fmt.Errorf("requires interactive terminal")
    }
    
    // 2. Initialize
    c.currentStep = StepWelcome
    c.totalSteps = 4
    
    // 3. Run wizard steps
    steps := []wizardStep{
        {StepWelcome, c.runWelcomeStep},
        {StepConfig, c.runConfigStep},
        {StepValidate, c.runValidateStep},
    }
    
    for _, step := range steps {
        c.currentStep = step.step
        fmt.Print("\033[H\033[2J")  // Clear screen
        
        if err := step.runFunc(); err != nil {
            if isInterruptError(err) {
                fmt.Println(HelperTextStyle.Render("Cancelled."))
                return nil
            }
            return err
        }
    }
    
    // 4. Show success
    c.currentStep = StepComplete
    c.renderSuccessScreen()
    
    return nil
}
```

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

### Build Flipt Distribution

Source: https://github.com/flipt-io/flipt/blob/v2/build/README.md

Builds a distribution-ready version of Flipt. The output is a container image containing the Flipt binary and the necessary filesystem structure, based on Alpine Linux.

```console
dagger call build
```

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

### Construct gRPC Client with Static Token Authentication

Source: https://github.com/flipt-io/flipt/blob/v2/sdk/go/README.md

Demonstrates how to construct a Flipt Go SDK client using the gRPC transport and authenticate with a static token. Ensure the gRPC server is running on localhost:9000.

```go
package main

import (
 sdk "go.flipt.io/flipt/sdk/go"
 sdkgrpc "go.flipt.io/flipt/sdk/go/grpc"
 grpc "google.golang.org/grpc"
 "google.golang.org/grpc/credentials/insecure"
)

func main() {
 token := sdk.StaticTokenAuthenticationProvider("a-flipt-client-token")

 conn, err := grpc.NewClient("localhost:9000", grpc.WithTransportCredentials(insecure.NewCredentials()))
 if err != nil {
  panic(err)
 }
 defer conn.Close()

 client := sdk.New(sdkgrpc.NewTransport(conn), sdk.WithAuthenticationProvider(token))
}
```

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

### Configure Flipt with Token Authentication

Source: https://github.com/flipt-io/flipt/blob/v2/build/CLAUDE.md

Sets up Flipt to require token authentication and enables token storage with a bootstrap credential. Ensure FLIPT_AUTHENTICATION_REQUIRED is set to 'true'.

```go
// Token authentication
flipt = flipt.
    WithEnvVariable("FLIPT_AUTHENTICATION_REQUIRED", "true").
    WithEnvVariable("FLIPT_AUTHENTICATION_METHODS_TOKEN_ENABLED", "true").
    WithEnvVariable("FLIPT_AUTHENTICATION_METHODS_TOKEN_STORAGE_TOKENS_BOOTSTRAP_CREDENTIAL", "s3cr3t")
```

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

### Render Responsive Info Section

Source: https://github.com/flipt-io/flipt/blob/v2/cmd/flipt/DESIGN.md

Renders an informational content section, adapting to available terminal width. Requires a `contentSection` struct and `applySectionSpacing` function.

```go
func (c *myCommand) renderInfoSection() string {
    width := c.availableWidth()
    
    section := &contentSection{
        badge:      BadgeInfoStyle,
        badgeText:  "INFO",
        heading:    "Important Information",
        helperText: "Please read carefully",
        bulletItems: []string{
            "First important point",
            "Second important point",
            "Third important point",
        },
    }
    
    return applySectionSpacing(section.render())
}
```

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

### Run Common Development Tasks with Mise

Source: https://github.com/flipt-io/flipt/blob/v2/CLAUDE.md

Execute common development tasks such as running the Go server, UI dev server, building, testing, linting, and regenerating code artifacts using `mise`.

```bash
mise run dev

```

```bash
mise run ui:dev

```

```bash
mise run build

```

```bash
mise run test

```

```bash
mise run lint / mise run fmt

```

```bash
mise run go:modernize

```

```bash
mise run proto

```

```bash
mise run go:mockery

```

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

### Run Pre-Commit Checks for Go, UI, and Markdown

Source: https://github.com/flipt-io/flipt/blob/v2/CLAUDE.md

Before committing, run formatting and linting checks for Go, UI components, and Markdown files. CI enforces these checks.

```bash
mise run fmt && mise run lint && mise run go:modernize   # Go
mise run ui:fmt && mise run ui:lint                      # UI
npx prettier -w <file>.md                                # Markdown
```

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

### Build with Registry Cache Debugging

Source: https://github.com/flipt-io/flipt/blob/v2/build/CLAUDE.md

Build the project using a specified registry cache and tag for debugging purposes. This command helps in testing the cache integration.

```bash
dagger call build-with-cache --source . --registry-cache ghcr.io/owner/repo-cache --cache-tag debug-test
```

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

### Comparison Table Section

Source: https://github.com/flipt-io/flipt/blob/v2/cmd/flipt/DESIGN.md

Renders a section to compare options side-by-side, using a badge, heading, and formatted configuration items.

```go
section := &contentSection{
    badge:      BadgeInfoStyle,
    badgeText:  "COMPARE",
    heading:    "Available Options",
    configItems: []string{
        SectionHeaderStyle.Render("Option A"),
        "  • Feature 1",
        "  • Feature 2",
        "",
        SectionHeaderStyle.Render("Option B"),
        "  • Feature 3",
        "  • Feature 4",
    },
}
```

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

### Run Unit and UI Tests with Dagger

Source: https://github.com/flipt-io/flipt/blob/v2/build/CLAUDE.md

Execute unit and UI tests using Dagger. Specify the source directory and test type.

```bash
dagger call test --source=. unit
```

```bash
dagger call test --source=. ui
```

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

### Create New Migration File

Source: https://github.com/flipt-io/flipt/blob/v2/internal/migrations/README.md

Use this command to generate a new SQL migration file. Specify the database type and a name for the migration.

```sh
migrate create -ext sql -dir ./migrations/{db} <migration_name>
```

```sh
migrate create -ext sql -dir ./migrations/clickhouse create_table_X
```

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

### Run Coverage Collection and Export

Source: https://github.com/flipt-io/flipt/blob/v2/build/CLAUDE.md

Collect coverage data for specified integration test cases and export the report to a given path.

```bash
dagger call test-coverage --source=. integration-coverage --cases="snapshot" export --path=/tmp/coverage.out
```

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

### Run Only Signing Integration Tests with Dagger

Source: https://github.com/flipt-io/flipt/blob/v2/build/testing/integration/signing/README.md

Execute only the commit signing-related integration tests for Flipt using the Dagger CLI by specifying the 'signing' case.

```bash
# From project root
dagger call test --source=. integration --cases signing
```

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

### Format Flipt UI Code (npm)

Source: https://github.com/flipt-io/flipt/blob/v2/ui/CLAUDE.md

Runs the Prettier code formatter to ensure consistent code style across the project using npm.

```bash
npm run format
```

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

### Build with Registry Cache Optimization

Source: https://github.com/flipt-io/flipt/blob/v2/build/CLAUDE.md

Optimize CI builds by utilizing a registry cache. Provide the source, registry cache path, and a cache tag.

```bash
dagger call build-with-cache --source . --registry-cache ghcr.io/owner/repo-cache --cache-tag cache-key
```

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

### Configure Flipt with File-based Secrets

Source: https://github.com/flipt-io/flipt/blob/v2/build/CLAUDE.md

Enables file-based secrets management for Flipt and sets the base path for secret files. Ensure FLIPT_SECRETS_PROVIDERS_FILE_ENABLED is set to 'true'.

```go
// File-based secrets
flipt = flipt.
    WithEnvVariable("FLIPT_SECRETS_PROVIDERS_FILE_ENABLED", "true").
    WithEnvVariable("FLIPT_SECRETS_PROVIDERS_FILE_BASE_PATH", "/home/flipt/secrets")
```

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

### Configure Flipt with Git-based Storage

Source: https://github.com/flipt-io/flipt/blob/v2/build/CLAUDE.md

Sets up Flipt to use Git-based storage, specifying the remote repository URL and the default branch. Also configures the default credential type for accessing the Git repository.

```go
// Git-based storage
flipt = flipt.
    WithEnvVariable("FLIPT_STORAGE_DEFAULT_REMOTE", "http://gitea:3000/root/features.git").
    WithEnvVariable("FLIPT_STORAGE_DEFAULT_BRANCH", "main").
    WithEnvVariable("FLIPT_CREDENTIALS_DEFAULT_TYPE", "basic")
```

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

### Run Integration Tests with Coverage

Source: https://github.com/flipt-io/flipt/blob/v2/build/CLAUDE.md

Execute integration tests and collect coverage data. Specify the test cases and an output path for the coverage report.

```bash
dagger call test-coverage --source=. integration-coverage --cases="snapshot"
```

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

### Run All Integration Tests

Source: https://github.com/flipt-io/flipt/blob/v2/build/README.md

Executes all integration test cases concurrently against the Dagger runtime. The `--source=.` argument specifies the project source directory.

```console
dagger call test --source=. integration
```

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

### Configure Flipt with JWT Authentication

Source: https://github.com/flipt-io/flipt/blob/v2/build/CLAUDE.md

Enables JWT authentication for Flipt and specifies the public key file for signature verification. Ensure FLIPT_AUTHENTICATION_METHODS_JWT_ENABLED is set to 'true'.

```go
// JWT authentication
flipt = flipt.
    WithEnvVariable("FLIPT_AUTHENTICATION_METHODS_JWT_ENABLED", "true").
    WithEnvVariable("FLIPT_AUTHENTICATION_METHODS_JWT_PUBLIC_KEY_FILE", "/etc/flipt/jwt.pem")
```

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

### Lint Flipt UI Code (npm)

Source: https://github.com/flipt-io/flipt/blob/v2/ui/CLAUDE.md

Runs ESLint to check for code quality and potential errors in the Flipt UI codebase using npm.

```bash
npm run lint
```

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

### Flipt Configuration for Commit Signing

Source: https://github.com/flipt-io/flipt/blob/v2/build/testing/integration/signing/README.md

Environment variables required to configure Flipt for commit signing, including Vault secrets provider and local storage settings.

```bash
# Vault secrets configuration
FLIPT_SECRETS_PROVIDERS_VAULT_ENABLED=true
FLIPT_SECRETS_PROVIDERS_VAULT_ADDRESS=http://vault:8200
FLIPT_SECRETS_PROVIDERS_VAULT_AUTH_METHOD=token
FLIPT_SECRETS_PROVIDERS_VAULT_TOKEN=test-root-token
FLIPT_SECRETS_PROVIDERS_VAULT_MOUNT=secret

# Local storage configuration
FLIPT_STORAGE_DEFAULT_BACKEND_TYPE=local
FLIPT_STORAGE_DEFAULT_BACKEND_PATH=/tmp/flipt-repo
FLIPT_STORAGE_DEFAULT_BRANCH=main

# Commit signing configuration
FLIPT_STORAGE_DEFAULT_SIGNATURE_ENABLED=true
FLIPT_STORAGE_DEFAULT_SIGNATURE_TYPE=gpg
FLIPT_STORAGE_DEFAULT_SIGNATURE_KEY_REF_PROVIDER=vault
FLIPT_STORAGE_DEFAULT_SIGNATURE_KEY_REF_PATH=flipt/signing-key
FLIPT_STORAGE_DEFAULT_SIGNATURE_KEY_REF_KEY=private_key
FLIPT_STORAGE_DEFAULT_SIGNATURE_NAME=Flipt Test Bot
FLIPT_STORAGE_DEFAULT_SIGNATURE_EMAIL=test-bot@flipt.io
FLIPT_STORAGE_DEFAULT_SIGNATURE_KEY_ID=test-bot@flipt.io
```

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

### Formatting UI Code

Source: https://github.com/flipt-io/flipt/blob/v2/ui/AGENTS.md

Runs the Prettier code formatter to ensure consistent code style across the UI project.

```bash
mise run ui:fmt
```

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

### Run Integration Tests with Cached Image

Source: https://github.com/flipt-io/flipt/blob/v2/build/CLAUDE.md

Execute integration tests using a pre-cached Docker image for faster CI runs. Specify the source, cached image reference, and test cases.

```bash
dagger call test-with-cache --source . --cached-image ghcr.io/owner/repo-cache:cache-key integration --cases="authn"
```

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

### UI Linting and Formatting Check

Source: https://github.com/flipt-io/flipt/blob/v2/ui/AGENTS.md

Ensures code consistency by running both Prettier for formatting and ESLint for linting. This is a required step before committing and is enforced by CI.

```bash
mise run ui:fmt && mise run ui:lint
```

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

### Format and Lint Go Code with Mise

Source: https://github.com/flipt-io/flipt/blob/v2/AGENTS.md

Runs Go code formatting (goimports) and linting (golangci-lint) using the mise task runner. These checks are enforced by CI.

```bash
mise run fmt
mise run lint
```

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

### Run Go Unit Tests with Specific Filters

Source: https://github.com/flipt-io/flipt/blob/v2/AGENTS.md

Executes Go unit tests, allowing for filtering by path and a specific test name. Useful for running a single test case during development.

```bash
mise run test
go test -v {path} -run {name}
```

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

### Run Specific Authentication Tests

Source: https://github.com/flipt-io/flipt/blob/v2/build/CLAUDE.md

Execute specific authentication-related integration tests, such as token and JWT authentication.

```bash
dagger call test --source=. integration --cases="authn/token authn/jwt"
```

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

### Running UI E2E Tests with Playwright

Source: https://github.com/flipt-io/flipt/blob/v2/ui/AGENTS.md

Executes end-to-end tests for the UI using Playwright. This requires a running backend instance. Specs are located in `ui/tests/`.

```bash
npx playwright test
```

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

### Wizard Progress Tracker

Source: https://github.com/flipt-io/flipt/blob/v2/cmd/flipt/DESIGN.md

Defines a struct to track the progress of a wizard, including the current step and the total number of steps. This is essential for managing multi-step processes.

```go
type wizard struct {
    currentStep WizardStep
    totalSteps  int
}
```

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

### Regenerate Protobuf and gRPC Stubs with Mise

Source: https://github.com/flipt-io/flipt/blob/v2/AGENTS.md

Runs the 'proto' task in mise to regenerate protobuf definitions and gRPC stubs. This is necessary after making changes to RPC definitions.

```bash
mise run proto
```

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

### Status Check Section

Source: https://github.com/flipt-io/flipt/blob/v2/cmd/flipt/DESIGN.md

Displays a warning section when a configuration is not met, including a badge, heading, helper text, and a placeholder for a call-to-action.

```go
if !isConfigured {
    section := &contentSection{
        badge:      BadgeWarnStyle,
        badgeText:  "ACTION REQUIRED",
        heading:    "Not Configured",
        helperText: "You need to set this up first",
    }
    // Add call-to-action
}
```

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

### Run Pre-commit Checks for Go

Source: https://github.com/flipt-io/flipt/blob/v2/AGENTS.md

Executes the necessary Go-related checks before committing code, including formatting, linting, and modernization. These are enforced by CI.

```bash
mise run fmt && mise run lint && mise run go:modernize
```

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

### Debug Integration Tests with Dagger

Source: https://github.com/flipt-io/flipt/blob/v2/build/CLAUDE.md

Commands to run integration tests with debug logging enabled and to export coverage data for analysis. The `--cases` flag filters which tests to run.

```bash
# Run with debug logging
dagger call test --source=. integration --cases="snapshot"

# Export coverage for analysis
dagger call test-coverage --source=. integration-coverage --cases="snapshot" export --path=/tmp/debug.out
```

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

### Finding Unused Code with Knip

Source: https://github.com/flipt-io/flipt/blob/v2/ui/AGENTS.md

Analyzes the UI project to identify unused files, exports, and dependencies.

```bash
npm run knip
```

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

### Render Bullet List

Source: https://github.com/flipt-io/flipt/blob/v2/cmd/flipt/DESIGN.md

Renders a list of items with bullet points. Each item in the string slice will be displayed as a separate bulleted entry.

```go
renderBulletList([]string{
    "First item",
    "Second item",
    "Third item",
})
```

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

### Render Key-Value Pair

Source: https://github.com/flipt-io/flipt/blob/v2/cmd/flipt/DESIGN.md

Helper function to render key-value pairs, often used for configuration or status information. The value is typically styled.

```go
renderKeyValue("Label", ValueStyle.Render("value"))
```

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

### Run Specific Integration Test Cases

Source: https://github.com/flipt-io/flipt/blob/v2/build/README.md

Runs a specific subset of integration tests. Use the `--cases` flag followed by a space-delimited list of case names to filter the tests.

```console
dagger call test --source=. integration --cases="authn"
```

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

### Running UI Tests with Jest

Source: https://github.com/flipt-io/flipt/blob/v2/ui/AGENTS.md

Executes unit tests for the UI components using Jest. Configuration is provided in `jest.config.ts`.

```bash
cd ui && npm run test
```

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

### Configure Flipt with Vault Secrets

Source: https://github.com/flipt-io/flipt/blob/v2/build/CLAUDE.md

Enables Vault secrets management for Flipt and specifies the Vault server address. Ensure FLIPT_SECRETS_PROVIDERS_VAULT_ENABLED is set to 'true'.

```go
// Vault secrets
flipt = flipt.
    WithEnvVariable("FLIPT_SECRETS_PROVIDERS_VAULT_ENABLED", "true").
    WithEnvVariable("FLIPT_SECRETS_PROVIDERS_VAULT_ADDRESS", "http://vault:8200")
```

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

### Select Input Field Configuration

Source: https://github.com/flipt-io/flipt/blob/v2/cmd/flipt/DESIGN.md

Configures a select input field for forms, allowing users to choose from a predefined list of options. Supports titles and dynamic option creation.

```go
huh.NewSelect[string]().
    Title("Select License Type").
    Options(
        huh.NewOption("Pro Monthly", "monthly"),
        huh.NewOption("Pro Annual", "annual"),
    ).
    Value(&licenseType)
```

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

### Render Colored Badge

Source: https://github.com/flipt-io/flipt/blob/v2/cmd/flipt/DESIGN.md

Renders a colored badge with the provided text. Use this for categorizing and highlighting information.

```go
badge.Render("ACTIVE")  // Creates a colored badge with text
```

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

### Confirmation Input Field Configuration

Source: https://github.com/flipt-io/flipt/blob/v2/cmd/flipt/DESIGN.md

Configures a confirmation input field (yes/no) for forms. Allows setting a title, description, custom affirmative/negative text, and binding the boolean result.

```go
huh.NewConfirm().
    Title("Ready to begin?").
    Description("This will take about 2 minutes").
    Value(&proceed).
    Affirmative("Yes, let's start").
    Negative("No, maybe later")
```

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

### Regenerate Mocks with Mise

Source: https://github.com/flipt-io/flipt/blob/v2/AGENTS.md

Uses the 'go:mockery' task in mise to regenerate mock implementations for interfaces, based on the configuration in .mockery.yml. This is crucial for testing.

```bash
mise run go:mockery
```

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

### Calculate Available Terminal Width

Source: https://github.com/flipt-io/flipt/blob/v2/cmd/flipt/DESIGN.md

Calculates the usable width for content in the terminal, accounting for padding and minimum/maximum content widths. Returns the terminal width if it cannot be determined.

```go
func availableWidth() int {
    width, _, err := term.GetSize(int(os.Stdout.Fd()))
    if err != nil || width == 0 {
        return contentWidth
    }
    
    usable := width - 4  // Account for padding
    if usable < minContentWidth {
        return max(1, usable)
    }
    if usable > contentWidth {
        return contentWidth
    }
    return usable
}
```

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

### Run Specific Integration Test Cases

Source: https://github.com/flipt-io/flipt/blob/v2/build/CLAUDE.md

Isolate and run specific integration test suites by providing their names. Supports single or multiple cases.

```bash
dagger call test --source=. integration --cases="authn"
```

```bash
dagger call test --source=. integration --cases="authn authz"
```

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

### Apply Modern Go Idioms with Mise

Source: https://github.com/flipt-io/flipt/blob/v2/AGENTS.md

Uses the 'go:modernize' task in mise to automatically apply modern Go language idioms to the codebase. This is part of the pre-commit checks.

```bash
mise run go:modernize
```

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

### Enable Debug Logging for Flipt

Source: https://github.com/flipt-io/flipt/blob/v2/build/testing/integration/signing/README.md

Set the FLIPT_LOG_LEVEL environment variable to DEBUG to enable detailed logging for troubleshooting integration tests.

```bash
FLIPT_LOG_LEVEL=DEBUG
```

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

### Linting UI Code

Source: https://github.com/flipt-io/flipt/blob/v2/ui/AGENTS.md

Runs ESLint to check for code quality and potential errors in the UI project.

```bash
mise run ui:lint
```

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

### Text Input Field Configuration

Source: https://github.com/flipt-io/flipt/blob/v2/cmd/flipt/DESIGN.md

Configures a text input field for forms. Supports titles, descriptions, placeholders, value binding, and password echo mode for sensitive data.

```go
huh.NewInput().
    Title(InputLabelStyle.Render("License Key")).
    Description("Enter your license key").
    Placeholder("XXXXX-XXXXX-XXXXX-XXXXX").
    Value(&licenseKey).
    EchoMode(huh.EchoModePassword)  // For sensitive data
```

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

### Success Screen Structure

Source: https://github.com/flipt-io/flipt/blob/v2/cmd/flipt/DESIGN.md

Defines the structure for success screen sections, including badges, headings, and content.

```go
type successScreenSection struct {
    badge       lipgloss.Style
    badgeText   string
    heading     string
    content     []string  // For key-value pairs
    bulletItems []string  // For bullet lists
}
```

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

### Check Cache Existence

Source: https://github.com/flipt-io/flipt/blob/v2/build/CLAUDE.md

Verify if a specific Docker image reference exists in the registry cache.

```bash
dagger call check-cache-exists --image-ref ghcr.io/owner/repo-cache:cache-key
```

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

### Inspect Docker Manifest

Source: https://github.com/flipt-io/flipt/blob/v2/build/CLAUDE.md

Inspect the manifest of a Docker image in the registry. This can help in understanding image layers and configurations related to caching.

```bash
docker manifest inspect ghcr.io/owner/repo-cache:cache-key
```

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

### Define Color Palette with Lipgloss

Source: https://github.com/flipt-io/flipt/blob/v2/cmd/flipt/DESIGN.md

Defines the primary brand, semantic, neutral, and surface colors using the lipgloss library for TUI styling.

```go
Purple       = lipgloss.Color("#6366F1") // Primary accent
PurpleAccent = lipgloss.Color("#8B5CF6") // Accent highlight
PurpleLight  = lipgloss.Color("#A78BFA") // Light purple for subtle highlights
PurpleDark   = lipgloss.Color("#4C1D95") // Dark purple for borders

// Semantic Colors
Green      = lipgloss.Color("#22C55E") // Success states
GreenLight = lipgloss.Color("#86EFAC") // Light green for success highlights
Amber      = lipgloss.Color("#F59E0B") // Warning states
Red        = lipgloss.Color("#EF4444") // Error states

// Neutral Colors
MutedGray    = lipgloss.Color("#94A3B8") // Secondary text
SoftGray     = lipgloss.Color("#E2E8F0") // Label text
DarkGray     = lipgloss.Color("#64748B") // Darker secondary text
White        = lipgloss.Color("#F8FAFC") // Primary text on dark surfaces

// Surface Colors
Surface      = lipgloss.Color("#111827") // Primary surface background
SurfaceMuted = lipgloss.Color("#1F2937") // Muted surface for nested areas
CodeBlockBg  = lipgloss.Color("#1F2937") // Background for code blocks
```

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

### Format Markdown Files with Prettier

Source: https://github.com/flipt-io/flipt/blob/v2/AGENTS.md

Formats Markdown files using Prettier to ensure consistent style. This is a manual check that should be run before committing.

```bash
npx prettier -w <file>.md
```

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

### Define Content Section Structure

Source: https://github.com/flipt-io/flipt/blob/v2/cmd/flipt/DESIGN.md

Defines the structure for a content section, including badges, headings, helper text, and list items. Use this struct to build structured UI components.

```go
type contentSection struct {
    badge       lipgloss.Style  // Badge style
    badgeText   string         // Badge text (e.g., "INFO", "SUCCESS")
    heading     string         // Section heading
    helperText  string         // Optional helper text
    configItems []string       // Key-value pairs or config items
    bulletItems []string       // Bullet list items
}
```

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

### Progress Indicator Struct

Source: https://github.com/flipt-io/flipt/blob/v2/cmd/flipt/DESIGN.md

Defines a struct to hold information for progress indicators, including current step, total steps, and percentage completion.

```go
type progressInfo struct {
    currentStep   int
    totalSteps    int
    progressPct   float64
}
```

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

### Debug Registry Cache Existence

Source: https://github.com/flipt-io/flipt/blob/v2/build/CLAUDE.md

Check if a specific image reference exists in the registry cache. This is useful for diagnosing cache miss issues.

```bash
# Registry cache debugging
dagger call check-cache-exists --image-ref ghcr.io/owner/repo-cache:cache-key
```

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

### Wizard Step Enum Definition

Source: https://github.com/flipt-io/flipt/blob/v2/cmd/flipt/DESIGN.md

Defines an enum for wizard steps using iota for sequential integer assignment. Use these constants to track the current stage in a multi-step process.

```go
type WizardStep int

const (
    StepWelcome WizardStep = iota
    StepConfiguration
    StepValidation
    StepComplete
)
```