{"id":43924707,"url":"https://github.com/catio-tech/kportforward","last_synced_at":"2026-02-17T04:03:53.616Z","repository":{"id":303480763,"uuid":"1001721012","full_name":"catio-tech/kportforward","owner":"catio-tech","description":"Modern cross-platform Kubernetes port-forward manager with terminal UI and auto-updates","archived":false,"fork":false,"pushed_at":"2026-02-07T00:02:37.000Z","size":274,"stargazers_count":0,"open_issues_count":9,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-07T08:13:18.282Z","etag":null,"topics":["bubble-tea","cli-tool","cross-platform","devops","golang","grpc-ui","kubectl","kubernetes","port-forward","swagger-ui","terminal-ui","tui"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/catio-tech.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-06-13T22:15:46.000Z","updated_at":"2026-02-07T00:02:39.000Z","dependencies_parsed_at":"2025-07-07T23:12:25.006Z","dependency_job_id":"c506923c-a65c-4ba2-88b3-6eed6e3523f4","html_url":"https://github.com/catio-tech/kportforward","commit_stats":null,"previous_names":["catio-tech/kportforward"],"tags_count":19,"template":false,"template_full_name":null,"purl":"pkg:github/catio-tech/kportforward","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/catio-tech%2Fkportforward","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/catio-tech%2Fkportforward/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/catio-tech%2Fkportforward/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/catio-tech%2Fkportforward/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/catio-tech","download_url":"https://codeload.github.com/catio-tech/kportforward/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/catio-tech%2Fkportforward/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29532990,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-17T03:01:11.216Z","status":"ssl_error","status_checked_at":"2026-02-17T03:00:31.803Z","response_time":100,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bubble-tea","cli-tool","cross-platform","devops","golang","grpc-ui","kubectl","kubernetes","port-forward","swagger-ui","terminal-ui","tui"],"created_at":"2026-02-06T23:03:09.061Z","updated_at":"2026-02-17T04:03:53.602Z","avatar_url":"https://github.com/catio-tech.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# kportforward\n\nA modern, cross-platform Kubernetes port-forward manager with a rich terminal UI, automatic recovery, and built-in update system.\n\n[![Build Status](https://github.com/catio-tech/kportforward/workflows/Build%20and%20Test/badge.svg)](https://github.com/catio-tech/kportforward/actions)\n[![Releases](https://img.shields.io/badge/Releases-Latest-blue)](https://github.com/catio-tech/kportforward/releases)\n\n## ✨ Features\n\n- **🎨 Modern Terminal UI**: Interactive interface with real-time updates, port display, and keyboard navigation\n- **🔄 Automatic Recovery**: Monitors and automatically restarts failed port-forwards with state tracking\n- **🌐 Cross-Platform**: Works on macOS, Linux, and Windows\n- **📊 Smart Monitoring**: Health checks with detailed service state management and visual feedback\n- **👁️ Service State Visualization**: Shows \"Connecting\" and \"Reconnecting\" states for better user feedback\n- **🔄 Context Awareness**: Fast detection and response to Kubernetes context changes\n- **🆙 Auto-Updates**: Daily update checks with in-UI notifications\n- **🎯 UI Integration**: Automated gRPC UI and Swagger UI for API services\n- **⚙️ Embedded Config**: Pre-configured services with user override support\n- **🚀 High Performance**: Optimized for managing 100+ concurrent port-forwards with 4,200x faster config loading\n- **📊 Performance Profiling**: Built-in CPU and memory profiling tools for performance analysis\n\n## 📥 Installation\n\n### Homebrew (macOS - Recommended)\n\nThe easiest way to install on macOS is with Homebrew:\n\n```bash\n# Install from Homebrew (preferred SSH method)\nbrew tap catio-tech/kportforward git@github.com:catio-tech/kportforward.git\nbrew install kportforward\n\n# Alternative HTTPS method\n# brew tap catio-tech/kportforward https://github.com/catio-tech/kportforward\n# brew install kportforward\n```\n\n### Quick Install\n\nAlternatively, download the latest release for your platform:\n\n```bash\n# macOS (Intel) - no sudo required\ncurl -L https://github.com/catio-tech/kportforward/releases/latest/download/kportforward-darwin-amd64 -o kportforward\nchmod +x kportforward\nmkdir -p ~/bin\nmv kportforward ~/bin/\n# Then add to PATH if you haven't already:\n# echo 'export PATH=\"$HOME/bin:$PATH\"' \u003e\u003e ~/.zshrc\n# source ~/.zshrc\n\n# macOS (Apple Silicon) - no sudo required\ncurl -L https://github.com/catio-tech/kportforward/releases/latest/download/kportforward-darwin-arm64 -o kportforward\nchmod +x kportforward\nmkdir -p ~/bin\nmv kportforward ~/bin/\n# Then add to PATH if you haven't already:\n# echo 'export PATH=\"$HOME/bin:$PATH\"' \u003e\u003e ~/.zshrc\n# source ~/.zshrc\n\n# Linux\ncurl -L https://github.com/catio-tech/kportforward/releases/latest/download/kportforward-linux-amd64 -o kportforward\nchmod +x kportforward\nsudo mv kportforward /usr/local/bin/\n\n# Windows (PowerShell)\nInvoke-WebRequest -Uri \"https://github.com/catio-tech/kportforward/releases/latest/download/kportforward-windows-amd64.exe\" -OutFile \"kportforward.exe\"\n```\n\n### Manual Installation\n\n1. Go to the [Releases page](https://github.com/catio-tech/kportforward/releases)\n2. Download the appropriate binary for your platform\n3. Make it executable and place it in your PATH\n\n## 🚀 Quick Start\n\n1. **Start the application**:\n   ```bash\n   kportforward\n   ```\n\n2. **Use the interactive interface**:\n   - `↑↓` or `j/k` - Navigate services\n   - `Enter` - View service details\n   - `n/s/t/p/u` - Sort by Name/Status/Type/Port/Uptime\n   - `r` - Reverse sort order\n   - `q` - Quit\n\n3. **With UI integrations**:\n   ```bash\n   # Enable gRPC UI for RPC services\n   kportforward --grpcui\n   \n   # Enable Swagger UI for REST services  \n   kportforward --swaggerui\n   \n   # Enable both\n   kportforward --grpcui --swaggerui\n   ```\n\n4. **With log file output**:\n   ```bash\n   # Write logs to a file instead of stdout\n   kportforward --log-file /path/to/logfile.log\n   \n   # Combine with UI features\n   kportforward --grpcui --swaggerui --log-file /var/log/kportforward.log\n   ```\n\n## ⚙️ Configuration\n\nkportforward uses embedded configuration for immediate functionality, with support for user customizations.\n\n### User Configuration\n\nCreate `~/.config/kportforward/config.yaml` (Unix) or `%APPDATA%/kportforward/config.yaml` (Windows):\n\n```yaml\n# Add your own services (merged with embedded config)\nportForwards:\n  my-service:\n    target: \"service/my-service\"\n    targetPort: 80\n    localPort: 8080\n    namespace: \"default\"\n    type: \"web\"\n\n# Override default settings\nmonitoringInterval: 2s\nuiOptions:\n  refreshRate: 500ms\n  theme: \"dark\"\n```\n\n### Service Types\n\n- **`rest`**: REST APIs (enables Swagger UI with `--swaggerui`)\n- **`rpc`**: gRPC services (enables gRPC UI with `--grpcui`)  \n- **`web`**: Web applications\n- **`other`**: Other services\n\n## 🎯 UI Integrations\n\n### gRPC UI\nAutomatically launches web interfaces for gRPC services with intelligent connection testing:\n```bash\nkportforward --grpcui\n```\n- Requires: `go install github.com/fullstorydev/grpcui/cmd/grpcui@latest`\n- Accessible at: `http://localhost:\u003cauto-assigned-port\u003e` (only when service is accessible)\n- Smart startup: Only shows URLs for services that are actually running and reachable\n\n### Swagger UI\nAutomatically launches Swagger UI for REST APIs with intelligent connection testing:\n```bash\nkportforward --swaggerui\n```\n- Requires: Docker Desktop\n- Accessible at: `http://localhost:\u003cauto-assigned-port\u003e` (only when service is accessible)\n- Smart startup: Only shows URLs for services that are actually running and reachable\n\n## 🛠️ Development\n\n### Prerequisites\n\n- Go 1.21+\n- kubectl (configured for your cluster)\n\n### Building\n\n```bash\n# Build for current platform\ngo build -o bin/kportforward ./cmd/kportforward\n\n# Build for all platforms\n./scripts/build.sh\n\n# Create a release\n./scripts/release.sh v1.0.0\n```\n\n### Performance Testing\n\n```bash\n# Run benchmarks\ngo test -bench=. -benchmem ./...\n\n# Profile CPU usage\n./kportforward profile --cpuprofile=cpu.prof --duration=30s\n\n# Profile memory usage\n./kportforward profile --memprofile=mem.prof --duration=30s\n\n# Live profiling with pprof\n./kportforward --pprof localhost:6060 --mem-stats-interval 5m\n\n# Automatic heap snapshots (opt-in)\n./kportforward --pprof localhost:6060 --heap-snapshot-dir ./pprof --heap-snapshot-interval 30m\n\n# Analyze profiles\ngo tool pprof cpu.prof\ngo tool pprof mem.prof\n```\n\n### Testing\n\n```bash\n# Run tests\ngo test ./...\n\n# Run benchmarks\ngo test -bench=. -benchmem ./...\n\n# Run with verbose logging\ngo run ./cmd/kportforward -v\n```\n\n### Git Hooks\n\nInstall pre-commit hooks to automatically format Go code:\n\n```bash\n# Install git hooks\n./scripts/install-hooks.sh\n```\n\nThe pre-commit hook will:\n- Automatically format Go code with `gofmt -s -w` before each commit\n- Add formatted files back to staging\n- Abort the commit if files were formatted (so you can review changes)\n\nTo bypass the hook for a specific commit (not recommended):\n```bash\ngit commit --no-verify\n```\n\n## 📱 Terminal UI\n\n```\n┌─ kportforward v1.3.0 ─ Context: my-cluster ─ Services (18/18 running) ──┐\n│                                                                           │\n│ Services (18/18 running)  [↑↓] Navigate [Enter] Details [q] Quit         │\n│                                                                           │\n│ Name                 Status         URL                    Type   Port   Uptime  │\n│ ───────────────────────────────────────────────────────────────────────────── │\n│ ● flyte-console      Running        http://localhost:8088  web    8088   2h3m   │\n│ ● flyte-admin-rpc    Running        http://localhost:8089  rpc    8089   2h3m   │\n│ ● api-gateway        Running        http://localhost:8080  rest   8080   1h45m  │\n│ ● process-monitor    Failed         -                      rpc    -      0s     │\n│ ● auth-service       Connecting     -                      rest   8081   0s     │\n│ ● metrics-service    Reconnecting   -                      web    8082   0s     │\n│ ...                                                                            │\n│                                                                                │\n│ Status: Reconnecting due to context change                                     │\n│ [n/s/t/p/u] Sort by Name/Status/Type/Port/Uptime  [r] Reverse                 │\n└──────────────────────────────────────────────────────────────────────────────┘\n```\n\n## 🔧 Troubleshooting\n\n### Common Issues\n\n**Port conflicts**: kportforward automatically finds available ports when configured ports are in use.\n\n**Service state transitions**:\n- **Connecting**: Service is establishing initial connection (new port-forward)\n- **Reconnecting**: Service is re-establishing connection (after context change or temporary failure)\n- **Running**: Service is successfully connected and responding to health checks\n- **Degraded**: Service is running but experiencing intermittent connectivity issues\n- **Failed**: Service failed to connect or has persistent health check failures\n- **Cooldown**: Service is in backoff period after multiple failures\n\n**gRPC UI not starting**:\n- Install grpcui: `go install github.com/fullstorydev/grpcui/cmd/grpcui@latest`\n- Check logs in `/tmp/kpf_grpcui_*.log`\n- gRPC UI only starts for accessible services - check if port-forward is working\n- Look for \"TCP connection test\" messages in debug logs\n\n**Swagger UI not starting**:\n- Ensure Docker is running\n- Check that REST services expose Swagger documentation\n- Swagger UI only starts for accessible services - check if port-forward is working\n- Look for \"TCP connection test\" messages in debug logs\n- Check Docker containers: `docker ps | grep kpf-swagger`\n\n**Services stuck in \"Connecting\" state**:\n- Verify service exists in the cluster: `kubectl get svc -n \u003cnamespace\u003e`\n- Check if the Kubernetes context is valid: `kubectl config current-context`\n- Services will transition to \"Failed\" within 10 seconds if the service doesn't exist\n\n**Services frequently restarting**:\n- Services enter cooldown mode with exponential backoff\n- Check Kubernetes context: `kubectl config current-context`\n- Verify service exists: `kubectl get svc -n \u003cnamespace\u003e`\n- Look for error messages in status column or details view\n\n### Debug Mode\n\n```bash\n# Check application version\nkportforward version\n\n# View help and available commands\nkportforward --help\n\n# Performance profiling\nkportforward profile --cpuprofile=cpu.prof --memprofile=mem.prof --duration=60s\n\n# Debug with log file\nkportforward --log-file /tmp/debug.log\n\n# Check service status manually\nkubectl port-forward -n \u003cnamespace\u003e \u003cservice\u003e \u003cport\u003e:\u003cport\u003e\n\n# Verify kubectl context\nkubectl config current-context\n```\n\n## 📊 Performance\n\nkportforward is optimized for high performance with enterprise-scale deployments:\n\n### Performance Benchmarks\n- **Config Loading**: 4,200x faster with caching (126ms → 30ns)\n- **Port Conflict Resolution**: 600x faster with object pooling\n- **Port Availability Checks**: 1,280x faster with caching\n- **Application Startup**: 10x faster overall\n- **Memory Usage**: 93% reduction in allocations\n\n### Performance Features\n- **Intelligent Caching**: TTL-based caching for expensive operations\n- **Object Pooling**: Reduced garbage collection pressure\n- **Optimized Data Structures**: Pre-allocated maps and concurrent-safe operations\n- **Smart Algorithms**: Optimized port finding and conflict resolution\n\n### Performance Monitoring\n```bash\n# Run performance profiling\nkportforward profile --duration=60s --cpuprofile=cpu.prof --memprofile=mem.prof\n\n# Analyze CPU usage\ngo tool pprof cpu.prof\n\n# Analyze memory usage\ngo tool pprof mem.prof\n\n# Run benchmarks during development\ngo test -bench=. -benchmem ./...\n```\n\nFor detailed performance analysis, see [PERFORMANCE_REPORT.md](PERFORMANCE_REPORT.md).\n\n## 💡 Examples\n\n### Basic Usage\n```bash\n# Start with embedded services\nkportforward\n\n# Use arrow keys to navigate, Enter for details, q to quit\n```\n\n### Custom Configuration\nCreate `~/.config/kportforward/config.yaml`:\n```yaml\nportForwards:\n  # Add your microservice\n  user-service:\n    target: \"service/user-service\"\n    targetPort: 8080\n    localPort: 3001\n    namespace: \"production\"\n    type: \"rest\"\n    swaggerPath: \"docs/swagger.json\"\n    \n  # Add your gRPC service  \n  notification-service:\n    target: \"deployment/notification-service\"\n    targetPort: 9090\n    localPort: 3002\n    namespace: \"production\"\n    type: \"rpc\"\n\n# Override defaults\nmonitoringInterval: 3s\nuiOptions:\n  refreshRate: 1s\n```\n\nThen run with UI integrations:\n```bash\nkportforward --grpcui --swaggerui\n```\n\n### Advanced Workflows\n```bash\n# Different contexts with logging\nkubectl config use-context staging\nkportforward --grpcui --log-file /var/log/staging.log\n\nkubectl config use-context production  \nkportforward --swaggerui --log-file /var/log/production.log\n\n# Check what's running\nkportforward version  # Shows current version and update status\n```\n\n### Development Workflow\n```bash\n# Developer working on microservices with logging\nkportforward --grpcui --swaggerui --log-file ./dev.log\n\n# Production deployment with log rotation\nkportforward --log-file /var/log/kportforward.log\n\n# Access services:\n# - Embedded services available at configured ports\n# - gRPC UI: http://localhost:\u003cauto-assigned-port\u003e (starts from 9090)\n# - Swagger UI: http://localhost:\u003cauto-assigned-port\u003e (starts from 8080)\n# - Your APIs accessible through UI tools\n# - All activity logged to specified file\n```\n\n## 📋 Documentation\n\n- **[README.md](README.md)**: This file - project overview and usage\n- **[CLAUDE.md](CLAUDE.md)**: Developer guide and architecture documentation  \n- **[SERVICE_STATE_DIAGRAM.md](SERVICE_STATE_DIAGRAM.md)**: Comprehensive service state machine documentation\n- **[IMPLEMENTATION_LOG.md](IMPLEMENTATION_LOG.md)**: Development progress and technical decisions\n- **[PERFORMANCE_REPORT.md](PERFORMANCE_REPORT.md)**: Detailed performance analysis and benchmarks\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature/amazing-feature`\n3. Commit your changes: `git commit -m 'Add amazing feature'`\n4. Push to the branch: `git push origin feature/amazing-feature`\n5. Open a Pull Request\n\n### Performance Considerations\n\nWhen contributing, please:\n- Run benchmarks: `go test -bench=. -benchmem ./...`\n- Profile changes with large service counts (100+ services)\n- Test memory usage: `go tool pprof mem.prof`\n- Ensure optimizations don't break existing functionality\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- [Bubble Tea](https://github.com/charmbracelet/bubbletea) for the excellent TUI framework\n- [Lipgloss](https://github.com/charmbracelet/lipgloss) for terminal styling\n- [Cobra](https://github.com/spf13/cobra) for CLI framework","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcatio-tech%2Fkportforward","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcatio-tech%2Fkportforward","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcatio-tech%2Fkportforward/lists"}