npm package: @redredchen01/k8s-tools
Description: Kubernetes management CLI — pods, logs, exec, deploy, scale, rollout, config
Author: redredchen01
Latest version: 1.0.0

# @redredchen01/k8s-tools

> Kubernetes management CLI — pods, logs, exec, deploy, scale, rollout, config

[![npm version](https://img.shields.io/npm/v/@redredchen01/k8s-tools.svg)](https://www.npmjs.com/package/@redredchen01/k8s-tools)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Install

```bash
npm install -g @redredchen01/k8s-tools
```

## Prerequisites

- `kubectl` installed and configured with a valid kubeconfig

## Quick Start

```bash
k8s-tools pods                               # list pods in current namespace
k8s-tools pods --namespace production        # list pods in a specific namespace
k8s-tools logs --pod api-server --follow     # tail logs
k8s-tools exec --pod nginx-abc123            # open shell
k8s-tools deploy --file k8s/api.yaml --wait  # apply manifest and wait
k8s-tools scale --deployment worker --replicas 3
k8s-tools rollout status --deployment api-server
k8s-tools config current                     # show active context and namespace
```

## Commands

### `pods` — List pods with readable status

Display pods with colorized status indicators and human-readable age. More
readable than raw `kubectl get pods`.

```bash
k8s-tools pods --namespace production
k8s-tools pods --all-namespaces
k8s-tools pods --label app=nginx --wide
k8s-tools pods --namespace staging --json
```

Options: `--namespace NS`, `--all-namespaces`, `--label SELECTOR`, `--wide`, `--json`

---

### `logs` — Multi-pod tail logs

Stream or display logs from one or more pods matching a name pattern.
When multiple pods match, logs are prefixed with the pod name (stern-like).

```bash
k8s-tools logs --pod api-server --namespace production --tail 200
k8s-tools logs --pod worker --follow
k8s-tools logs --pod job-runner --since 1h --namespace staging
```

Options: `--pod POD`, `--namespace NS`, `--container NAME`, `--tail N`, `--follow`, `--since DURATION`, `--json`

---

### `exec` — Quick pod shell access

Open an interactive shell inside a pod, or run a one-off command and capture
its output.

```bash
k8s-tools exec --pod nginx-abc123
k8s-tools exec --pod api-server --container sidecar --shell /bin/bash
k8s-tools exec --pod nginx-abc123 --command "nginx -t"
k8s-tools exec --pod nginx-abc123 --command "cat /etc/hosts" --json
```

Options: `--pod POD`, `--namespace NS`, `--container NAME`, `--shell SHELL`, `--command CMD`, `--json`

Note: `--json` is only valid with `--command`; interactive shell mode does not support JSON output.

---

### `deploy` — Apply deployment YAML

Apply a Kubernetes YAML manifest with optional client-side dry-run and
automatic rollout wait.

```bash
k8s-tools deploy --file deployment.yaml
k8s-tools deploy --file k8s/api.yaml --namespace production --dry-run
k8s-tools deploy --file deployment.yaml --wait --timeout 120
```

Options: `--file FILE`, `--namespace NS`, `--dry-run`, `--wait`, `--timeout SECS`, `--json`

---

### `scale` — Adjust replica count

Scale a Deployment to a target number of replicas and optionally wait for
the operation to stabilize.

```bash
k8s-tools scale --deployment api-server --replicas 3
k8s-tools scale --deployment worker --replicas 0 --namespace staging
k8s-tools scale --deployment api-server --replicas 5 --wait
```

Options: `--deployment NAME`, `--replicas N`, `--namespace NS`, `--wait`, `--json`

---

### `rollout` — View/manage rollout status

Inspect and control Kubernetes Deployment rollouts via four subcommands.

```bash
k8s-tools rollout status  --deployment api-server
k8s-tools rollout history --deployment api-server --namespace production
k8s-tools rollout undo    --deployment api-server
k8s-tools rollout undo    --deployment api-server --revision 3
k8s-tools rollout restart --deployment worker --namespace staging
```

Options: `--deployment NAME`, `--namespace NS`, `--revision N` (undo only), `--json`

---

### `config` — Switch context/namespace

Inspect and switch kubectl contexts and namespaces without editing kubeconfig
manually.

```bash
k8s-tools config current
k8s-tools config contexts
k8s-tools config use-context --name prod-cluster
k8s-tools config namespaces
k8s-tools config use-namespace --name staging
```

Options: `--name NAME`, `--json`

---

## JSON Output (Pipe Protocol)

All commands support `--json` for structured output compatible with the Skill
Foundry pipe protocol:

```bash
k8s-tools pods --namespace production --json | some-other-tool
```

## Status Color Legend

| Color   | Status                                          |
|---------|-------------------------------------------------|
| Green   | Running                                         |
| Yellow  | Pending, ContainerCreating, Init:*              |
| Red     | CrashLoopBackOff, Error, OOMKilled, ImagePullBackOff |
| Magenta | Terminating, Unknown                            |
| Cyan    | Completed, Succeeded                            |

## License

MIT