### Install and Run kubefwd

Source: https://github.com/txn2/kubefwd/blob/master/docs/index.md

Provides installation commands for macOS and Windows, followed by the command to start the TUI.

```bash
# macOS
brew install kubefwd

# Windows
winget install txn2.kubefwd

# Then start exploring
sudo -E kubefwd --tui
```

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

### Install and Verify KIND

Source: https://github.com/txn2/kubefwd/blob/master/test/README.md

Install the KIND (Kubernetes IN Docker) tool and verify its installation. KIND is used to run a local Kubernetes cluster.

```bash
# Install KIND
go install sigs.k8s.io/kind@latest

# Verify installation
kind version
```

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

### Install kubefwd

Source: https://github.com/txn2/kubefwd/blob/master/docs/llms-full.txt

Installation commands for various operating systems and environments.

```bash
brew install txn2/tap/kubefwd
```

```powershell
scoop install kubefwd
```

```bash
sudo dpkg -i kubefwd_*_amd64.deb
```

```bash
sudo rpm -i kubefwd_*_amd64.rpm
```

```bash
docker run -it --rm --privileged \
    -v "$HOME/.kube:/root/.kube:ro" \
    txn2/kubefwd --tui
```

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

### Install kubefwd on Windows

Source: https://github.com/txn2/kubefwd/blob/master/docs/getting-started.md

Use winget or Scoop to install and manage the kubefwd binary. Requires Administrator privileges.

```powershell
winget install txn2.kubefwd
```

```powershell
scoop install kubefwd
```

```powershell
winget upgrade txn2.kubefwd
# or
scoop update kubefwd
```

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

### Hosts file entry example

Source: https://github.com/txn2/kubefwd/blob/master/docs/getting-started.md

Example of how kubefwd maps service names to loopback IPs in /etc/hosts.

```text
127.1.27.1    my-api
127.1.27.2    postgres
127.1.27.3    redis
```

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

### Install kubefwd on Linux (RHEL/Fedora)

Source: https://github.com/txn2/kubefwd/blob/master/docs/getting-started.md

Install or upgrade using the downloaded .rpm package.

```bash
# Install
sudo rpm -i kubefwd_*_amd64.rpm

# Upgrade
sudo rpm -U kubefwd_*_amd64.rpm
```

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

### Initialize and Use Metrics Registry

Source: https://context7.com/txn2/kubefwd/llms.txt

This Go code initializes the metrics registry, starts it, and defers stopping it. It demonstrates recording incoming and outgoing bytes for a service, retrieving specific service metrics, fetching all metrics, and getting a summary of total bytes transferred. Ensure the 'fmt' package is imported for printing.

```go
package main

import (
    "fmt"
    "github.com/txn2/kubefwd/pkg/fwdmetrics"
)

func main() {
    registry := fwdmetrics.GetRegistry()
    registry.Start()
    defer registry.Stop()

    // Record traffic
    registry.RecordBytesIn("my-service.default.minikube", 1024)
    registry.RecordBytesOut("my-service.default.minikube", 512)

    // Get metrics for a service
    metrics := registry.GetMetrics("my-service.default.minikube")
    fmt.Printf("Bytes In: %d\n", metrics.BytesIn)
    fmt.Printf("Bytes Out: %d\n", metrics.BytesOut)
    fmt.Printf("Rate In: %.2f bytes/sec\n", metrics.RateIn)
    fmt.Printf("Rate Out: %.2f bytes/sec\n", metrics.RateOut)

    // Get all metrics
    all := registry.GetAllMetrics()
    for key, m := range all {
        fmt.Printf("%s: %d in, %d out\n", key, m.BytesIn, m.BytesOut)
    }

    // Get summary
    summary := registry.GetSummary()
    fmt.Printf("Total: %d bytes in, %d bytes out\n",
        summary.TotalBytesIn, summary.TotalBytesOut)
}
```

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

### Install kubefwd on Linux (Debian/Ubuntu)

Source: https://github.com/txn2/kubefwd/blob/master/docs/getting-started.md

Install or upgrade using the downloaded .deb package.

```bash
# Install
sudo dpkg -i kubefwd_*_amd64.deb

# Upgrade (same command)
sudo dpkg -i kubefwd_*_amd64.deb
```

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

### Install kubectl

Source: https://github.com/txn2/kubefwd/blob/master/test/README.md

Install kubectl, the Kubernetes command-line tool, and verify its client version. This is used to interact with the Kubernetes cluster.

```bash
# macOS
brew install kubectl

# Verify installation
kubectl version --client
```

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

### Verify Docker Installation

Source: https://github.com/txn2/kubefwd/blob/master/test/README.md

Verify that Docker is installed on your system. This is a prerequisite for KIND.

```bash
docker --version  # Verify Docker is installed
```

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

### Start kubefwd with Pre-forwarded Namespace and API Enabled

Source: https://github.com/txn2/kubefwd/blob/master/docs/mcp-integration.md

Starts kubefwd, pre-forwarding services in the 'default' namespace and enabling the API for MCP communication.

```bash
sudo -E kubefwd svc -n default --api
```

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

### Start kubefwd with API

Source: https://github.com/txn2/kubefwd/blob/master/docs/api-reference.md

Commands to launch kubefwd with the API enabled.

```bash
# Idle mode - API enabled by default, add namespaces dynamically
sudo -E kubefwd

# Or forward a namespace with API enabled
sudo -E kubefwd svc -n default --api

# Test the API
curl http://kubefwd.internal/api/health
```

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

