### Install and Configure Pre-commit Hooks

Source: https://github.com/confluentinc/cli/blob/main/AGENTS.md

Install the pre-commit framework and set up repository-specific hooks for tasks like secret scanning. This is a one-time setup in the repository root.

```bash
brew install pre-commit          # prerequisite — pre-commit hooks scan for secrets via gitleaks
pre-commit install               # one-time, in repo root
```

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

### List Clusters Command Example

Source: https://github.com/confluentinc/cli/blob/main/CLAUDE.md

Example of listing Kafka clusters using the CLI, demonstrating backticks for commands.

```shell
`confluent kafka cluster list`
```

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

### Install Mockgen

Source: https://github.com/confluentinc/cli/blob/main/pkg/flink/CONTRIBUTING.md

Installs the `mockgen` tool from Uber's `mock` library, which is used for generating mocks.

```bash
go install go.uber.org/mock/mockgen@latest
```

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

### Set up Go environment with goenv

Source: https://github.com/confluentinc/cli/blob/main/CONTRIBUTING.md

Instructions for cloning goenv, setting environment variables, and installing the correct Go version for CLI development.

```bash
brew uninstall goenv
```

```bash
git clone https://github.com/syndbg/goenv.git ~/.goenv
```

```bash
export GOENV_ROOT="$HOME/.goenv"
export PATH="$GOENV_ROOT/bin:$PATH"
eval "$(goenv init -)"
export PATH="$PATH:$GOPATH/bin"
```

```bash
goenv install
```

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

### Update Cluster Command Example

Source: https://github.com/confluentinc/cli/blob/main/CLAUDE.md

Example of updating a cluster using the CLI, demonstrating backticks for commands and double quotes for resource names.

```shell
`confluent kafka cluster update lkc-123456`
```

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

### Install pre-commit hooks

Source: https://github.com/confluentinc/cli/blob/main/CONTRIBUTING.md

Installs the pre-commit tool and its hooks for the repository to ensure code quality and prevent secrets from being committed. The second command must be run from the repository root.

```bash
brew install pre-commit
```

```bash
pre-commit install
```

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

### Install Confluent CLI with APT (Ubuntu/Debian)

Source: https://github.com/confluentinc/cli/blob/main/README.md

Installs the Confluent CLI using APT for Ubuntu and Debian-based systems. Requires glibc 2.28 or above.

```bash
wget -qO - https://packages.confluent.io/confluent-cli/deb/archive.key | sudo apt-key add -
sudo apt install software-properties-common
sudo add-apt-repository "deb https://packages.confluent.io/confluent-cli/deb stable main"
sudo apt update && sudo apt install confluent-cli
```

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

### Update Cluster with ID Example

Source: https://github.com/confluentinc/cli/blob/main/CLAUDE.md

Example showing how to update a specific cluster by its ID, using backticks for the command and double quotes for the cluster ID.

```shell
`Update cluster "lkc-123456" with `confluent kafka cluster update lkc-123456`. `
```

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

### Example CLI Error Output

Source: https://github.com/confluentinc/cli/blob/main/pkg/errors/README.md

Illustrates the expected format for CLI error messages and suggestions.

```text
> ./confluent ksql cluster create kk --cluster lkc-asfdsaf
Error: Kafka cluster "lkc-asfdsaf" not found

Suggestions:
    List Kafka clusters with `confluent kafka cluster list`.
```

```text
Error: no API key selected for resource "lkc-dvnr7"

Suggestions:
    Select an API key for resource "lkc-dvnr7" with `confluent api-key use <API_KEY>`.
    To do so, you must have either already created or stored an API key for the resource.
    To create an API key use `confluent api-key create --resource lkc-dvnr7`.
    To store an existing API key use `confluent api-key store --resource lkc-dvnr7`.
```

```text
Error: Kafka cluster "lkc-yydnp" not ready

Suggestions:
    It may take up to 5 minutes for a recently created Kafka cluster to be ready.
```

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

### Example: Pre-Authenticated Session for Live Tests

Source: https://github.com/confluentinc/cli/blob/main/test/live/README.md

Configure live integration tests to use a pre-authenticated session by setting the `CLI_LIVE_TEST_CONFIG_DIR` environment variable. This points to the directory containing your Confluent CLI configuration.

```bash
CLI_LIVE_TEST_CONFIG_DIR=~ make live-test-core
```

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

### Install Flink Dependencies

Source: https://github.com/confluentinc/cli/blob/main/pkg/flink/README.md

Download and verify project dependencies using Go modules.

```bash
go mod download
go mod verify
```

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

### Install Confluent CLI with YUM (RHEL/CentOS)

Source: https://github.com/confluentinc/cli/blob/main/README.md

Installs the Confluent CLI using YUM for RHEL and CentOS. Requires glibc 2.28 or above.

```bash
sudo rpm --import https://packages.confluent.io/confluent-cli/rpm/archive.key
sudo yum install yum-utils
sudo yum-config-manager --add-repo https://packages.confluent.io/confluent-cli/rpm/confluent-cli.repo
sudo yum clean all && sudo yum install confluent-cli
```

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

### Install Confluent CLI with Homebrew

Source: https://github.com/confluentinc/cli/blob/main/README.md

Installs the latest version of the Confluent CLI using Homebrew. For FIPS-140 compliance, use the '-fips' variant.

