Metadata-Version: 2.4
Name: kop-cli
Version: 0.1.0a4
Summary: Terminal-based kubernetes operation platform
Author-email: vegaoqiang <vegaoqiang@gmail.com>
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: k8s,kop,kubernetes,lens,terminal,textual
Classifier: Development Status :: 3 - Alpha
Classifier: Development Status :: 4 - Beta
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows :: Windows 10
Classifier: Operating System :: Microsoft :: Windows :: Windows 11
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Terminals
Requires-Python: >=3.9
Requires-Dist: kubernetes>=33.1.0
Requires-Dist: pyte
Requires-Dist: textual>=8.1.1
Requires-Dist: textual[syntax]
Provides-Extra: dev
Requires-Dist: pytest-asyncio; extra == 'dev'
Requires-Dist: pytest>=9.0.2; extra == 'dev'
Requires-Dist: textual-dev>=1.8.0; extra == 'dev'
Description-Content-Type: text/markdown

![sample](docs/images/sample.png)

[![PyPI version](https://badge.fury.io/py/kop-cli.svg)](https://badge.fury.io/py/kop-cli)
![PyPI - Python Version](https://img.shields.io/pypi/pyversions/kop-cli)
![OS support](https://img.shields.io/badge/OS-macOS%20Linux%20Windows-red)

# kop

`kop` is a terminal-based (TUI) Kubernetes operations platform. Its goal is to provide an interactive experience similar to desktop cluster management tools, but fully within the terminal command line, aiming to solve the problem of conveniently operating Kubernetes clusters when no desktop environment is available.


## Requirements

- Python `>=3.9`
- Terminal environment with TUI support (TrueColor/xterm-256color/Mouse Tracking)

## Installation

```bash
pip install kop-cli
```

After installation, you can directly run:

```bash
kop --version
```


## Usage

### 1. Default Startup (Read Local Configuration)

```bash
kop
```

By default, it will load:

- `~/.kube/config` (if it exists)
- kubeconfig files already synced under `~/.kop/`

If no available cluster is found, you can import configuration from the startup page via `Add` or `Sync`.

### 2. Start Directly with a Specified kubeconfig

```bash
kop --kubeconfig /path/to/kubeconfig.yaml
```

In this mode, the file path and kubeconfig validity are verified, and after validation it enters the resource view directly.

## Operations and Shortcuts
See demo video:
[![Watch the demo](https://img.youtube.com/vi/sEXl9UQQxVc/maxresdefault.jpg)](https://www.youtube.com/watch?v=sEXl9UQQxVc)

Please refer to the [Documentation](https://vegaoqiang.github.io/kop/) for more detailed usage instructions.

### Startup Page (Cluster List)

- `a`: Add cluster
- `c` / `Enter`: Connect to cluster
- `d`: Delete cluster
- `e`: Edit cluster
- `s`: Sync local kubeconfig
- Arrow keys `↑↓←→`: Move between cluster cards

### Resource Page

- Select resource type from the left-side menu
- `]`: Quickly focus the namespace selector
- `/`: Search (menu or resources)
- `c`: Create resource (when supported by the current resource type)
- `Esc`: Return to cluster home page

Tip: Available actions differ by resource in the details/operation panel. The bottom of the interface shows available key hints.

## Kubernetes Version Compatibility Matrix


## FAQ

### Mouse click not working

When using iTerm2 on macOS to SSH into a remote host and run kop, mouse clicks may not work. This happens because in Linux environments, most command-line programs rely on the `$TERM` variable to determine terminal capabilities (such as colors and bold text). A common value is `xterm-256color`. While `xterm-256color` is a general standard, it does not cover all extensions of modern terminals (such as advanced mouse protocols or synchronized updates). `Textual` is a very advanced TUI (text user interface) framework. To provide the best experience, it tries to detect which terminal is actually running. For `iTerm2`, it supports many non-standard advanced features. Textual has internal optimization logic: when it detects `TERM_PROGRAM=iTerm.app`, it switches to an interaction mode optimized for `iTerm2`. If Textual does not see `TERM_PROGRAM=iTerm.app`, it may avoid enabling some advanced interaction features, or due to configuration conflicts, it may fail to properly fall back to a generic mouse mode.

Solutions:

1. Manually run `export TERM_PROGRAM=iTerm.app` on the remote host. After restarting `kop`, mouse clicks should work normally.
2. Update local SSH config on macOS: `~/.ssh/config`, add:

```shell
Host *
    SendEnv TERM_PROGRAM
```

Update remote host `sshd` config: `/etc/ssh/sshd_config`, add:

```shell
AcceptEnv TERM_PROGRAM
```

After restarting the `sshd` service, disconnect and reconnect to the remote host, then run `kop` again. Mouse clicking should be restored.


### Why doesn't kop look good on macOS?
kop is built with Textual for terminal UI. Please refer to the Textual FAQ section about display issues in the default macOS terminal for fixes: https://textual.textualize.io/FAQ/#why-doesnt-textual-look-good-on-macos

### Abnormal display on physical terminals
You may use kop on a physical terminal (a monitor connected to a server via a VGA cable) and find kop UI rendering issues or even crashes. This is because Linux kernel built-in virtual terminals (`tty1`~`tty6`):
* ❌ Do not support True Color (24-bit)
* ❌ Do not support 256 colors
* ✅ Only support 16 colors (sometimes even only 8)
* ✅ Rendering is controlled by the kernel (not by a terminal emulator)

There is currently no good solution. If you must use kop on a physical terminal, one compromise is `kmscon`.

Kmscon is a simple terminal emulator based on linux kernel mode setting (KMS). It is an attempt to replace the in-kernel VT implementation with a userspace console. See https://github.com/kmscon/kmscon


## Roadmap

### Features
* Upload local files to pod containers
* Download files from pod containers to local
* Multi-task window support