### Install kubefwd on Linux

Source: https://github.com/txn2/kubefwd/blob/master/README.md

For Linux, download the appropriate package (.deb, .rpm, or .tar.gz) from the releases page. This snippet indicates where to find installation files.

```bash
# Download .deb, .rpm, or .tar.gz from releases
```

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

### Install kubefwd on Windows using Scoop

Source: https://github.com/txn2/kubefwd/blob/master/README.md

Install kubefwd on Windows using the Scoop package manager.

```powershell
scoop install kubefwd
```

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

### Install kubefwd on macOS

Source: https://github.com/txn2/kubefwd/blob/master/docs/getting-started.md

Use Homebrew to install or upgrade the kubefwd binary.

```bash
brew install kubefwd
```

```bash
brew update && brew upgrade kubefwd
```

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

### Verify Go Installation

Source: https://github.com/txn2/kubefwd/blob/master/test/README.md

Verify that Go version 1.21 or later is installed. This is a development requirement for kubefwd.

```bash
go version
```

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

### Install kubefwd on Linux (Manual)

Source: https://github.com/txn2/kubefwd/blob/master/docs/getting-started.md

Extract the tarball and move the binary to a system path.

```bash
tar -xzf kubefwd_Linux_amd64.tar.gz
sudo mv kubefwd /usr/local/bin/
sudo chmod +x /usr/local/bin/kubefwd
```

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

### Traditional kubefwd Workflow Example

Source: https://github.com/txn2/kubefwd/blob/master/docs/mcp-integration.md

Illustrates the traditional command-line interaction for port forwarding and retrieving connection details.

```bash
You: How do I forward postgres from kft1?
AI: Run sudo -E kubefwd svc -n kft1 -l app=postgres
You: *runs command*
You: What's the connection string?
AI: psql -h postgres -U user -d dbname
```

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

### Setup KIND Cluster and Deploy Services

Source: https://github.com/txn2/kubefwd/blob/master/test/README.md

Set up a KIND Kubernetes cluster and deploy test services. This is part of the traditional testing method.

```bash
# 1. Setup KIND Cluster
./test/scripts/setup-kind.sh
./test/scripts/deploy-test-services.sh test/manifests
```

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

### MCP Example: Setting Up Environment for Checkout Service

Source: https://github.com/txn2/kubefwd/blob/master/docs/mcp-integration.md

Demonstrates an AI assistant setting up the development environment by forwarding multiple services and providing connection URLs.

```bash
You: "I'm starting work on the checkout service, set up my environment"
AI: "Your environment is ready. These services are available locally:

- cart-service:8080
- payment-service:443
- inventory-service:8080
- user-db:5432

Add to your .env:
```
CART_URL=http://cart-service:8080
PAYMENT_URL=https://payment-service:443
```"
```

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

### MCP-Enabled kubefwd Workflow Example

Source: https://github.com/txn2/kubefwd/blob/master/docs/mcp-integration.md

Demonstrates how an AI assistant, using MCP, can directly provide connection information after discovering and forwarding a service.

```bash
You: I need the staging database
AI: Connected. Your connection: psql -h postgres -U admin -d mydb
```

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

### Install kubefwd on Windows using winget

Source: https://github.com/txn2/kubefwd/blob/master/README.md

Install kubefwd on Windows using the Windows Package Manager (winget).

```powershell
winget install txn2.kubefwd
```

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

### Start kubefwd with API enabled for ChatGPT

Source: https://github.com/txn2/kubefwd/blob/master/docs/mcp-integration.md

Run this command with sudo to start the kubefwd REST API on the default port, enabling remote MCP server connections for ChatGPT. Ensure you use `-E` to preserve environment variables.

```bash
sudo -E kubefwd --api
```

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

### Verify kubefwd installation

Source: https://github.com/txn2/kubefwd/blob/master/docs/getting-started.md

Check the installed version of the tool.

```bash
kubefwd version
```

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

### Development Setup with TUI

Source: https://github.com/txn2/kubefwd/blob/master/docs/configuration.md

Forward all services within a specific namespace using the TUI interface.

```bash
# Forward all services in dev namespace with TUI
sudo -E kubefwd svc -n development --tui
```

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

### REST API Quick Start

Source: https://github.com/txn2/kubefwd/blob/master/docs/llms-full.txt

Commands to initialize kubefwd in idle mode and verify the API health endpoint.

```bash
# Idle mode - API enabled by default
sudo -E kubefwd

# Test the API
curl http://kubefwd.internal/api/health
```

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

### List MCP Prompts

Source: https://context7.com/txn2/kubefwd/llms.txt

Available guided workflows for common tasks.

```text
setup_local_dev     Complete environment setup guide
forward_namespace   Forward all services in a namespace
quick_connect       Fastest path to connect to a service
connection_guide    Connection string examples for various tools
troubleshoot        General debugging workflow
debug_service       Deep dive into a specific service
fix_errors          Resolve current error conditions
analyze_issues      Comprehensive issue analysis
explain_status      Explain current kubefwd state
monitor             Set up monitoring for forwards
```

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

### Install kubefwd on macOS

Source: https://github.com/txn2/kubefwd/blob/master/docs/llms.txt

Use Homebrew to install kubefwd on macOS. Ensure you have Homebrew installed.

```bash
# Install (macOS)
brew install txn2/tap/kubefwd
```

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