```bash
brew install confluentinc/tap/cli
```

```bash
brew install confluentinc/tap/cli-fips
```

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

### Resource Deletion with Error Wrapping

Source: https://github.com/confluentinc/cli/blob/main/pkg/deletion/README.md

This example demonstrates how to wrap errors returned from the delete function, specifically handling `KafkaNotFoundError` for Kafka clusters.

```go
deleteFunc := func(id string) error {
		if httpResp, err := c.V2Client.DeleteKafkaCluster(id, environmentId); err != nil {
			return errors.CatchKafkaNotFoundError(err, id, httpResp)
		}
		return nil
}

_, err = deletion.Delete(cmd, args, deleteFunc, resource.User)
return err
```

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

### Generate Mocks

Source: https://github.com/confluentinc/cli/blob/main/pkg/flink/CONTRIBUTING.md

Generates mocks for interfaces using the `mock_generator.go` script. Ensure `mockgen` is installed and interfaces are updated before running.

```bash
go generate pkg/flink/test/mock/mock_generator.go
```

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

### Copy FIPS Modules to Homebrew Directory

Source: https://github.com/confluentinc/cli/blob/main/README.md

Copy the generated FIPS provider module and configuration file into the appropriate Homebrew OpenSSL directories. Ensure you replace `<version>` with your installed OpenSSL version.

```bash
cp install/usr/local/lib/ossl-modules/fips.dylib /opt/homebrew/Cellar/openssl@3/<version>/lib/ossl-modules
cp install/usr/local/ssl/fipsmodule.cnf /opt/homebrew/etc/openssl@3/
```

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

### Run Unit Tests Only

Source: https://github.com/confluentinc/cli/blob/main/AGENTS.md

Execute only the unit tests for the Confluent CLI. This is the fastest way to get feedback during development.

```bash
make unit-test                                                   # unit only — fastest signal
```

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

### Cross Compile Confluent CLI for Windows

Source: https://github.com/confluentinc/cli/blob/main/README.md

Cross-compiles the Confluent CLI for Windows (amd64) using MinGW-w64. Requires 'mingw-w64' to be installed.

```bash
brew install mingw-w64
GOOS=windows GOARCH=amd64 make cross-build
```

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

### Build FIPS-Compliant Confluent CLI

Source: https://github.com/confluentinc/cli/blob/main/AGENTS.md

Build a FIPS-140 compliant version of the Confluent CLI on macOS. The full setup for FIPS builds is detailed in the README.md file.

```bash
GOLANG_FIPS=1 make build                                         # FIPS-140 build on macOS (full setup in README.md, NOT CONTRIBUTING.md)
```

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

### Run Confluent CLI in FIPS-140 Mode

Source: https://github.com/confluentinc/cli/blob/main/README.md

Execute the Confluent CLI with environment variables set to utilize the FIPS-140 configured OpenSSL. This ensures that all cryptographic operations performed by the CLI adhere to FIPS standards. Replace `<version>` with your installed OpenSSL version.

```bash
env \
 DYLD_LIBRARY_PATH=/opt/homebrew/Cellar/openssl@3/<version>/lib \
 OPENSSL_CONF=/opt/homebrew/etc/openssl@3/openssl-fips.cnf \
 GOLANG_FIPS=1 \
 confluent version
```

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

### Run New Command

Source: https://github.com/confluentinc/cli/blob/main/CONTRIBUTING.md

Executes the newly added 'config file describe' command with an argument of 3.

```bash
dist/confluent_<os>_<arch>/confluent config file describe 3
```

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

### Build CLI Documentation

Source: https://github.com/confluentinc/cli/blob/main/CONTRIBUTING.md

Generates the CLI documentation locally in RST format using a Go script.

```bash
go run cmd/docs/main.go
```

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

### Implement Config Describe Command

Source: https://github.com/confluentinc/cli/blob/main/CONTRIBUTING.md

Implements the 'describe' subcommand for the 'config' command, printing the config filename a specified number of times.

```go
package config

import (
    "strconv"

    "github.com/spf13/cobra"

    "github.com/confluentinc/cli/v4/pkg/errors"
    "github.com/confluentinc/cli/v4/pkg/utils"
)

func (c *command) newDescribeCommand() *cobra.Command {
    return &cobra.Command{
        Use:  "describe",
        Args: cobra.ExactArgs(1),
        RunE: c.describe,
    }
}

func (c *command) describe(_ *cobra.Command, args []string) error {
    filename := c.CLICommand.Config.Config.Filename
    if filename == "" {
        return fmt.Errorf("config file not found")
    }

    n, err := strconv.Atoi(args[0])
    if err != nil {
        return err
    }

    for i := 0; i < n; i++ {
        output.Println(filename)
    }
    return nil
}
```

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

### Run Flink Prototype

Source: https://github.com/confluentinc/cli/blob/main/pkg/flink/README.md

Execute the Flink SQL Client prototype using the main demo file.

```bash
go run _examples/main/demo_main.go
```

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

### Run Test Steps

Source: https://github.com/confluentinc/cli/blob/main/test/live/README.md

Iterate through defined steps and execute them using 'runLiveCommand'.

```go
for _, step := range steps {
    t.Run(step.Name, func(t *testing.T) {
        s.runLiveCommand(t, step, state)
    })
}

```

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

### Create Live Test File

