| Name | kpf JSON |
| Version |
0.1.22
JSON |
| download |
| home_page | None |
| Summary | A terminal utility to run kubectl port-forward and automatically restart it when endpoint changes are detected |
| upload_time | 2025-08-29 00:27:07 |
| maintainer | None |
| docs_url | None |
| author | Jesse Goodier |
| requires_python | <3.14,>=3.11 |
| license | MIT License Copyright (c) 2025 Jesse Goodier Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| keywords |
cli
devops
k8s
kubectl
kubernetes
port-forward
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# kpf - A better way to port-forward with kubectl
This is a Python utility that (attempts) to dramatically improve the experience of port-forwarding with kubectl.
It is essentially a wrapper around `kubectl port-forward` that adds an interactive service selection with automatic reconnect when the pods are restarted or your network connection is interrupted (computer goes to sleep, etc).
## Features
- 🔄 **Automatic Restart**: Monitors endpoint changes and restarts port-forward automatically
- 🎯 **Interactive Selection**: Choose services with a colorful, intuitive interface
- 🌈 **Color-coded Status**: Green for services with endpoints, red for those without
- 🔍 **Multi-resource Support**: Services, pods, deployments, and more
- 📊 **Rich Tables**: Beautiful formatted output with port information
- 🏷️ **Namespace Aware**: Work with specific namespaces or across all namespaces
## Installation
**Note**: `oh-my-zsh` kubectl plugin will conflict with this `kpf` command. If you prefer this tool, you can alias at the bottom of your `~/.zshrc` file or use a different alias.
### Homebrew (Recommended)
```bash
brew tap jessegoodier/kpf
brew install kpf
```
Or install directly:
```bash
brew install jessegoodier/kpf/kpf
```
### Using uv
If you have `uv` installed, you can "install" `kpf` with:
```bash
alias kpf="uvx kpf"
```
Install uv with pipx:
```bash
pipx install uv
```
## Usage
### Interactive Mode (Recommended)
**Warm Tip**: You can use the interactive mode to find the service you want, and it will output the command to connect to that service directly next time.
**Note**: You might think that "warm tip" is something that AI wrote, but that's not the case. It really is just a little bit less than a hot tip.
Select services interactively:
Interactive selection in current namespace:
```bash
kpf --prompt
```
Interactive selection in specific namespace:
```bash
kpf --prompt -n production
Show all services across all namespaces:
```bash
kpf --all
```
Include pods and deployments with ports defined:
```bash
kpf --all-ports
```
Combine a few options (interactive mode, all services, and endpoint status checking, debug mode):
```bash
kpf -pAdl
```
### Check Mode
Add endpoint status checking to service selection (slower but shows endpoint health):
```bash
# Interactive selection with endpoint status
kpf --prompt --check
# Show all services with endpoint status
kpf --all --check
# Include pods and deployments with status
kpf --all-ports --check
```
### Legacy Mode
Direct port-forward (backward compatible):
```bash
# Traditional kubectl port-forward syntax
kpf svc/frontend 8080:8080 -n production
kpf pod/my-pod 3000:3000
```
### Command Options
```sh
There is no default command. You must specify one of the arguments below.
Example usage:
kpf svc/frontend 8080:8080 -n production # Direct port-forward (backwards compatible with kpf alias)
kpf --prompt (or -p) # Interactive service selection
kpf --prompt -n production # Interactive selection in specific namespace
kpf --all (or -A) # Show all services across all namespaces
kpf --all-ports (or -l) # Show all services with their ports
kpf --prompt --check -n production # Interactive selection with endpoint status
```
## Examples
### Interactive Service Selection
Fast mode (without endpoint checking):
```bash
$ kpf --prompt -n kube-system
Services in namespace: kube-system
# Type Name Ports
1 SERVICE kube-dns 53, 9153
2 SERVICE metrics-server 443
3 SERVICE kubernetes-dashboard 443
Select a service [1]: 1
Local port (press Enter for 53): 5353
```
With endpoint status checking:
```bash
$ kpf --prompt --check -n kube-system
Services in namespace: kube-system
# Type Name Ports Status
1 SERVICE kube-dns 53, 9153 ✓
2 SERVICE metrics-server 443 ✓
3 SERVICE kubernetes-dashboard 443 ✗
✓ = Has endpoints ✗ = No endpoints
Select a service [1]: 1
Local port (press Enter for 53): 5353
```
### Cross-Namespace Discovery
```bash
$ kpf --all
Services across all namespaces
# Namespace Type Name Ports Status
1 default SERVICE kubernetes 443 ✓
2 kube-system SERVICE kube-dns 53, 9153 ✓
3 production SERVICE frontend 80, 443 ✓
4 production SERVICE backend 8080 ✗
```
## How It Works
1. **Port-Forward Thread**: Runs kubectl port-forward in a separate thread
2. **Endpoint Watcher**: Monitors endpoint changes using `kubectl get ep -w`
3. **Automatic Restart**: When endpoints change, gracefully restarts the port-forward
4. **Service Discovery**: Uses kubectl to discover services and their endpoint status
## Requirements
- kubectl configured with cluster access
## Development
### Setup Development Environment
```bash
# Clone the repository
git clone https://github.com/jessegoodier/kpf.git
cd kpf
# Install with development dependencies
uv venv
uv pip install -e ".[dev]"
source .venv/bin/activate
```
### Code Quality Tools
```bash
# Format and lint code
uvx ruff check . --fix
uvx ruff format .
# Sort imports
uvx isort .
# Run tests
uv run pytest
```
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests and linting
5. Submit a pull request
## License
MIT License - see [LICENSE](LICENSE) file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "kpf",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.14,>=3.11",
"maintainer_email": null,
"keywords": "cli, devops, k8s, kubectl, kubernetes, port-forward",
"author": "Jesse Goodier",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/42/84/8e0c2d42b053d0be652dcfb974dc0cbf4817b4396d3658b32bf498253a88/kpf-0.1.22.tar.gz",
"platform": null,
"description": "# kpf - A better way to port-forward with kubectl\n\nThis is a Python utility that (attempts) to dramatically improve the experience of port-forwarding with kubectl.\n\nIt is essentially a wrapper around `kubectl port-forward` that adds an interactive service selection with automatic reconnect when the pods are restarted or your network connection is interrupted (computer goes to sleep, etc).\n\n## Features\n\n- \ud83d\udd04 **Automatic Restart**: Monitors endpoint changes and restarts port-forward automatically\n- \ud83c\udfaf **Interactive Selection**: Choose services with a colorful, intuitive interface\n- \ud83c\udf08 **Color-coded Status**: Green for services with endpoints, red for those without\n- \ud83d\udd0d **Multi-resource Support**: Services, pods, deployments, and more\n- \ud83d\udcca **Rich Tables**: Beautiful formatted output with port information\n- \ud83c\udff7\ufe0f **Namespace Aware**: Work with specific namespaces or across all namespaces\n\n## Installation\n\n**Note**: `oh-my-zsh` kubectl plugin will conflict with this `kpf` command. If you prefer this tool, you can alias at the bottom of your `~/.zshrc` file or use a different alias.\n\n### Homebrew (Recommended)\n\n```bash\nbrew tap jessegoodier/kpf\nbrew install kpf\n```\n\nOr install directly:\n\n```bash\nbrew install jessegoodier/kpf/kpf\n```\n\n### Using uv\n\nIf you have `uv` installed, you can \"install\" `kpf` with:\n\n```bash\nalias kpf=\"uvx kpf\"\n```\n\nInstall uv with pipx:\n\n```bash\npipx install uv\n```\n\n## Usage\n\n### Interactive Mode (Recommended)\n\n**Warm Tip**: You can use the interactive mode to find the service you want, and it will output the command to connect to that service directly next time.\n\n**Note**: You might think that \"warm tip\" is something that AI wrote, but that's not the case. It really is just a little bit less than a hot tip.\n\n\n\nSelect services interactively:\n\nInteractive selection in current namespace:\n\n```bash\nkpf --prompt\n```\n\nInteractive selection in specific namespace:\n\n```bash\nkpf --prompt -n production\n\nShow all services across all namespaces:\n\n```bash\nkpf --all\n```\n\nInclude pods and deployments with ports defined:\n\n```bash\nkpf --all-ports\n```\n\nCombine a few options (interactive mode, all services, and endpoint status checking, debug mode):\n\n```bash\nkpf -pAdl\n```\n\n### Check Mode\n\nAdd endpoint status checking to service selection (slower but shows endpoint health):\n\n```bash\n# Interactive selection with endpoint status\nkpf --prompt --check\n\n# Show all services with endpoint status\nkpf --all --check\n\n# Include pods and deployments with status\nkpf --all-ports --check\n```\n\n### Legacy Mode\n\nDirect port-forward (backward compatible):\n\n```bash\n# Traditional kubectl port-forward syntax\nkpf svc/frontend 8080:8080 -n production\nkpf pod/my-pod 3000:3000\n```\n\n### Command Options\n\n```sh\nThere is no default command. You must specify one of the arguments below.\n\nExample usage:\n kpf svc/frontend 8080:8080 -n production # Direct port-forward (backwards compatible with kpf alias)\n kpf --prompt (or -p) # Interactive service selection\n kpf --prompt -n production # Interactive selection in specific namespace\n kpf --all (or -A) # Show all services across all namespaces\n kpf --all-ports (or -l) # Show all services with their ports\n kpf --prompt --check -n production # Interactive selection with endpoint status\n```\n\n## Examples\n\n### Interactive Service Selection\n\nFast mode (without endpoint checking):\n\n```bash\n$ kpf --prompt -n kube-system\n\nServices in namespace: kube-system\n\n# Type Name Ports\n1 SERVICE kube-dns 53, 9153\n2 SERVICE metrics-server 443\n3 SERVICE kubernetes-dashboard 443\n\nSelect a service [1]: 1\nLocal port (press Enter for 53): 5353\n```\n\nWith endpoint status checking:\n\n```bash\n$ kpf --prompt --check -n kube-system\n\nServices in namespace: kube-system\n\n# Type Name Ports Status\n1 SERVICE kube-dns 53, 9153 \u2713\n2 SERVICE metrics-server 443 \u2713\n3 SERVICE kubernetes-dashboard 443 \u2717\n\n\u2713 = Has endpoints \u2717 = No endpoints\n\nSelect a service [1]: 1\nLocal port (press Enter for 53): 5353\n```\n\n### Cross-Namespace Discovery\n\n```bash\n$ kpf --all\n\nServices across all namespaces\n\n# Namespace Type Name Ports Status\n1 default SERVICE kubernetes 443 \u2713\n2 kube-system SERVICE kube-dns 53, 9153 \u2713\n3 production SERVICE frontend 80, 443 \u2713\n4 production SERVICE backend 8080 \u2717\n```\n\n## How It Works\n\n1. **Port-Forward Thread**: Runs kubectl port-forward in a separate thread\n2. **Endpoint Watcher**: Monitors endpoint changes using `kubectl get ep -w`\n3. **Automatic Restart**: When endpoints change, gracefully restarts the port-forward\n4. **Service Discovery**: Uses kubectl to discover services and their endpoint status\n\n## Requirements\n\n- kubectl configured with cluster access\n\n## Development\n\n### Setup Development Environment\n\n```bash\n# Clone the repository\ngit clone https://github.com/jessegoodier/kpf.git\ncd kpf\n\n# Install with development dependencies\nuv venv\nuv pip install -e \".[dev]\"\nsource .venv/bin/activate\n```\n\n### Code Quality Tools\n\n```bash\n# Format and lint code\nuvx ruff check . --fix\nuvx ruff format .\n\n# Sort imports\nuvx isort .\n\n# Run tests\nuv run pytest\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Run tests and linting\n5. Submit a pull request\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n",
"bugtrack_url": null,
"license": "MIT License Copyright (c) 2025 Jesse Goodier Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.",
"summary": "A terminal utility to run kubectl port-forward and automatically restart it when endpoint changes are detected",
"version": "0.1.22",
"project_urls": {
"Homepage": "https://github.com/jessegoodier/kpf",
"Issues": "https://github.com/jessegoodier/kpf/issues",
"Repository": "https://github.com/jessegoodier/kpf"
},
"split_keywords": [
"cli",
" devops",
" k8s",
" kubectl",
" kubernetes",
" port-forward"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "b10774b8342794c4d77e691d20133e7c52ef26f909c407ecb4fff8fdc9c8f40d",
"md5": "9b5b3783c028b907b39249b217ee0441",
"sha256": "d3be3ccd678097205235cc1f5af430d6d0b407a053821feb36297ea36d72daa3"
},
"downloads": -1,
"filename": "kpf-0.1.22-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9b5b3783c028b907b39249b217ee0441",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.14,>=3.11",
"size": 26083,
"upload_time": "2025-08-29T00:27:06",
"upload_time_iso_8601": "2025-08-29T00:27:06.668244Z",
"url": "https://files.pythonhosted.org/packages/b1/07/74b8342794c4d77e691d20133e7c52ef26f909c407ecb4fff8fdc9c8f40d/kpf-0.1.22-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "42848e0c2d42b053d0be652dcfb974dc0cbf4817b4396d3658b32bf498253a88",
"md5": "1ffa2902d184af11f476157ef192d3a7",
"sha256": "c1c2df4cd8d357a5bd71aa3aa2c8eb0afe7f972707857153be0e1725ad88e76c"
},
"downloads": -1,
"filename": "kpf-0.1.22.tar.gz",
"has_sig": false,
"md5_digest": "1ffa2902d184af11f476157ef192d3a7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.14,>=3.11",
"size": 24802,
"upload_time": "2025-08-29T00:27:07",
"upload_time_iso_8601": "2025-08-29T00:27:07.509728Z",
"url": "https://files.pythonhosted.org/packages/42/84/8e0c2d42b053d0be652dcfb974dc0cbf4817b4396d3658b32bf498253a88/kpf-0.1.22.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-29 00:27:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jessegoodier",
"github_project": "kpf",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "kpf"
}