### MCP Integration Setup

Source: https://github.com/txn2/kubefwd/blob/master/docs/llms-full.txt

Configuration steps to enable kubefwd as an MCP server for AI clients.

```bash
sudo -E kubefwd --tui
```

```bash
claude mcp add --transport stdio kubefwd -- kubefwd mcp
```

```json
{
  "mcpServers": {
    "kubefwd": {
      "command": "kubefwd",
      "args": ["mcp"]
    }
  }
}
```

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

### Field Selector Examples

Source: https://github.com/txn2/kubefwd/blob/master/docs/advanced-usage.md

Filter services based on their metadata fields. This example forwards a single service by name and excludes another service by name.

```bash
sudo -E kubefwd svc -n default -f metadata.name=my-service --tui
```

```bash
sudo -E kubefwd svc -n default -f metadata.name!=internal-only --tui
```

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

### MCP Example: Connecting to PostgreSQL

Source: https://github.com/txn2/kubefwd/blob/master/docs/mcp-integration.md

Shows a user request for a PostgreSQL connection and the AI's response providing the connection string via MCP.

```bash
You: "I need to connect to PostgreSQL in kft1 on the dev cluster"
AI: "Connected. Use: `psql -h postgres -U admin -d mydb`"
```

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

### CLI Usage Examples

Source: https://github.com/txn2/kubefwd/blob/master/docs/llms-full.txt

Common command-line patterns for forwarding services, filtering by namespace or label, and configuring port mappings.

```bash
# Forward all services in a namespace with TUI
sudo -E kubefwd svc -n default --tui

# Multiple namespaces
sudo -E kubefwd svc -n frontend,backend,data --tui

# Filter by label
sudo -E kubefwd svc -n default -l app=api --tui

# Port mapping (80 → 8080)
sudo -E kubefwd svc -n default -m 80:8080 --tui

# IP reservation
sudo -E kubefwd svc -n default -r my-service.default:127.3.3.1 --tui
```

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

### Cross-Cluster Development Example

Source: https://github.com/txn2/kubefwd/blob/master/docs/advanced-usage.md

Forward services from a production namespace in a production cluster while developing locally. The second command shows combining namespaces across multiple clusters.

```bash
sudo -E kubefwd svc -n production -x prod-cluster -l type=database --tui
```

```bash
sudo -E kubefwd svc -n production,development -x prod-cluster,dev-cluster --tui
```

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

### Start kubefwd in Idle Mode with API

Source: https://github.com/txn2/kubefwd/blob/master/docs/mcp-integration.md

Starts kubefwd in idle mode, waiting for commands from MCP. The API must be enabled for MCP to communicate with kubefwd.

```bash
sudo -E kubefwd
```

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

### Setup KIND Cluster

Source: https://github.com/txn2/kubefwd/blob/master/test/README.md

Script to set up a local Kubernetes cluster using KIND. This is a prerequisite for running integration tests that require a cluster environment.

```bash
./test/scripts/setup-kind.sh
```

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

### GET /api/v1/kubernetes/contexts

Source: https://github.com/txn2/kubefwd/blob/master/docs/llms-full.txt

Lists available kubeconfig contexts.

```APIDOC
## GET /api/v1/kubernetes/contexts

### Description
Lists available kubeconfig contexts.

### Method
GET

### Endpoint
/api/v1/kubernetes/contexts
```

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

### Start kubefwd in Idle Mode

Source: https://github.com/txn2/kubefwd/blob/master/docs/index.md

Launches the tool without pre-specified services to allow interactive browsing and forwarding.

```bash
sudo -E kubefwd --tui
```

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

### Start kubefwd in interactive mode

Source: https://github.com/txn2/kubefwd/blob/master/README.md

Launch kubefwd in interactive mode for the 'default' namespace. This command requires root privileges.

```bash
sudo -E kubefwd svc -n default --tui
```

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

### Multiple Port Mappings

Source: https://github.com/txn2/kubefwd/blob/master/docs/advanced-usage.md

Configure multiple port remappings simultaneously. This example maps ports 80, 443, and 3000 to different local ports.

```bash
sudo -E kubefwd svc -n default \
  -m 80:8080 \
  -m 443:8443 \
  -m 3000:3000 \
  --tui
```

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

### Deploy Demo Environment

Source: https://github.com/txn2/kubefwd/blob/master/CLAUDE.md

Applies a Kubernetes manifest to deploy a demo environment consisting of 60 services across two namespaces. This is useful for testing kubefwd's capabilities in a complex setup.

```bash
# Deploy 60 services across 2 namespaces
kubectl apply -f test/manifests/demo-microservices.yaml
```

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

### Access forwarded services

Source: https://github.com/txn2/kubefwd/blob/master/docs/getting-started.md

Example commands to interact with services forwarded by name.

```bash
curl http://my-api:8080/health
psql -h postgres -U admin -d mydb
redis-cli -h redis ping
```

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

### Add Namespace Watcher

Source: https://github.com/txn2/kubefwd/blob/master/docs/api-reference.md

Start forwarding all services within a specific namespace.

```bash
curl -X POST http://kubefwd.internal/api/v1/namespaces \
  -H "Content-Type: application/json" \
  -d '{
    "namespace": "staging",
    "context": "minikube"
  }'
```

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

### Commit message example

Source: https://github.com/txn2/kubefwd/blob/master/CONTRIBUTING.md