Source: https://github.com/confluentinc/cli/blob/main/test/live/README.md

Test methods must end with 'Live' to be included in the '-run="'.*Live$"' filter.

```go
//go:build live_test && (all || mygroup)

package live

func (s *CLILiveTestSuite) TestMyResourceCRUDLive() {
    t := s.T()
    t.Parallel()
    state := s.setupTestContext(t)

    // ... test body ...
}

```

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

### Run Go Code Linting

Source: https://github.com/confluentinc/cli/blob/main/AGENTS.md

Execute Go code linting using `golangci-lint` according to the configuration specified in `.golangci.yml`.

```bash
make lint-go                                                     # golangci-lint per .golangci.yml
```

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

### Download and Build OpenSSL

Source: https://github.com/confluentinc/cli/blob/main/README.md

Download the OpenSSL source code, extract it, and configure it with FIPS support enabled. This prepares the OpenSSL library for FIPS compliance.

```bash
wget "https://www.openssl.org/source/openssl-3.0.9.tar.gz"
tar -xvf openssl-3.0.9.tar.gz
cd openssl-3.0.9/
./Configure enable-fips
make install_fips DESTDIR=install
```

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

### Run Live Kafka Integration Tests

Source: https://github.com/confluentinc/cli/blob/main/AGENTS.md

Execute live integration tests against a real Confluent Cloud Kafka environment. These tests require valid credentials.

```bash
make live-test-kafka                                             # also: -schema-registry, -iam, -auth, -connect, -core, -essential
```

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

### Initialize Clients in Delete Function

Source: https://github.com/confluentinc/cli/blob/main/pkg/deletion/README.md

Initialize required clients, such as Kafka REST, within the `delete` function before proceeding.

```go
func (c *command) delete(cmd *cobra.Command, args []string) error {
	kafkaREST, err := c.GetKafkaREST(cmd)
	if err != nil {
		return err
	}
}
```

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

### Define CLI Test Steps

Source: https://github.com/confluentinc/cli/blob/main/test/live/README.md

Use CLILiveTest structs to define individual CLI command test steps. 'UseStateVars' enables template substitution for arguments.

```go
steps := []CLILiveTest{
    {
        Name:     "Create resource",
        Args:     "resource create my-name -o json",
        JSONFieldsExist: []string{"id"},
        CaptureID: "resource_id",  // captures JSON "id" field into state
    },
    {
        Name:         "Describe resource",
        Args:         "resource describe {{.resource_id}} -o json",
        UseStateVars: true,  // enables {{.key}} template substitution
        JSONFields:   map[string]string{"name": "my-name"},
    },
}

```

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

### Run unit tests

Source: https://github.com/confluentinc/cli/blob/main/CONTRIBUTING.md

Commands to run all unit tests or a specific subset of unit tests using the make command.

```bash
make unit-test
```

```bash
make unit-test UNIT_TEST_ARGS="-run TestApiTestSuite"
```

```bash
make unit-test UNIT_TEST_ARGS="-run TestApiTestSuite/TestCreateCloudAPIKey"
```

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

### Error Creation with Suggestions

Source: https://github.com/confluentinc/cli/blob/main/pkg/errors/README.md

Initialize errors with both a message and suggestions using NewErrorWithSuggestions. Ensure corresponding ErrorMsg and Suggestions variables are defined.

```go
ResolvingConfigPathErrorMsg        = "error resolving the config filepath at \"%s\" has occurred"
ResolvingConfigPathSuggestions     = "Try moving the config file to a different location."

return "", errors.NewErrorWithSuggestions(fmt.Sprintf(errors.ResolvingConfigPathErrorMsg, c.Filename), errors.ResolvingConfigPathSuggestions)
```

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

### Run Live Tests Against Confluent Cloud

Source: https://github.com/confluentinc/cli/blob/main/CLAUDE.md

Executes live tests against a real Confluent Cloud environment. Requires valid credentials to be configured.

```bash
# Live tests against real Confluent Cloud (require credentials):
make live-test-kafka                                             # also: -schema-registry, -iam, -auth, -connect, -core, -essential
```

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

### Build Confluent CLI from Source

Source: https://github.com/confluentinc/cli/blob/main/README.md

Builds the Confluent CLI from the source code using the 'make build' command. The output binary is located in 'dist/'.

```bash
make build
dist/confluent_$(go env GOOS)_$(go env GOARCH)/confluent -h
```

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

### Create New Config Command

Source: https://github.com/confluentinc/cli/blob/main/CONTRIBUTING.md

Defines the basic structure for a new 'config' command in the CLI.

```go
package config

import (
    "github.com/spf13/cobra"

    pcmd "github.com/confluentinc/cli/v4/pkg/cmd"
)

type command struct {
    *pcmd.CLICommand
}

func New(prerunner pcmd.PreRunner) *cobra.Command {
    cmd := &cobra.Command{Use: "config"}

    c := &command{pcmd.NewAnonymousCLICommand(cmd, prerunner)}

    cmd.AddCommand(c.newDescribeCommand())

    return cmd
}
```

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

### Basic Error Creation with fmt.Errorf

Source: https://github.com/confluentinc/cli/blob/main/pkg/errors/README.md

Use fmt.Errorf with predefined error messages from error_message.go for basic error creation.

```go
fmt.Errorf(errors.AuthorizeAccountsErrorMsg, accountsStr)
```

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

