{"id":19030357,"url":"https://github.com/chmouel/kss","last_synced_at":"2026-01-03T11:26:09.046Z","repository":{"id":62757429,"uuid":"223628506","full_name":"chmouel/kss","owner":"chmouel","description":"Kubernetes pod status on steroid 💉","archived":false,"fork":false,"pushed_at":"2023-12-19T17:22:50.000Z","size":8546,"stargazers_count":42,"open_issues_count":2,"forks_count":2,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-23T16:03:55.609Z","etag":null,"topics":["cli","containers","fzf","kubernetes","pods"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/chmouel.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":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2019-11-23T17:36:40.000Z","updated_at":"2023-09-09T22:44:01.000Z","dependencies_parsed_at":"2025-04-20T06:46:26.516Z","dependency_job_id":null,"html_url":"https://github.com/chmouel/kss","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/chmouel/kss","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chmouel%2Fkss","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chmouel%2Fkss/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chmouel%2Fkss/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chmouel%2Fkss/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chmouel","download_url":"https://codeload.github.com/chmouel/kss/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chmouel%2Fkss/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259565531,"owners_count":22877345,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["cli","containers","fzf","kubernetes","pods"],"created_at":"2024-11-08T21:17:41.568Z","updated_at":"2026-01-03T11:26:09.040Z","avatar_url":"https://github.com/chmouel.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# KSS - Kubernetes pod status on steroid 💉\n\nA beautiful and feature-rich tool to show the current status of a pod and its associated `containers` and `initContainers`.\n\nThis was developed out of frustration with `kubectl get pod` not showing much and `kubectl describe pod` showing way too much in a cryptic way. Debugging failed pods with a lot of `initContainers` and `sideCars` usually was done with `kubectl get pod -o yaml |less` with a lot of going up and down over a pager to figure out what's going on and a bunch of swearing 🔞. All those techniques for introspection and debugging are still useful and **KSS** is not planning to fully replace them but now thanks to it you can see quickly what happen and what fails and get your sanity back 😅.\n\n\u003cimg width=\"1193\" height=\"847\" alt=\"image\" src=\"https://github.com/user-attachments/assets/c65ac2e8-ba61-4fbe-a72f-f70af4f9814a\" /\u003e\n\n## Features ✨\n\n- 🎨 **Beautiful UI** with color-coded status indicators, borders, and visual hierarchy\n- 🔍 **Interactive pod selection** using [fzf](https://github.com/junegunn/fzf) with live preview\n- ⏱️ **Watch mode** for real-time monitoring with auto-refresh\n- 📊 **Detailed container information** including:\n  - Container status with visual indicators (✓, ✗, ⏳)\n  - Container age (how long it's been running)\n  - Image names and versions\n  - Restart counts\n  - Ready status\n- 📝 **Enhanced logging** with formatted output and separators\n- 🏷️ **Labels and annotations** display with clean formatting\n- 📅 **Events** with chronological sorting\n- 🚨 **Better error detection** for common failure states\n\n## Usage\n\n### Basic Usage\n\nYou can specify a pod or multiple ones as argument to **KSS**, if you don't it will launch the lovely [fzf](https://github.com/junegunn/fzf) and let you choose the pod interactively, if there is only one pod available it will select it automatically. If you would like to choose multiple pods you can use the key [TAB] and select them, **KSS** will then show them all.\n\n**KSS** shows a preview when running with fzf, it will try to do the preview with itself if it cannot find itself in the `PATH` it will fallback to a good ol' and boring `kubectl describe` 👴🏼👵🏻.\n\n### Command Line Options\n\n```\nUsage: kss [OPTIONS] [POD...]\n\nOptions:\n  -n, --namespace NAMESPACE    Use namespace\n  -r, --restrict REGEXP        Restrict to show only those containers (regexp)\n  -l, --showlog                Show logs of containers\n  --maxlines INT               Maximum line when showing logs (default: -1)\n  -L, --labels                 Show labels\n  -A, --annotations            Show annotations\n  -E, --events                 Show events\n  -w, --watch                  Watch mode (auto-refresh)\n  --watch-interval SECONDS     Watch refresh interval in seconds (default: 2)\n  -h, --help                   Display help message\n```\n\n### Examples\n\n#### Interactive Pod Selection\n\n```bash\n# Launch fzf to interactively select a pod\nkss\n\n# Select from a specific namespace\nkss -n production\n\n# Select multiple pods (use TAB in fzf)\nkss\n```\n\n#### Direct Pod Selection\n\n```bash\n# Show status for a specific pod\nkss my-pod\n\n# Show status for multiple pods\nkss pod-1 pod-2 pod-3\n\n# Show status with namespace\nkss -n production my-pod\n```\n\n#### Viewing Logs\n\n```bash\n# Show logs for all containers\nkss my-pod -l\n\n# Show last 50 lines of logs\nkss my-pod -l --maxlines 50\n\n# Show logs only for containers matching a regex\nkss my-pod -r \"app\" -l\n\n# Show logs for init containers only\nkss my-pod -r \"init\" -l\n```\n\n#### Watch Mode\n\n```bash\n# Watch a pod with default 2-second refresh\nkss my-pod -w\n\n# Watch with custom refresh interval (5 seconds)\nkss my-pod -w --watch-interval 5\n\n# Watch multiple pods\nkss pod-1 pod-2 -w\n\n# Watch with logs\nkss my-pod -w -l\n```\n\n#### Labels and Annotations\n\n```bash\n# Show labels\nkss my-pod -L\n\n# Show annotations\nkss my-pod -A\n\n# Show both\nkss my-pod -L -A\n```\n\n#### Events\n\n```bash\n# Show events for a pod\nkss my-pod -E\n\n# Show events with other information\nkss my-pod -E -L\n```\n\n#### Combined Usage\n\n```bash\n# Full information with logs, labels, and events\nkss my-pod -l -L -A -E\n\n# Watch mode with logs and events\nkss my-pod -w -l -E --watch-interval 3\n```\n\n## Output Format\n\n### Pod Header\n\nThe pod information is displayed in a beautiful box with:\n\n- Pod name\n- Overall status (✅ SUCCESS, 🔄 RUNNING, ❌ FAIL)\n- Namespace\n- Phase\n- Age (time since pod creation)\n\n### Container Information\n\nFor each container, KSS displays:\n\n- **Status**: Visual indicator (✓, ✗, ⏳) with color coding\n  - ✓ Green: Success/Running\n  - ✗ Red: Failed/Error\n  - ⏳ Yellow: Waiting\n- **Image**: Container image name\n- **Restarts**: Number of restarts (highlighted if \u003e 0)\n- **Age**: How long the container has been in its current state\n- **Ready**: Whether the container is ready\n\n### Status Colors\n\n- 🟢 **Green**: Success, Running, Ready\n- 🔵 **Blue**: Running, Active\n- 🟡 **Yellow**: Waiting, Warning, Restarts\n- 🔴 **Red**: Failed, Error, Not Ready\n\n## Install\n\n### Packages\n\n#### Homebrew\n\nYou can install **KSS** latest with homebrew, you just have to fire up those\ncommands in your shell and **KSS** and its zsh completions will be installed :\n\n```shell\nbrew tap chmouel/kss https://github.com/chmouel/kss\nbrew install kss\n```\n\nThis has been tested as working on [linuxbrew](https://docs.brew.sh/Homebrew-on-Linux) too.\n\n#### Arch\n\nIt's available on Arch AUR [here](https://aur.archlinux.org/packages/kss).\n\nInstall it with your favourite aur installer (i.e: [yay](https://github.com/Jguer/yay))\n\n```bash\nyay -S kss\n```\n\n### Manual install\n\nYou just make sure you have [Go](https://golang.org/) (\u003e=1.21), [fzf](https://github.com/junegunn/fzf) and kubectl. You can build from source:\n\n```shell\ngit clone https://github.com/chmouel/kss\ncd kss\ngo build -o kss main.go\nsudo cp kss /usr/local/bin/\n```\n\nOr checkout this GIT repo and build the binary into your path.\n\nWith zsh you can install the [_kss](./_kss) completionfile  to your [fpath](https://unix.stackexchange.com/a/33898).\n\n### Requirements\n\n- **kubectl**: Must be installed and configured\n- **fzf**: Required for interactive pod selection (install via your package manager)\n- **Go**: Only needed if building from source (\u003e=1.21)\n\n\n## Tips \u0026 Tricks 💡\n\n### Quick Debugging Workflow\n\n```bash\n# 1. Find and select the problematic pod\nkss\n\n# 2. View logs for the failing container\nkss my-pod -r \"app\" -l --maxlines 100\n\n# 3. Check events to see what happened\nkss my-pod -E\n\n# 4. Watch the pod recover\nkss my-pod -w\n```\n\n### Using with kubectl aliases\n\n```bash\n# Add to your .bashrc or .zshrc\nalias kp='kss'\nalias kpw='kss -w'\nalias kpl='kss -l'\n```\n\n### Filtering containers\n\n```bash\n# Show only sidecar containers\nkss my-pod -r \"sidecar\"\n\n# Show only init containers\nkss my-pod -r \"init\"\n\n# Show containers matching multiple patterns (use regex)\nkss my-pod -r \"app|worker\"\n```\n\n## Troubleshooting\n\n### fzf not found\n\nIf you get an error about fzf not being found, install it:\n\n```bash\n# macOS\nbrew install fzf\n\n# Linux\nsudo apt install fzf  # Debian/Ubuntu\nsudo yum install fzf  # RHEL/CentOS\n```\n\n### kubectl not configured\n\nMake sure kubectl is installed and your kubeconfig is set up:\n\n```bash\nkubectl get pods\n```\n\n### No pods found\n\nIf KSS says \"No pods is no news which is arguably no worries\", it means:\n\n- No pods exist in the current/default namespace\n- You might need to specify a namespace with `-n`\n- Check your kubectl context: `kubectl config current-context`\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## License\n\nLicensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) for details.\n\n## Misc\n\n- The code has been rewritten in Go for better performance and easier distribution. The original Python version was getting quite tortured, like some sort of spaghetti plate 🍝 with greasy meatballs 🥩 on the top, the kind of stuff you start to write quickly and dirty out of frustration to fix a problem and it grows until it really become an unreadable beast. So we rewrote it in Go! 🎉\n\nThe Go version maintains all the functionality of the Python version while being faster and easier to distribute as a single binary. It also includes many new features like watch mode, better UI, and enhanced container information display.\n\nI may do a [krew](https://github.com/kubernetes-sigs/krew) plugin if this get [requested](https://github.com/chmouel/kss/issues/1) enough. Watch this space as cool people would say 😎🏄🤙.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchmouel%2Fkss","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchmouel%2Fkss","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchmouel%2Fkss/lists"}