A template for writing clear and descriptive commit messages.

```text
Fix: Handle pod deletion during port forward

- Add check for nil channel before send
- Improve error message for connection failures
- Add test for pod deletion scenario
```

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

### Label Selector Examples

Source: https://github.com/txn2/kubefwd/blob/master/docs/advanced-usage.md

Demonstrates various ways to use label selectors for filtering services, including equality-based, set-based, and existence checks. Multiple requirements are combined with AND logic.

```bash
sudo -E kubefwd svc -n default -l app=nginx --tui
```

```bash
sudo -E kubefwd svc -n default -l app==nginx --tui
```

```bash
sudo -E kubefwd svc -n default -l app!=nginx --tui
```

```bash
sudo -E kubefwd svc -n default -l "app in (api, web, worker)" --tui
```

```bash
sudo -E kubefwd svc -n default -l "tier notin (frontend)" --tui
```

```bash
sudo -E kubefwd svc -n default -l "environment" --tui
```

```bash
sudo -E kubefwd svc -n default -l "!canary" --tui
```

```bash
sudo -E kubefwd svc -n default -l app=api,version=v2,team=platform --tui
```

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

### Get Kubernetes Events

Source: https://github.com/txn2/kubefwd/blob/master/docs/api-reference.md

Retrieve Kubernetes events for debugging purposes, such as scheduling, pulling, starting, and killing events. Can be filtered by resource kind and name.

```bash
# Get all events in namespace
curl http://kubefwd.internal/api/v1/kubernetes/events/default
```

```bash
# Filter to pod events
curl "http://kubefwd.internal/api/v1/kubernetes/events/default?resourceKind=Pod"
```

```bash
# Get events for specific pod
curl "http://kubefwd.internal/api/v1/kubernetes/events/default?resourceKind=Pod&resourceName=api-gateway-7d4f5b6c8-abc12"
```

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

### Access Kubernetes services locally by name

Source: https://github.com/txn2/kubefwd/blob/master/README.md

Examples of how to access Kubernetes services by their service names after kubefwd has set up the port forwards. These commands work as if the services were running locally.

```bash
curl http://api-service:8080
```

```bash
mysql -h database -P 3306
```

```bash
redis-cli -h cache -p 6379
```

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

### Launch kubefwd TUI modes

Source: https://github.com/txn2/kubefwd/blob/master/docs/user-guide.md

Commands to start the kubefwd TUI in different configurations. Requires sudo privileges to manage network port forwarding.

```bash
sudo -E kubefwd --tui
```

```bash
sudo -E kubefwd svc -n my-namespace --tui
```

```bash
sudo -E kubefwd svc -n frontend,backend,data --tui
```

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

### Get Specific Service

Source: https://github.com/txn2/kubefwd/blob/master/docs/api-reference.md

Retrieve details for a specific service using the key format service-name.namespace.context.

```bash
curl http://kubefwd.internal/api/v1/services/api-gateway.default.minikube
```

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

### Forward Services with Label Selector

Source: https://github.com/txn2/kubefwd/blob/master/docs/advanced-usage.md

Filter services to be forwarded based on labels. This example forwards services in the 'default' namespace with the label 'team=myteam'.

```bash
sudo -E kubefwd svc -A -l team=myteam --tui
```

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

### GET /api/v1/forwards/:key/http

Source: https://github.com/txn2/kubefwd/blob/master/docs/api-reference.md

Get HTTP traffic captured for a specific forward.

```APIDOC
## GET /api/v1/forwards/:key/http

### Description
Get HTTP traffic captured for a forward.

### Method
GET

### Endpoint
/api/v1/forwards/:key/http

### Parameters
#### Path Parameters
- **key** (string) - Required - The forward key identifier

#### Query Parameters
- **count** (integer) - Optional - Number of entries (default: 50)
```

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

### IP Reservation Config File Format

Source: https://github.com/txn2/kubefwd/blob/master/docs/configuration.md

Example YAML structure for the IP reservation configuration file. It allows defining specific IP reservations for services and optionally a base IP for auto-allocation.

```yaml
# config.yml
reservations:
  # Reserve specific IPs for services
  - service: api-gateway
    namespace: default
    ip: 127.3.3.1

  - service: database
    namespace: default
    ip: 127.3.3.2

  - service: cache
    namespace: default
    ip: 127.3.3.3

# Optional: base IP for auto-allocation
baseIP: 127.1.27.1
```

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

### Build and Run Application

Source: https://github.com/txn2/kubefwd/blob/master/README_PACKAGING.md

Build and run the kubefwd application directly from source. Useful for quick development cycles.

```bash
go run ./cmd/kubefwd/kubefwd.go
```

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

### GET /api/v1/diagnostics

Source: https://github.com/txn2/kubefwd/blob/master/docs/llms-full.txt

Retrieves a diagnostics summary.

```APIDOC
## GET /api/v1/diagnostics

### Description
Retrieves a diagnostics summary.

### Method
GET

### Endpoint
/api/v1/diagnostics
```

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

### GET /api/v1/metrics

Source: https://github.com/txn2/kubefwd/blob/master/docs/llms-full.txt

Retrieves summary metrics.

```APIDOC
## GET /api/v1/metrics

### Description
Retrieves summary metrics.

### Method
GET

### Endpoint
/api/v1/metrics
```

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

### GET /api/v1/kubernetes/services

Source: https://github.com/txn2/kubefwd/blob/master/docs/llms-full.txt