### Run All Live Integration Tests

Source: https://github.com/confluentinc/cli/blob/main/test/live/README.md

Execute all available live integration tests for the Confluent CLI. Ensure prerequisites like the CLI binary and authentication are met.

```bash
make live-test
```

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

### Run Multi-Cloud Live Integration Tests

Source: https://github.com/confluentinc/cli/blob/main/test/live/README.md

Execute live integration tests across multiple cloud providers. This can be a convenience target for common scenarios or customized with specific variants.

```bash
# Convenience target: runs kafka tests across aws, gcp, and azure
make live-test-multicloud

# Custom variants
CLI_LIVE_TEST_VARIANTS="aws:us-east-1:basic,gcp:us-east1:basic,azure:eastus:basic" make live-test-kafka
```

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

### Validate Resource Existence and Confirm Deletion

Source: https://github.com/confluentinc/cli/blob/main/pkg/deletion/README.md

Use `deletion.ValidateAndConfirm` to check if resources exist and prompt the user for confirmation before deletion. The `checkExistence` function should return true if the resource exists.

```go
func ValidateAndConfirm(cmd *cobra.Command, args []string, checkExistence func(string) bool, resourceType) error
```

```go
existenceFunc := func(id string) bool {
    _, _, err := c.V2Client.GetApiKey(id)
    return err == nil
}

if err := deletion.ValidateAndConfirm(cmd, args, existenceFunc, resource.ApiKey); err != nil {
    return err
}
```

```go
connectorIdToName, err := c.mapConnectorIdToName(environmentId, kafkaCluster.ID)
if err != nil {
    return err
}

existenceFunc := func(id string) bool {
    _, ok := connectorIdToName[id]
    return ok
}

if err := deletion.ValidateAndConfirm(cmd, args, existenceFunc, resource.Connector); err != nil {
    return err
}
```

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

### Run Single Go Test Directly

Source: https://github.com/confluentinc/cli/blob/main/AGENTS.md

Execute a single Go test directly using the `go test` command. This is faster than using `make` targets for inner-loop development on a specific test.

```bash
go test ./pkg/foo/ -run TestX -v
```

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

### Run Single Live Integration Test Directly with Go

Source: https://github.com/confluentinc/cli/blob/main/test/live/README.md

Execute a specific live integration test directly using the Go test runner. This allows for fine-grained control and debugging, requiring the `CLI_LIVE_TEST=1` environment variable and specific Go test flags.

```bash
CLI_LIVE_TEST=1 go test ./test/live/ -v -run TestLive/TestKafkaClusterCRUDLive \
    -tags="live_test,kafka" -timeout 30m
```

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

### Register New Command

Source: https://github.com/confluentinc/cli/blob/main/CONTRIBUTING.md

Adds the newly created 'config' command as a child of the root command in the CLI.

```go
cmd.AddCommand(config.New(prerunner))
```

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

### Register Cleanup Action

Source: https://github.com/confluentinc/cli/blob/main/test/live/README.md

Register cleanup actions before creating resources to ensure LIFO execution order.

```go
s.registerCleanup(t, "resource delete {{.resource_id}} --force", state)

```

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

### Config Describe Integration Test

Source: https://github.com/confluentinc/cli/blob/main/CONTRIBUTING.md

Defines an integration test case for the 'config describe' command, specifying arguments and a golden file for output comparison.

```go
package test

func (s *CLITestSuite) TestConfigDescribe() {
	tests := []CLITest{
		{args: "config describe 3", fixture: "config/1.golden"},
	}

	for _, test := range tests {
		s.runConfluentTest(test)
	}
}
```

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

### Run Live Integration Tests for a Single Resource

Source: https://github.com/confluentinc/cli/blob/main/test/live/README.md

Execute live integration tests for a specific Confluent Cloud resource. Specify the resource name using the `RESOURCE` variable.

```bash
make live-test-resource RESOURCE=kafka_cluster
make live-test-resource RESOURCE=environment
make live-test-resource   # prints all available resources
```

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

### Run Unit and Integration Tests

Source: https://github.com/confluentinc/cli/blob/main/CLAUDE.md

Executes all unit and integration tests for the CLI. Provides options to run only unit tests or specific test cases.

```bash
# Test
make test                                                        # unit + integration
make unit-test                                                   # unit only — fastest signal
make unit-test UNIT_TEST_ARGS="-run TestApiTestSuite/TestCreateCloudAPIKey"
make integration-test                                            # rebuilds CLI by default
make integration-test INTEGRATION_TEST_ARGS="-run TestCLI/TestKafka"
make integration-test INTEGRATION_TEST_ARGS="-no-rebuild"        # iterate without rebuild
make integration-test INTEGRATION_TEST_ARGS="-update"            # regenerate golden files (see Testing rules)
```

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

### Run all tests

Source: https://github.com/confluentinc/cli/blob/main/CONTRIBUTING.md

Command to execute all unit and integration tests for the Confluent CLI.

```bash
make test
```

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

### Build Confluent CLI

Source: https://github.com/confluentinc/cli/blob/main/AGENTS.md

Build the Confluent CLI binary for the current operating system and architecture. This command produces the executable in the dist directory.

```bash
make build                                                       # → dist/confluent_<os>_<arch>/confluent
```

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