Lists services in a namespace.

```APIDOC
## GET /api/v1/kubernetes/services

### Description
Lists services in a namespace.

### Method
GET

### Endpoint
/api/v1/kubernetes/services
```

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

### Run All Tests

Source: https://github.com/txn2/kubefwd/blob/master/CLAUDE.md

Executes all tests within the project. Use 'go test ./...' to run tests for all packages. For specific packages, use 'go test ./pkg/<package-name>'. Add the -v flag for verbose output.

```bash
# Run all tests
go test ./...
```

```bash
# Run tests for a specific package
go test ./pkg/fwdport
```

```bash
# Run tests with verbose output
go test -v ./pkg/fwdport
```

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

### GET /api/info

Source: https://github.com/txn2/kubefwd/blob/master/docs/llms-full.txt

Retrieves server information.

```APIDOC
## GET /api/info

### Description
Retrieves server information.

### Method
GET

### Endpoint
/api/info
```

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

### GET /api/v1/diagnostics/errors

Source: https://github.com/txn2/kubefwd/blob/master/docs/llms-full.txt

Retrieves current system errors.

```APIDOC
## GET /api/v1/diagnostics/errors

### Description
Retrieves current system errors.

### Method
GET

### Endpoint
/api/v1/diagnostics/errors
```

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

### GET /api/v1/kubernetes/namespaces

Source: https://github.com/txn2/kubefwd/blob/master/docs/llms-full.txt

Lists namespaces in the current context.

```APIDOC
## GET /api/v1/kubernetes/namespaces

### Description
Lists namespaces in the current context.

### Method
GET

### Endpoint
/api/v1/kubernetes/namespaces
```

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

### Build Kubefwd Project

Source: https://github.com/txn2/kubefwd/blob/master/CLAUDE.md

Compiles the kubefwd project using Go. The first command builds a standard executable. The second command includes version information using linker flags.

```bash
# Build the project (uses goreleaser)
go build -o kubefwd ./cmd/kubefwd/kubefwd.go
```

```bash
# Build with version information
go build -ldflags "-X main.Version=dev" -o kubefwd ./cmd/kubefwd/kubefwd.go
```

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

### GET /api/v1/namespaces

Source: https://github.com/txn2/kubefwd/blob/master/docs/llms-full.txt

Lists all active namespace watchers.

```APIDOC
## GET /api/v1/namespaces

### Description
Lists all active namespace watchers.

### Method
GET

### Endpoint
/api/v1/namespaces
```

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

### GET /api/v1/services

Source: https://github.com/txn2/kubefwd/blob/master/docs/llms-full.txt

Lists all currently forwarded services.

```APIDOC
## GET /api/v1/services

### Description
Lists all currently forwarded services.

### Method
GET

### Endpoint
/api/v1/services
```

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

### Run kubefwd in Classic Mode

Source: https://github.com/txn2/kubefwd/blob/master/docs/getting-started.md

Forward services from specific namespaces, optionally using the TUI.

```bash
sudo -E kubefwd svc -n default --tui
```

```bash
sudo -E kubefwd svc -n default
```

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

### GET /api/v1/services

Source: https://github.com/txn2/kubefwd/blob/master/docs/api-reference.md

List all forwarded services with optional filtering.

```APIDOC
## GET /api/v1/services

### Description
List all forwarded services.

### Method
GET

### Endpoint
/api/v1/services

### Parameters
#### Query Parameters
- **namespace** (string) - Optional - Filter by namespace
- **context** (string) - Optional - Filter by context
- **status** (string) - Optional - Filter by status (active, error)
```

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

### Build the kubefwd binary

Source: https://github.com/txn2/kubefwd/blob/master/CONTRIBUTING.md

Commands to clone the repository and compile the project, including an option to set the version string.

```bash
# Clone the repository
git clone https://github.com/txn2/kubefwd.git
cd kubefwd

# Build
go build -o kubefwd ./cmd/kubefwd/kubefwd.go

# Build with version
go build -ldflags "-X main.Version=dev" -o kubefwd ./cmd/kubefwd/kubefwd.go
```

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

### GET /api/v1/kubernetes/pods/:namespace

Source: https://github.com/txn2/kubefwd/blob/master/docs/llms-full.txt

Lists pods in a specific namespace.

```APIDOC
## GET /api/v1/kubernetes/pods/:namespace

### Description
Lists pods in a specific namespace.

### Method
GET

### Endpoint
/api/v1/kubernetes/pods/:namespace

### Parameters
#### Path Parameters
- **namespace** (string) - Required - The target namespace
```

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

### GET /api/health

Source: https://github.com/txn2/kubefwd/blob/master/docs/llms-full.txt

Performs a health check on the kubefwd server.

```APIDOC
## GET /api/health

### Description
Performs a health check on the kubefwd server.

### Method
GET

### Endpoint
/api/health
```

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

### POST /api/v1/services

Source: https://context7.com/txn2/kubefwd/llms.txt

Start forwarding a specific Kubernetes service.

```APIDOC
## POST /api/v1/services

### Description
Start forwarding a specific Kubernetes service.

### Method
POST

### Endpoint
http://kubefwd.internal/api/v1/services

### Parameters
#### Request Body
- **namespace** (string) - Required - The namespace of the service
- **service_name** (string) - Required - The name of the service
- **context** (string) - Required - The Kubernetes context

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful
- **data** (object) - Contains the key and connection details of the forwarded service

#### Response Example
{
  "success": true,
  "data": {
    "key": "my-service.default.minikube",
    "localIP": "127.1.27.2",
    "hostnames": ["my-service", "my-service.default"],
    "ports": [{"local": 8080, "remote": 8080}]
  }
}
```

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