### Run Live Integration Tests by Group

Source: https://github.com/confluentinc/cli/blob/main/test/live/README.md

Execute specific groups of live integration tests. Use the `CLI_LIVE_TEST_GROUPS` variable to filter tests by category, such as 'kafka'.

```bash
make live-test-core        # environment, service account, API key
make live-test-kafka       # kafka cluster, topic, ACL, consumer group
make live-test-essential   # core + kafka + schema_registry + auth
make live-test CLI_LIVE_TEST_GROUPS="kafka"  # kafka only
```

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

### Build CLI Binary

Source: https://github.com/confluentinc/cli/blob/main/CONTRIBUTING.md

Builds the Confluent CLI binary. This command is typically run before executing CLI commands.

```bash
make build
```

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

### Run Test Coverage Report

Source: https://github.com/confluentinc/cli/blob/main/pkg/flink/CONTRIBUTING.md

Executes tests and generates an HTML coverage report. Open the generated `coverage.html` file in your browser to view results.

```bash
go test -coverprofile=coverage.out ./... && \
go tool cover -html=coverage.out -o coverage.html
```

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

### Create OpenSSL FIPS Configuration

Source: https://github.com/confluentinc/cli/blob/main/README.md

Create a dedicated OpenSSL configuration file for FIPS-140 mode by copying the default configuration and appending FIPS-specific settings. This file defines the FIPS provider and security policies.

```bash
cp /opt/homebrew/etc/openssl@3/openssl.cnf /opt/homebrew/etc/openssl@3/openssl-fips.cnf
```

```ini
config_diagnostics = 1
openssl_conf = openssl_init

.include /opt/homebrew/etc/openssl@3/fipsmodule.cnf

[openssl_init]
providers = provider_sect
ssl_conf = ssl_module
alg_section = algorithm_sect

[provider_sect]
fips = fips_sect
default = default_sect

[default_sect]
activate = 1

[algorithm_sect]
default_properties = fips=yes

[ssl_module]
system_default = crypto_policy

[crypto_policy]
CipherString = @SECLEVEL=2:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384
Ciphersuites = TLS_AES_256_GCM_SHA384
TLS.MinProtocol = TLSv1.2
TLS.MaxProtocol = TLSv1.3
DTLS.MinProtocol = DTLSv1.2
DTLS.MaxProtocol = DTLSv1.2
SignatureAlgorithms = ECDSA+SHA256:ECDSA+SHA384:ECDSA+SHA512:rsa_pss_pss_sha256:rsa_pss_pss_sha384:rsa_pss_pss_sha512:rsa_pss_rsae_sha256:rsa_pss_rsae_sha384:rsa_pss_rsae_sha512:RSA+SHA256:RSA+SHA384:RSA+SHA512:ECDSA+SHA224:RSA+SHA224
```

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

### Cloud/On-Prem Mode Gating Annotation

Source: https://github.com/confluentinc/cli/blob/main/AGENTS.md

Use this Cobra annotation to gate commands based on login state (Cloud or On-Prem). Avoid runtime branches for mode switching.

```go
Annotations: map[string]string{
	annotations.RunRequirement: annotations.RequireCloudLogin
}
```

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

### Run Integration Tests

Source: https://github.com/confluentinc/cli/blob/main/CONTRIBUTING.md

Executes integration tests for the CLI, specifically targeting the 'TestConfigDescribe' test case.

```bash
make integration-test INTEGRATION_TEST_ARGS="-run TestCLI/TestConfigDescribe"
```

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

### Generate Coverage Report

Source: https://github.com/confluentinc/cli/blob/main/AGENTS.md

Merge unit and integration test coverage data to generate a `coverage.txt` file. This provides an overview of code coverage across the project.

```bash
make coverage                                                    # merge unit + integration coverage → coverage.txt
```

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

### Configure Cobra Command for Multiple Deletions

Source: https://github.com/confluentinc/cli/blob/main/pkg/deletion/README.md

Use `MinimumNArgs(1)` and `ValidArgsFunction` with `NewValidArgsFunction` to enable deletion of multiple resources.

```go
func (c *command) newDeleteCommand() *cobra.Command {
    return &cobra.Command{
        Use:               "delete <id-1> [id-2] ... [id-n]",
        Args:              cobra.MinimumNArgs(1),
        ValidArgsFunction: pcmd.NewValidArgsFunction(c.validArgsMultiple),
        RunE:              c.delete,
    }
}
```

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

### Configure macOS for development

Source: https://github.com/confluentinc/cli/blob/main/CONTRIBUTING.md

Commands to increase the maximum number of open files and processes on macOS to prevent errors during integration tests. Restart is required after applying these changes.

```bash
echo 'kern.maxfiles=20480' | sudo tee -a /etc/sysctl.conf
```

```bash
echo -e 'limit maxfiles 8192 20480\nlimit maxproc 1000 2000' | sudo tee -a /etc/launchd.conf
```

```bash
echo 'ulimit -n 4096' | sudo tee -a /etc/profile
```

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

### Require Cloud Login Annotation

Source: https://github.com/confluentinc/cli/blob/main/CLAUDE.md

Use this annotation to gate commands that require a cloud login. This is the standard pattern for handling cloud vs. on-premise mode gating.

```go
Annotations: map[string]string{
annotations.RunRequirement: annotations.RequireCloudLogin
}
```

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

### Build the Confluent CLI

Source: https://github.com/confluentinc/cli/blob/main/CLAUDE.md

Builds the Confluent CLI executable. Supports cross-compilation for different operating systems and architectures.

```bash
# Build
make build                                                       # → dist/confluent_<os>_<arch>/confluent
GOARCH=arm64 make build                                          # cross-compile, same OS
GOOS=linux GOARCH=amd64 make cross-build                         # cross-OS (requires musl-cross or mingw-w64; see README)
GOLANG_FIPS=1 make build                                         # FIPS-140 build on macOS (full setup in README.md, NOT CONTRIBUTING.md)
```

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

### Apply Cloud-Only Annotation to Command

Source: https://github.com/confluentinc/cli/blob/main/pkg/cmd/ANNOTATIONS.md

Use the `annotations.RunRequirement` and `annotations.RequireCloudLogin` annotations to mark a command as requiring a Confluent Cloud login. This annotation will be inherited by child commands.

```go
cmd := &cobra.Command{
    Use:         "billing",
    Short:       "Perform billing administrative tasks for the current organization.",
    Args:        cobra.NoArgs,
    Annotations: map[string]string{annotations.RunRequirement: annotations.RequireCloudLogin},
}
```

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

### Update Snapshots

Source: https://github.com/confluentinc/cli/blob/main/pkg/flink/CONTRIBUTING.md

Runs tests and updates snapshot files when the `UPDATE_SNAPSHOTS` environment variable is set to `true`. Use this when snapshot tests fail and the changes are intentional.

```bash
UPDATE_SNAPSHOTS=true go test ./...
```

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

### Format Mixed String with Commands and Resources

Source: https://github.com/confluentinc/cli/blob/main/pkg/output/README.md

When a string contains both commands/flags and resources, format the commands/flags with backticks and the resources with escaped quotes. Note the spf13/pflag limitation that flag descriptions must use quotes.

```go
suggestion := "Update Kafka cluster \"lkc-123456\" with `confluent kafka cluster update lkc-123456`."
```

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

### Run specific integration tests

Source: https://github.com/confluentinc/cli/blob/main/CONTRIBUTING.md

Commands to run a specific suite or a particular integration test within a suite. This is useful for targeted testing and debugging.

```bash
make integration-test INTEGRATION_TEST_ARGS="-run TestCLI/TestKafka"
```

```bash
make integration-test INTEGRATION_TEST_ARGS="-run TestCLI/TestKafka/kafka_cluster_--help"
```

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

### Build Confluent CLI for macOS in FIPS-140 Mode

Source: https://github.com/confluentinc/cli/blob/main/README.md

Builds the Confluent CLI for macOS in FIPS-140 mode by setting the GOLANG_FIPS environment variable. Requires a separate OpenSSL FIPS provider build.

```bash
GOLANG_FIPS=1 make build
```

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

### Basic Resource Deletion

Source: https://github.com/confluentinc/cli/blob/main/pkg/deletion/README.md

Use this snippet to delete a single resource. It calls the `deletion.Delete` function with a specific delete function and resource type.

```go
deleteFunc := func(id string) error {
    return c.V2Client.DeleteIamUser(id)
}

_, err = deletion.Delete(cmd, args, deleteFunc, resource.User)
return err
```

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

### Run Linter

Source: https://github.com/confluentinc/cli/blob/main/CONTRIBUTING.md

Checks the codebase for linter errors. This is a required step before opening a Pull Request.

```bash
make lint
```

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

### Run Specific Unit Tests

Source: https://github.com/confluentinc/cli/blob/main/AGENTS.md

Execute specific unit tests using custom arguments. This allows for focused testing of particular test cases or functions.

```bash
make unit-test UNIT_TEST_ARGS="-run TestApiTestSuite/TestCreateCloudAPIKey"
```

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

### Run integration tests without rebuilding CLI

Source: https://github.com/confluentinc/cli/blob/main/CONTRIBUTING.md

Command to run integration tests while skipping the CLI binary rebuild if it already exists in the dist/ directory. This can speed up test execution.

```bash
make integration-test INTEGRATION_TEST_ARGS="-no-rebuild"
```

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

### Run Integration Tests with Specific Arguments

Source: https://github.com/confluentinc/cli/blob/main/AGENTS.md

Execute integration tests with custom arguments, such as filtering tests by name. This provides granular control over the integration test execution.

```bash
make integration-test INTEGRATION_TEST_ARGS="-run TestCLI/TestKafka"
```

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

### Lint and Generate Coverage Reports

Source: https://github.com/confluentinc/cli/blob/main/CLAUDE.md

Performs linting checks on Go code and the CLI user interface, and generates a merged coverage report.

```bash
# Lint and coverage
make lint                                                        # = lint-go + lint-cli
make lint-go                                                     # golangci-lint per .golangci.yml
make lint-cli                                                    # hunspell-based spell check on user-facing strings (cmd/lint/main.go)
make coverage                                                    # merge unit + integration coverage → coverage.txt
```

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

### Add Autocompletion to Describe Command

Source: https://github.com/confluentinc/cli/blob/main/CONTRIBUTING.md

Enhances the 'describe' command by adding autocompletion support using `ValidArgsFunction`.