### Get Forward Details

Source: https://github.com/txn2/kubefwd/blob/master/docs/api-reference.md

Retrieve details for a specific port forward.

```bash
curl http://kubefwd.internal/api/v1/forwards/api-gateway-pod-abc.default.minikube
```

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

### Local Build

Source: https://github.com/txn2/kubefwd/blob/master/README_PACKAGING.md

Build a local executable of kubefwd. The output binary is named 'kubefwd'.

```bash
go build -o kubefwd ./cmd/kubefwd/kubefwd.go
```

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

### GET /api/v1/kubernetes/pods/:namespace/:pod/logs

Source: https://github.com/txn2/kubefwd/blob/master/docs/llms-full.txt

Retrieves logs for a specific pod.

```APIDOC
## GET /api/v1/kubernetes/pods/:namespace/:pod/logs

### Description
Retrieves logs for a specific pod.

### Method
GET

### Endpoint
/api/v1/kubernetes/pods/:namespace/:pod/logs

### Parameters
#### Path Parameters
- **namespace** (string) - Required - The target namespace
- **pod** (string) - Required - The target pod name
```

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

### GET /api/v1/services/:key

Source: https://github.com/txn2/kubefwd/blob/master/docs/llms-full.txt

Retrieves details for a specific forwarded service.

```APIDOC
## GET /api/v1/services/:key

### Description
Retrieves details for a specific forwarded service.

### Method
GET

### Endpoint
/api/v1/services/:key

### Parameters
#### Path Parameters
- **key** (string) - Required - The unique identifier for the service
```

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

### Integrate with Tilt

Source: https://github.com/txn2/kubefwd/blob/master/docs/advanced-usage.md

Add kubefwd as a local resource within a Tiltfile.

```python
local_resource(
  'kubefwd',
  serve_cmd='sudo -E kubefwd svc -n default',
  deps=[]
)
```

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

### Run Integration Tests

Source: https://github.com/txn2/kubefwd/blob/master/CLAUDE.md

Commands for setting up a KIND cluster and executing integration tests that require elevated privileges.

```bash
# Setup KIND cluster
./test/scripts/setup-kind.sh
./test/scripts/deploy-test-services.sh test/manifests

# Run integration tests (requires sudo)
sudo -E go test -tags=integration -v ./test/integration/...

# Teardown
./test/scripts/teardown-kind.sh
```

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

### GET /api/v1/services/{key}

Source: https://context7.com/txn2/kubefwd/llms.txt

Retrieve detailed information for a specific forwarded service.

```APIDOC
## GET /api/v1/services/{key}

### Description
Get detailed information for a specific forwarded service.

### Method
GET

### Endpoint
http://kubefwd.internal/api/v1/services/{key}

### Parameters
#### Path Parameters
- **key** (string) - Required - The service key (format: servicename.namespace.context)

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful
- **data** (object) - Detailed service information including ports, pods, and activity

#### Response Example
{
  "success": true,
  "data": {
    "key": "api-gateway.default.minikube",
    "serviceName": "api-gateway",
    "namespace": "default",
    "context": "minikube",
    "status": "active",
    "localIP": "127.1.27.1",
    "hostnames": ["api-gateway", "api-gateway.default"],
    "ports": [
      {"name": "http", "local": 8080, "remote": 8080, "protocol": "TCP"}
    ],
    "pods": [
      {"name": "api-gateway-7d4f5b6c8-abc12", "status": "Running", "ready": true}
    ],
    "bytesIn": 1048576,
    "bytesOut": 524288,
    "lastActivity": "2025-01-15T10:29:45Z"
  }
}
```

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

### Get Namespace Watcher Details

Source: https://github.com/txn2/kubefwd/blob/master/docs/api-reference.md

Retrieve details for a specific namespace watcher.

```bash
curl http://kubefwd.internal/api/v1/namespaces/default.minikube
```

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

### Get HTTP Traffic

Source: https://github.com/txn2/kubefwd/blob/master/docs/api-reference.md

Retrieve captured HTTP traffic for a specific forward.

```bash
curl http://kubefwd.internal/api/v1/forwards/api-gateway.default.minikube/http?count=10
```

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

### Connect to PostgreSQL in kft1

Source: https://github.com/txn2/kubefwd/blob/master/docs/llms-full.txt

Use this command to connect to a PostgreSQL database instance after establishing a connection via Kubefwd.

```bash
psql -h postgres -U admin -d mydb
```

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

### Python Configuration for Notification Service

Source: https://github.com/txn2/kubefwd/blob/master/docs/mcp-integration.md

This configuration snippet shows how to set up database and SMTP hostnames for a notification service, using values provided by MCP after forwarding services.

```python
# config.py
DATABASE_URL = 'postgresql://dev:dev123@postgres:5432/notifications'
SMTP_HOST = 'smtp'
SMTP_PORT = 2525
```

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

### List MCP Tools

Source: https://context7.com/txn2/kubefwd/llms.txt

Reference list of available tools for AI assistants to control kubefwd.