```go
func (c *command) newDescribeCommand() *cobra.Command {
    return &cobra.Command{
        Use:               "describe",
        Args:              cobra.ExactArgs(1),
        ValidArgsFunction: pcmd.NewValidArgsFunction(c.validArgs),
        RunE:              c.describe,
    }
}
```

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

### Register Argument Autocompletion - Go

Source: https://github.com/confluentinc/cli/blob/main/pkg/cmd/AUTOCOMPLETION.md

Use NewValidArgsFunction to dynamically complete a command argument, such as an API key. Ensure PersistentPreRunE is called to handle authentication and other prerequisites.

```go
pcmd.NewValidArgsFunction(c.validArgs)
```

```go
func (c *command) validArgs(cmd *cobra.Command, args []string) []string {
    if len(args) > 0 {
        return nil
    }

    if err := c.PersistentPreRunE(cmd, args); err != nil {
        return nil
    }

    return pcmd.AutocompleteApiKeys(c.V2Client)
}
```

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

### Handling Post-Deletion Tasks with Multierror

Source: https://github.com/confluentinc/cli/blob/main/pkg/deletion/README.md

For resources requiring additional tasks after deletion, use the returned deleted IDs and append any new errors using `multierror.Append`.

```go
deletedIds, err := deletion.Delete(cmd, args, deleteFunc, resource.ApiKey)

errs := multierror.Append(err, c.deleteKeysFromKeyStore(deletedIds))
```

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

### Format Resource with Quotes

Source: https://github.com/confluentinc/cli/blob/main/pkg/output/README.md

Use quotes to format resources (e.g., cluster IDs) within user-facing strings. This is useful when referring to specific entities.

```go
suggestion := `Update Kafka cluster "lkc-123456".`
```

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

### Run Integration Tests

Source: https://github.com/confluentinc/cli/blob/main/AGENTS.md

Execute the integration tests for the Confluent CLI. By default, this target rebuilds the CLI before running tests.

```bash
make integration-test                                            # rebuilds CLI by default
```

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

### Wrapped Error Creation with Suggestions

Source: https://github.com/confluentinc/cli/blob/main/pkg/errors/README.md

Wrap an existing error and add a custom message and suggestions using NewWrapErrorWithSuggestions. This is useful for adding context to errors from external packages.

```go
LookUpRoleErrorMsg              = "failed to look up role \"%s\""
LookUpRoleSuggestions           = "To check for valid roles, use `confluent iam rbac role list`."

return errors.NewWrapErrorWithSuggestions(err, fmt.Sprintf(errors.LookUpRoleErrorMsg, roleName), errors.LookUpRoleSuggestions)
```

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

### Format CLI Command with Backticks

Source: https://github.com/confluentinc/cli/blob/main/pkg/output/README.md

Use backticks to format CLI commands or flags within user-facing strings. This helps distinguish them from regular text.

```go
suggestion := "Run `confluent kafka cluster list` to list the Kafka clusters in the current environment."
```

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

### Run Linting Checks

Source: https://github.com/confluentinc/cli/blob/main/AGENTS.md

Perform linting checks on the Confluent CLI codebase. This includes Go code linting and spell checking for user-facing strings.

```bash
make lint                                                        # = lint-go + lint-cli
```

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

### Add New Makefile Target for Test Group

Source: https://github.com/confluentinc/cli/blob/main/test/live/README.md

Define a new Makefile target to run a specific live test group, using the 'live-test' command with the 'CLI_LIVE_TEST_GROUPS' parameter.

```makefile
.PHONY: live-test-mygroup
live-test-mygroup:
	@$(MAKE) live-test CLI_LIVE_TEST_GROUPS="mygroup"

```

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

### Run Integration Tests Without Rebuilding

Source: https://github.com/confluentinc/cli/blob/main/AGENTS.md

Execute integration tests without rebuilding the CLI. This is useful for faster iteration when only test logic is being changed.

```bash
make integration-test INTEGRATION_TEST_ARGS="-no-rebuild"        # iterate without rebuild
```

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

### Wait for Async Operation Condition

Source: https://github.com/confluentinc/cli/blob/main/test/live/README.md

Use 'waitForCondition' for operations that take time, such as cluster provisioning. It polls a command and checks the output with a provided function.

```go
s.waitForCondition(t,
    "kafka cluster describe {{.cluster_id}} -o json",
    state,
    func(output string) bool {
        return strings.EqualFold(extractJSONField(t, output, "status"), "UP")
    },
    30*time.Second,   // poll interval
    10*time.Minute,   // timeout
)

```

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

### Cross Compile Confluent CLI for Linux

Source: https://github.com/confluentinc/cli/blob/main/README.md

Cross-compiles the Confluent CLI for Linux (amd64 or arm64) using Go cross-compilation tools. Requires 'musl-cross' for musl libc.

```bash
brew install FiloSottile/musl-cross/musl-cross
GOOS=linux GOARCH=amd64 make cross-build
```

```bash
brew install FiloSottile/musl-cross/musl-cross
GOOS=linux GOARCH=arm64 make cross-build
```

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

### Cross-Compile Confluent CLI for ARM64

Source: https://github.com/confluentinc/cli/blob/main/AGENTS.md

Cross-compile the Confluent CLI for ARM64 architecture on the current operating system. This is useful for building binaries for different target platforms.

```bash
GOARCH=arm64 make build                                          # cross-compile, same OS
```

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

### Conditional Error Return with Suggestions

Source: https://github.com/confluentinc/cli/blob/main/pkg/deletion/README.md

This snippet shows how to check for errors after appending post-deletion tasks and return a formatted error with suggestions if any errors occurred.

```go
deletedIds, err := deletion.Delete(cmd, args, deleteFunc, resource.ApiKey)

errs := multierror.Append(err, c.deleteKeysFromKeyStore(deletedIds))
if errs.ErrorOrNil() != nil {
    return errors.NewErrorWithSuggestions(err.Error(), errors.APIKeyNotFoundSuggestions)
}

return nil
```

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

### Register Flag Autocompletion - Go

Source: https://github.com/confluentinc/cli/blob/main/pkg/cmd/AUTOCOMPLETION.md

Use RegisterFlagCompletionFunc to dynamically complete a flag's value, like an API key. This function requires the command, flag name, and a completion function that handles prerequisites like authentication.

```go
pcmd.RegisterFlagCompletionFunc(cmd, "api-key", func(cmd *cobra.Command, args []string) []string {
    if err := c.PersistentPreRunE(cmd, args); err != nil {
        return nil
    }

    return pcmd.AutocompleteApiKeys(c.V2Client)
})
```

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

### Set macOS File Descriptor Limit

Source: https://github.com/confluentinc/cli/blob/main/AGENTS.md

Adjust the maximum number of open file descriptors on macOS. This setting may need to be persisted by appending to /etc/profile.

```bash
ulimit -n 4096                   # macOS only; persist by appending to /etc/profile (see CONTRIBUTING.md)
```

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

### Minimum Number of Arguments Validation

Source: https://github.com/confluentinc/cli/blob/main/CLAUDE.md

Use cobra.MinimumNArgs for commands that accept a variable number of arguments, especially for delete operations.

```go
cobra.MinimumNArgs(1)
```

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

### Run CLI String Linting

Source: https://github.com/confluentinc/cli/blob/main/AGENTS.md

Perform spell checking on user-facing strings within the CLI using a hunspell-based checker. This targets the `cmd/lint/main.go` implementation.

```bash
make lint-cli                                                    # hunspell-based spell check on user-facing strings (cmd/lint/main.go)
```

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

### Pull Confluent CLI Docker Image

Source: https://github.com/confluentinc/cli/blob/main/README.md

Pulls the latest version of the Confluent CLI Docker image or a specific version.

```bash
docker pull confluentinc/confluent-cli:latest
```

```bash
docker pull confluentinc/confluent-cli:3.6.0
```

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

### Cross-Compile Confluent CLI for Linux AMD64

Source: https://github.com/confluentinc/cli/blob/main/AGENTS.md

Cross-compile the Confluent CLI for Linux AMD64 architecture. This requires specific cross-compilation toolchains like musl-cross or mingw-w64.

```bash
GOOS=linux GOARCH=amd64 make cross-build                         # cross-OS (requires musl-cross or mingw-w64; see README)
```

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

### Fixed Number of Arguments Validation

Source: https://github.com/confluentinc/cli/blob/main/CLAUDE.md

Use cobra.ExactArgs to validate a fixed number of arguments for a command.

```go
cobra.ExactArgs(N)
```

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

### Deletion Without Custom Message

Source: https://github.com/confluentinc/cli/blob/main/pkg/deletion/README.md

Use `deletion.DeleteWithoutMessage` when immediate deletion is not guaranteed and a custom deletion message is required. This function returns the IDs of successfully deleted resources.

```go
deletedIds, err := deletion.DeleteWithoutMessage(cmd, args, deleteFunc)
deleteMsg := "Started deletion of %s %s. To monitor a remove-broker task run `confluent kafka broker task list <id> --task-type remove-broker`.\n"
if len(deletedIds) == 1 {
    output.Printf(deleteMsg, resource.Broker, fmt.Sprintf(`"%s"`, deletedIds[0]))
} else if len(deletedIds) > 1 {
    output.Printf(deleteMsg, plural.Plural(resource.Broker), utils.ArrayToCommaDelimitedString(deletedIds, "and"))
}

return err
```

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

### Update Integration Tests

Source: https://github.com/confluentinc/cli/blob/main/CONTRIBUTING.md

Updates golden files for integration tests, particularly useful after making changes to command output.

```bash
make integration-test INTEGRATION_TEST_ARGS="-run TestCLI/TestConfigDescribe -update"
```

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

### Tab Completion Function

Source: https://github.com/confluentinc/cli/blob/main/CLAUDE.md

Assign a ValidArgsFunction for tab completion, typically using NewValidArgsFunction.

```go
ValidArgsFunction: pcmd.NewValidArgsFunction(c.validArgs)
```

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

### Update integration test golden files

Source: https://github.com/confluentinc/cli/blob/main/CONTRIBUTING.md

Command to update the golden files for integration tests with the current output. This is useful when the expected output of CLI commands has changed.

```bash
make integration-test INTEGRATION_TEST_ARGS="-update"
```

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

### CLITypedError Interface Definition

Source: https://github.com/confluentinc/cli/blob/main/pkg/errors/README.md

Defines the CLITypedError interface, which extends the standard error interface and adds a UserFacingError method. This allows for custom error types that can be processed downstream.

```go
type CLITypedError interface {
	error
	UserFacingError() error
}
```

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