```text
Service Forwarding:
  add_namespace         Forward all services in a namespace
  remove_namespace      Stop forwarding all services in a namespace
  add_service           Forward a single service
  remove_service        Stop forwarding a service
  get_connection_info   Get connection details for a service
  find_services         Search forwarded services

Kubernetes Discovery:
  list_contexts         List available kubeconfig contexts
  list_k8s_namespaces   List namespaces in a context
  list_k8s_services     List services in a namespace

Pod Operations:
  list_pods             List pods with status and health
  get_pod               Get detailed pod information
  get_pod_logs          Stream logs from a pod container
  get_events            Get Kubernetes events for debugging
  get_endpoints         Get service endpoints

Monitoring:
  get_health            Check kubefwd health status
  get_quick_status      Fast health check (ok/issues/error)
  get_metrics           Get traffic metrics
  get_http_traffic      View HTTP requests through forwards
  get_history           Access event/error/reconnection history
  get_logs              Get kubefwd application logs

Troubleshooting:
  diagnose_errors       Analyze errors with fix suggestions
  get_analysis          Full analysis with recommendations
  reconnect_service     Force reconnect a service
  reconnect_all_errors  Reconnect all errored services
  sync_service          Re-sync pods for a service

Utility:
  list_services         List all forwarded services
  get_service           Get detailed service info
  list_hostnames        View /etc/hosts entries
```

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

### POST /api/v1/namespaces

Source: https://github.com/txn2/kubefwd/blob/master/docs/api-reference.md

Add a namespace watcher to start forwarding all services in a namespace.

```APIDOC
## POST /api/v1/namespaces

### Description
Add a namespace watcher (start forwarding all services in namespace).

### Method
POST

### Endpoint
/api/v1/namespaces

### Parameters
#### Request Body
- **namespace** (string) - Required - Namespace to watch
- **context** (string) - Required - Kubernetes context

### Request Example
{
  "namespace": "staging",
  "context": "minikube"
}
```

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

### Refreshing hosts file backup

Source: https://github.com/txn2/kubefwd/blob/master/docs/troubleshooting.md

Create a fresh backup of the hosts file.

```bash
sudo -E kubefwd svc -n default -b --tui
```

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

### GET /api/v1/services

Source: https://context7.com/txn2/kubefwd/llms.txt

List all forwarded services with their status and connection information, with optional filtering.

```APIDOC
## GET /api/v1/services

### Description
List all forwarded services with their status and connection information.

### Method
GET

### Endpoint
http://kubefwd.internal/api/v1/services

### Parameters
#### Query Parameters
- **namespace** (string) - Optional - Filter by namespace
- **status** (string) - Optional - Filter by status (active, error)
- **context** (string) - Optional - Filter by context

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful
- **data** (object) - Contains a list of services and total count

#### Response Example
{
  "success": true,
  "data": {
    "services": [
      {
        "key": "api-gateway.default.minikube",
        "serviceName": "api-gateway",
        "namespace": "default",
        "context": "minikube",
        "status": "active",
        "localIP": "127.1.27.1",
        "hostnames": ["api-gateway", "api-gateway.default"],
        "ports": [{"local": 8080, "remote": 8080}],
        "bytesIn": 1048576,
        "bytesOut": 524288
      }
    ],
    "total": 15
  }
}
```

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

### Build and Release Official Version

Source: https://github.com/txn2/kubefwd/blob/master/README_PACKAGING.md

Create an official release using GoReleaser. Requires the GITHUB_TOKEN environment variable to be set.

```bash
GITHUB_TOKEN=$GITHUB_TOKEN goreleaser --clean
```

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

### Get Service-Grouped Metrics

Source: https://github.com/txn2/kubefwd/blob/master/docs/api-reference.md

Retrieve traffic and performance metrics, grouped by individual services.

```bash
curl http://kubefwd.internal/api/v1/metrics/services
```

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

### Reserve IPs via Configuration File

Source: https://github.com/txn2/kubefwd/blob/master/docs/advanced-usage.md

Define service mappings in a YAML file and reference it using the -z flag.

```yaml
reservations:
  - service: api
    namespace: default
    ip: 127.3.3.1

  - service: database
    namespace: default
    ip: 127.3.3.2

  - service: cache
    namespace: production
    ip: 127.3.3.3
```

```bash
sudo -E kubefwd svc -n default,production -z fwdconf.yml --tui
```

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

### Enable Verbose Logging

Source: https://github.com/txn2/kubefwd/blob/master/docs/troubleshooting.md

Run kubefwd with verbose output to debug service discovery and connection lifecycle.

```bash
sudo -E kubefwd svc -n default -v --tui
```

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

### GET /api/v1/events

Source: https://github.com/txn2/kubefwd/blob/master/docs/llms-full.txt

Provides a real-time event stream using Server-Sent Events (SSE).

```APIDOC
## GET /api/v1/events

### Description
Provides a real-time event stream using Server-Sent Events (SSE).

### Method
GET

### Endpoint
/api/v1/events
```

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

### Diagnostics and Analysis API

Source: https://context7.com/txn2/kubefwd/llms.txt

APIs for troubleshooting issues, getting status overviews, and AI-friendly analysis.

```APIDOC
## Diagnostics and Analysis API

### Description
Troubleshoot issues and get AI-friendly analysis.

### Quick Status Overview

#### Method
GET

#### Endpoint
/api/v1/status

#### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (object)
  - **status** (string) - Overall status (e.g., 'healthy').
  - **message** (string) - A descriptive message about the status.
  - **totalServices** (integer) - Total number of services being managed.
  - **activeServices** (integer) - Number of currently active services.
  - **errorCount** (integer) - Number of errors encountered.

#### Response Example
```json
{
  "success": true,
  "data": {
    "status": "healthy",
    "message": "All services forwarding normally",
    "totalServices": 15,
    "activeServices": 15,
    "errorCount": 0
  }
}
```

### Detailed Analysis with Recommendations

#### Method
GET

#### Endpoint
/api/v1/analyze

### List Current Errors

#### Method
GET

#### Endpoint
/api/v1/diagnostics/errors

### Diagnostics for a Specific Service

#### Method
GET

#### Endpoint
/api/v1/diagnostics/services/{serviceKey}

#### Parameters
#### Path Parameters
- **serviceKey** (string) - Required - The unique key of the service (e.g., api-gateway.default.minikube).

### Network Interface Diagnostics

#### Method
GET

#### Endpoint
/api/v1/diagnostics/network
```

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

### Run Container-Based Tests with Go Test

Source: https://github.com/txn2/kubefwd/blob/master/test/README.md

Alternative method to run container-based integration tests using the `go test` command directly.

```bash
# From project root - no sudo required!
./test/scripts/run-container-tests.sh

# Or use go test directly
go test -tags=integration -v ./test/integration/ -run TestContainer
```

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

### Launch kubefwd with TUI

Source: https://github.com/txn2/kubefwd/blob/master/docs/comparison.md

Launch kubefwd to forward all services in a namespace with an interactive terminal UI. Requires sudo privileges.

```bash
sudo -E kubefwd svc -n dev --tui
```

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

### Run All Integration Tests

Source: https://github.com/txn2/kubefwd/blob/master/test/README.md

Execute all integration tests. This requires sudo privileges due to modifications to system network configurations and hosts files. Always use the -E flag with sudo to preserve environment variables like KUBECONFIG.

```bash
sudo -E go test -tags=integration ./test/integration/...
```

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

### Implement Health Checking

Source: https://github.com/txn2/kubefwd/blob/master/docs/advanced-usage.md

Verify service availability after starting kubefwd by polling the health endpoint.

```bash
# Start kubefwd
sudo -E kubefwd svc -n default &

# Wait for services
sleep 10

# Check a service
curl -sf http://my-service:8080/health || exit 1
```

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

### Verify Test Build Artifacts

Source: https://github.com/txn2/kubefwd/blob/master/README_PACKAGING.md

Check the version of the built kubefwd binary and list the generated artifacts in the dist directory.

```bash
# Check version
./dist/kubefwd_darwin_arm64/kubefwd version
```

```bash
# List built artifacts
ls -lh dist/
```

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

### Get Service Endpoints

Source: https://github.com/txn2/kubefwd/blob/master/docs/api-reference.md

Fetch the endpoints for a given service, indicating which pods are backing the service and their ready state.

```bash
curl http://kubefwd.internal/api/v1/kubernetes/endpoints/default/api-gateway
```

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

### Forward Services in Classic Mode

Source: https://github.com/txn2/kubefwd/blob/master/docs/index.md

Forwards all services within a specific namespace immediately.

```bash
sudo -E kubefwd svc -n my-namespace --tui
```

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

### Get Specific Service Details

Source: https://github.com/txn2/kubefwd/blob/master/docs/api-reference.md

Fetch detailed information for a particular Kubernetes service identified by its namespace and name.

```bash
curl http://kubefwd.internal/api/v1/kubernetes/services/default/api-gateway
```

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

### Build Kubefwd Binary

Source: https://github.com/txn2/kubefwd/blob/master/test/README.md

Build the kubefwd binary from the source code. This binary is required for running the integration tests.

```bash
cd /path/to/kubefwd
go build -o kubefwd ./cmd/kubefwd/kubefwd.go
```

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

### Configure Claude Code MCP

Source: https://context7.com/txn2/kubefwd/llms.txt

Commands to register the kubefwd MCP server and start the application with API support.

```bash
claude mcp add --transport stdio kubefwd -- kubefwd mcp

claude mcp list

sudo -E kubefwd --tui
```

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

### Run Kubefwd with IP Reservation Config

Source: https://github.com/txn2/kubefwd/blob/master/CLAUDE.md

Uses a configuration file for IP reservation to ensure reproducible testing. This allows defining specific IP mappings for services during testing.

```bash
# Use IP reservation config for reproducible testing
sudo -E ./kubefwd svc -n <namespace> -z example.fwdconf.yml
```

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

### Add New Service

Source: https://github.com/txn2/kubefwd/blob/master/docs/api-reference.md

Register a new service to be forwarded.

```bash
curl -X POST http://kubefwd.internal/api/v1/services \
  -H "Content-Type: application/json" \
  -d '{
    "namespace": "default",
    "service_name": "my-service",
    "context": "minikube"
  }'
```

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

### Run Traditional Tests with Go Test

Source: https://github.com/txn2/kubefwd/blob/master/test/README.md

Execute traditional integration tests using the `go test` command, requiring sudo.

```bash
# From project root
sudo -E go test -tags=integration -v ./test/integration/...
```

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

### Verify kubefwd configuration in Claude CLI

Source: https://github.com/txn2/kubefwd/blob/master/docs/mcp-integration.md

Run this command to list configured MCP servers and verify that kubefwd has been successfully added.

```bash
claude mcp list
```