kctl-redis 0.8.4__tar.gz

kctl_redis-0.8.4/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+.venv/
+*.egg-info/
+dist/
+build/
+uv.lock

kctl_redis-0.8.4/PKG-INFO

@@ -0,0 +1,19 @@
+Metadata-Version: 2.4
+Name: kctl-redis
+Version: 0.8.4
+Summary: Kodemeio Redis CLI — manage Redis servers via SSH tunnel
+Requires-Python: >=3.12
+Requires-Dist: kctl-lib>=0.12.0
+Requires-Dist: paramiko<4.0.0,>=3.4.0
+Requires-Dist: pydantic>=2.10.0
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: redis[hiredis]>=5.0.0
+Requires-Dist: rich>=13.9.0
+Requires-Dist: sshtunnel>=0.4.0
+Requires-Dist: typer>=0.15.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.14.0; extra == 'dev'
+Requires-Dist: pytest>=8.3.0; extra == 'dev'
+Requires-Dist: ruff>=0.9.0; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0.0; extra == 'dev'
+Requires-Dist: types-redis>=4.6.0; extra == 'dev'

kctl_redis-0.8.4/README.md

@@ -0,0 +1,123 @@
+# kctl-redis
+
+Kodemeio Redis CLI — manage Redis servers via SSH tunnel.
+
+## Installation
+
+```bash
+uv tool install kctl-redis
+# or within the workspace
+uv sync --all-packages
+```
+
+## Quick Start
+
+```bash
+# Initialize a profile
+kctl-redis config init --profile production
+
+# Test the connection
+kctl-redis config validate
+
+# Check health
+kctl-redis health ping
+
+# Live dashboard
+kctl-redis dashboard overview
+
+# Scan keys
+kctl-redis keys scan --pattern "session:*"
+
+# Run a raw command
+kctl-redis query run GET mykey
+```
+
+## Command Groups
+
+| Group | Description | Commands |
+|-------|-------------|----------|
+| `config` | Profile management (init, add, use, show, validate, remove, set, profiles, current) | 9 |
+| `health` | Ping, latency check, info summary | 3 |
+| `dashboard` | Live server overview | 1 |
+| `query` | Execute raw Redis commands | 1 |
+| `keys` | Scan, get, set, delete, TTL, type, rename | 7 |
+| `db` | List databases, flush, select, move keys | 4 |
+| `memory` | Memory stats, usage by key, doctor, purge | 4 |
+| `clients` | List clients, kill, info | 3 |
+| `server` | Get/set config, save config, reset stats | 4 |
+| `persistence` | RDB status, AOF status, BGSAVE, BGREWRITEAOF | 4 |
+| `replication` | Replication info, promote replica, reset | 3 |
+| `pubsub` | List channels, subscribers, numsub | 3 |
+| `streams` | Stream info, read, trim, delete, groups | 5 |
+| `performance` | Slow log, latency history, command stats, monitor | 4 |
+| `backup` | Dump RDB via SSH, restore, list backups | 3 |
+| `maintenance` | Memory purge, defrag check, flush expired | 3 |
+
+**Total: 61 commands**
+
+## Global Options
+
+```
+--json              Output as JSON
+--quiet / -q        Suppress info messages
+--profile / -p      Config profile name
+--host / -H         Redis host override
+--port              Redis port override
+--user / -U         Redis username override
+--password          Redis password override
+--db                Redis database number override
+--version / -V      Show version
+```
+
+## Configuration
+
+Config is stored in `~/.config/kodemeio/config.yaml` under the `redis` service key.
+
+```yaml
+profiles:
+  production:
+    redis:
+      host: 10.0.0.5          # Redis host (internal, accessed via SSH tunnel)
+      port: 6379
+      username: default
+      password: ${REDIS_PASSWORD}
+      db: 0
+      ssh_host: 49.13.14.79   # Jump host IP
+      ssh_port: 22
+      ssh_user: root
+      ssh_key: ~/.ssh/id_ed25519
+```
+
+### Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `KCTL_REDIS_HOST` | Redis host |
+| `KCTL_REDIS_PORT` | Redis port |
+| `KCTL_REDIS_USERNAME` | Redis username |
+| `KCTL_REDIS_PASSWORD` | Redis password |
+| `KCTL_REDIS_SSH_HOST` | SSH tunnel host |
+| `KCTL_REDIS_DB` | Redis database number |
+| `REDIS_HOST` / `REDIS_PORT` | Standard Redis env vars (lower priority) |
+
+Resolution order (highest to lowest): CLI flags > `KCTL_REDIS_*` env vars > `REDIS_*` env vars > config file profile.
+
+### Profile Management
+
+```bash
+kctl-redis config init --profile production
+kctl-redis config add --profile staging --host 10.0.0.6 --ssh-host 1.2.3.4
+kctl-redis config use production
+kctl-redis config show
+kctl-redis config profiles
+```
+
+## Development
+
+```bash
+cd packages/kctl-redis
+uv sync --all-extras
+uv run pytest tests/ -v
+uv run ruff check src/
+uv run mypy src/
+```

kctl_redis-0.8.4/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "kctl-redis"
+version = "0.8.4"
+description = "Kodemeio Redis CLI — manage Redis servers via SSH tunnel"
+requires-python = ">=3.12"
+dependencies = [
+    "kctl-lib>=0.12.0",
+    "typer>=0.15.0",
+    "rich>=13.9.0",
+    "pydantic>=2.10.0",
+    "pyyaml>=6.0.2",
+    "redis[hiredis]>=5.0.0",
+    "sshtunnel>=0.4.0",
+    "paramiko>=3.4.0,<4.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.3.0",
+    "ruff>=0.9.0",
+    "mypy>=1.14.0",
+    "types-PyYAML>=6.0.0",
+    "types-redis>=4.6.0",
+]
+
+[project.scripts]
+kctl-redis = "kctl_redis.cli:_run"
+
+[tool.uv.sources]
+kctl-lib = { workspace = true }
+
+[project.entry-points."kctl_redis.plugins"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/kctl_redis"]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 120
+
+[tool.mypy]
+python_version = "3.12"
+strict = true

kctl_redis-0.8.4/skills/redis-admin/SKILL.md

@@ -0,0 +1,289 @@
+---
+name: redis-admin
+description: >
+  Redis server administration via kctl-redis CLI (22 groups, ~68 commands). MUST use for ANY kctl-redis operation. See SKILL.md ## Triggers for keywords.
+  Auto-generated: 2026-05-22
+  registry_hash: f7369f6882a2
+---
+
+# redis-admin — kctl-redis CLI Reference
+
+> Auto-generated from `kctl-redis` command registry. Do not edit manually.
+> To regenerate: `kctl-redis skill generate`
+> To add custom content: edit `SKILL.extra.md` in the same directory.
+
+## Overview
+
+**CLI:** `kctl-redis`
+**Command groups:** 22
+**Total commands:** ~68
+**Install:** `cd cli && uv tool install --editable .`
+
+## Global Options
+
+| Flag | Description |
+|------|-------------|
+| `--json` | JSON output |
+| `--quiet`, `-q` | Suppress info messages |
+| `--format`, `-f` | Output format: pretty/json/csv/yaml |
+| `--no-header` | Omit CSV header row |
+| `--profile`, `-p` | Config profile name |
+| `--version`, `-V` | Show version |
+
+## Quick Discovery (for AI agents)
+
+**DO NOT GUESS command paths or flag names.** Before invoking `kctl-redis <group> <verb> ...`, use these AI-facing affordances:
+
+1. **Find a command by keyword** — substring filter, returns sorted leaf paths:
+   ```bash
+   kctl-redis commands list --filter <keyword>
+   ```
+   Example: `kctl-redis commands list --filter database` → all database-related commands in one call.
+
+2. **Inspect flags before invoking** — full param schema with
+   opts/defaults/required/choices/help:
+   ```bash
+   kctl-redis commands tree --json | jq '.. | objects | select(.name == "<verb>") | .params'
+   ```
+   Reading the `params` array tells you exact flag names (`--lang`), short aliases (`-l`), defaults, required-vs-optional, and choices — eliminating the `No such option '--xxx'` failure mode.
+
+3. **Preview destructive operations without executing** — `--explain` is supported on selected write commands:
+   ```bash
+   kctl-redis <group> <verb> <args> --explain
+   ```
+   Prints the planned action and exits 0. If `--explain` errors with "no such option", that command does not support it — fall back to verifying via `commands tree` schema inspection before running for real.
+
+4. **Errors are user-facing one-liners**, not Python tracebacks. A failed invocation shows `❌ <ErrorClass>: <message>` on stderr (or `{"error": ..., "message": ...}` JSON if `--json` was passed). Read the message — it usually tells you exactly what's missing.
+
+## Triggers
+
+Auto-invoke this skill when the user references any of these keywords:
+
+"aof-status", "backup", "bgrewriteaof", "bgsave", "big-keys", "channels", "check", "clients", "commands", "completions", "config", "config-get", "config-rewrite", "config-set", "consumers", "current", "dashboard", "db", "defrag", "doctor", "dump", "eviction", "exec", "flush", "fragmentation", "generate", "groups", "health", "hit-ratio", "info", "init", "kctl-redis", "keys", "kill", "latency", "maintenance", "memory", "memory-purge", "memory-usage", "monitor", "numsub", "ops-sec", "pending", "performance", "persistence", "ping", "profile", "profiles", "promote", "publish", "pubsub", "query", "rdb-status", "remove", "rename", "replication", "restore", "scan", "self-update", "server", "size", "skill", "slowlog", "stats", "streams", "swap", "test", "tree", "trim", "tui", "type"
+
+## Command Reference
+
+### `kctl-redis backup`
+
+Redis backup operations via SSH.
+
+| Command | Description |
+|---------|-------------|
+| `backup dump [--output_path]` | Trigger BGSAVE and download the RDB file. |
+| `backup list [--remote_dir]` | List backup files on the remote server. |
+| `backup restore <file_path>` | Upload an RDB file to the server. |
+
+### `kctl-redis clients`
+
+Redis client management.
+
+| Command | Description |
+|---------|-------------|
+| `clients info` | Show client connection info. |
+| `clients kill <client_id>` | Kill a client connection by ID. |
+| `clients list` | List connected clients. |
+
+### `kctl-redis commands`
+
+Machine-readable command discovery (for AI agents).
+
+| Command | Description |
+|---------|-------------|
+| `commands list [--json_flag] [--filter_substr]` | List all leaf commands as 'group verb' strings. |
+| `commands tree [--json_flag]` | Dump the full command tree as JSON. |
+
+### `kctl-redis completions`
+
+Generate or install shell completions.
+
+Usage: `kctl-redis completions [--shell] [--install]`
+
+### `kctl-redis config`
+
+Manage kctl-redis configuration profiles.
+
+| Command | Description |
+|---------|-------------|
+| `config add <profile> [--host] [--port] [--username] [--password] [--db] [--ssh_host] [--ssh_port] [--ssh_user] [--ssh_key]` | Add or update a profile. |
+| `config current` | Show the active profile name. |
+| `config init [--profile] [--host] [--port] [--username] [--password] [--db] [--ssh_host] [--ssh_port] [--ssh_user] [--ssh_key]` | Initialize kctl-redis configuration. |
+| `config profiles` | List all profiles. |
+| `config remove <profile> [--force]` | Remove a profile. |
+| `config set <key> <value>` | Set a configuration value. |
+| `config show` | Show current configuration (passwords masked). |
+| `config test` | Test Redis connection. |
+| `config use <profile>` | Switch the default profile. |
+
+### `kctl-redis dashboard`
+
+Redis system overview.
+
+### `kctl-redis db`
+
+Redis database operations.
+
+| Command | Description |
+|---------|-------------|
+| `db flush [--force] [--async_mode]` | Flush current database (delete all keys). |
+| `db list` | List databases with key counts. |
+| `db size` | Show key count for current database. |
+| `db swap <db1> <db2>` | Swap two databases. |
+
+### `kctl-redis doctor`
+
+Run diagnostic checks.
+
+### `kctl-redis health`
+
+Redis health checks.
+
+| Command | Description |
+|---------|-------------|
+| `health check [--memory_warn] [--memory_crit] [--clients_warn]` | Run health threshold checks. |
+| `health info` | Show Redis server info summary. |
+| `health ping` | Ping Redis and measure latency. |
+
+### `kctl-redis keys`
+
+Redis key management.
+
+| Command | Description |
+|---------|-------------|
+| `keys delete <key> [--force]` | Delete a key. |
+| `keys get <key>` | Get value of a key (auto-detects type). |
+| `keys memory-usage <key>` | Show memory usage of a key. |
+| `keys rename <old_key> <new_key>` | Rename a key. |
+| `keys scan [--pattern] [--count] [--key_type] [--limit]` | Scan keys matching a pattern. |
+| `keys ttl <key> [--precise]` | Show time-to-live for a key. |
+| `keys type <key>` | Show key type and encoding. |
+
+### `kctl-redis maintenance`
+
+Redis maintenance operations.
+
+| Command | Description |
+|---------|-------------|
+| `maintenance config-rewrite` | Persist runtime configuration to redis.conf. |
+| `maintenance defrag` | Check and enable active defragmentation. |
+| `maintenance memory-purge` | Release memory back to the OS. |
+
+### `kctl-redis memory`
+
+Redis memory analysis.
+
+| Command | Description |
+|---------|-------------|
+| `memory big-keys [--count] [--limit]` | Find largest keys by memory usage. |
+| `memory eviction` | Show eviction policy and stats. |
+| `memory fragmentation` | Show memory fragmentation and recommendation. |
+| `memory stats` | Show memory statistics. |
+
+### `kctl-redis performance`
+
+Redis performance monitoring.
+
+| Command | Description |
+|---------|-------------|
+| `performance hit-ratio` | Show keyspace hit ratio. |
+| `performance latency` | Show latency monitoring data. |
+| `performance ops-sec` | Show current operations per second. |
+| `performance slowlog [--count]` | Show slow log entries. |
+
+### `kctl-redis persistence`
+
+Redis persistence management.
+
+| Command | Description |
+|---------|-------------|
+| `persistence aof-status` | Show AOF persistence status. |
+| `persistence bgrewriteaof` | Trigger AOF rewrite. |
+| `persistence bgsave` | Trigger a background RDB save. |
+| `persistence rdb-status` | Show RDB persistence status. |
+
+### `kctl-redis pubsub`
+
+Redis Pub/Sub operations.
+
+| Command | Description |
+|---------|-------------|
+| `pubsub channels [--pattern]` | List active Pub/Sub channels. |
+| `pubsub numsub <channel_names>` | Show subscriber counts for channels. |
+| `pubsub publish <channel> <message>` | Publish a message to a channel. |
+
+### `kctl-redis query`
+
+Execute raw Redis commands.
+
+| Command | Description |
+|---------|-------------|
+| `query exec <command>` | Execute a raw Redis command. |
+
+### `kctl-redis replication`
+
+Redis replication management.
+
+| Command | Description |
+|---------|-------------|
+| `replication info` | Show replication info. |
+| `replication lag` | Show replication lag for replicas. |
+| `replication promote` | Promote this replica to master (REPLICAOF NO ONE). |
+
+### `kctl-redis self-update`
+
+Check for updates and upgrade kctl-redis.
+
+### `kctl-redis server`
+
+Redis server management.
+
+| Command | Description |
+|---------|-------------|
+| `server acl [--user]` | List ACL users or show user details. |
+| `server config-get [--pattern]` | Get Redis configuration parameters. |
+| `server config-set <parameter> <value>` | Set a Redis configuration parameter at runtime. |
+| `server info [--section]` | Show Redis INFO output. |
+
+### `kctl-redis skill`
+
+Claude Code skill management.
+
+| Command | Description |
+|---------|-------------|
+| `skill generate [--output] [--install] [--check]` | Auto-generate SKILL.md from CLI command registry. |
+
+**Examples:**
+```bash
+kctl-redis skill generate
+kctl-redis skill generate --install
+kctl-redis skill generate --check
+```
+
+### `kctl-redis streams`
+
+Redis Streams operations.
+
+| Command | Description |
+|---------|-------------|
+| `streams consumers <key> <group>` | Show consumers in a group. |
+| `streams groups <key>` | Show consumer groups for a stream. |
+| `streams info <key>` | Show stream information. |
+| `streams pending <key> <group> [--count]` | Show pending messages for a consumer group. |
+| `streams trim <key> [--maxlen] [--minid] [--approximate]` | Trim a stream. |
+
+### `kctl-redis tui`
+
+Launch the interactive TUI.
+
+Usage: `kctl-redis tui [--profile]`
+
+## Configuration
+
+Shared config: `~/.config/kodemeio/config.yaml`
+
+```bash
+kctl-redis config init       # Interactive setup
+kctl-redis config show       # Show current config
+kctl-redis config profiles   # List profiles
+kctl-redis config current    # Show active profile
+kctl-redis config validate   # Verify config
+```

kctl_redis-0.8.4/src/kctl_redis/__init__.py

@@ -0,0 +1,3 @@
+"""Kodemeio Redis CLI."""
+
+__version__ = "0.8.4"

kctl_redis-0.8.4/src/kctl_redis/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as: python -m kctl_redis."""
+
+from kctl_redis.cli import _run
+
+_run()

kctl_redis-0.8.4/src/kctl_redis/cli.py

@@ -0,0 +1,154 @@
+"""Main CLI entry point for kctl-redis."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+from kctl_lib import handle_cli_error
+from kctl_lib import cli_entrypoint, register_introspection_commands
+
+from kctl_redis import __version__
+from kctl_redis.commands.backup import app as backup_app
+from kctl_redis.commands.clients import app as clients_app
+from kctl_redis.commands.config_cmd import app as config_app
+from kctl_redis.commands.dashboard import app as dashboard_app
+from kctl_redis.commands.db import app as db_app
+from kctl_redis.commands.health import app as health_app
+from kctl_redis.commands.keys import app as keys_app
+from kctl_redis.commands.maintenance import app as maintenance_app
+from kctl_redis.commands.memory import app as memory_app
+from kctl_redis.commands.performance import app as performance_app
+from kctl_redis.commands.persistence import app as persistence_app
+from kctl_redis.commands.pubsub import app as pubsub_app
+from kctl_redis.commands.query import app as query_app
+from kctl_redis.commands.replication import app as replication_app
+from kctl_redis.commands.server import app as server_app
+from kctl_redis.commands.streams import app as streams_app
+from kctl_redis.commands.skill_cmd import app as skill_app
+from kctl_redis.commands.doctor_cmd import app as doctor_app
+from kctl_redis.core.callbacks import AppContext
+from kctl_redis.core.exceptions import KctlError
+from kctl_lib.self_update import notify_if_outdated
+from kctl_lib.tui import add_tui_command
+
+
+def version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"kctl-redis {__version__}")
+        raise typer.Exit()
+
+
+app = typer.Typer(
+    name="kctl-redis",
+    help="Kodemeio Redis CLI - manage Redis servers via SSH tunnel.",
+    no_args_is_help=True,
+    rich_markup_mode="rich",
+    pretty_exceptions_enable=False,
+)
+
+
+@app.callback()
+def main(
+    ctx: typer.Context,
+    json_output: Annotated[bool, typer.Option("--json", help="Output as JSON")] = False,
+    quiet: Annotated[bool, typer.Option("--quiet", "-q", help="Suppress info messages")] = False,
+    profile: Annotated[str | None, typer.Option("--profile", "-p", help="Config profile name")] = None,
+    host: Annotated[str | None, typer.Option("--host", "-H", help="Redis host override")] = None,
+    port: Annotated[int | None, typer.Option("--port", help="Redis port override")] = None,
+    user: Annotated[str | None, typer.Option("--user", "-U", help="Redis username override")] = None,
+    password: Annotated[str | None, typer.Option("--password", help="Redis password override")] = None,
+    db: Annotated[int | None, typer.Option("--db", help="Redis database number override")] = None,
+    version: Annotated[
+        bool, typer.Option("--version", "-V", callback=version_callback, is_eager=True, help="Show version")
+    ] = False,
+) -> None:
+    """Kodemeio Redis CLI."""
+    ctx.ensure_object(dict)
+    ctx.obj = AppContext(
+        json_mode=json_output,
+        quiet=quiet,
+        profile=profile,
+        host_override=host,
+        port_override=port,
+        user_override=user,
+        password_override=password,
+        db_override=db,
+    )
+    notify_if_outdated(ctx.obj.output, "kctl-redis", __version__)
+
+
+# Register all command groups
+app.add_typer(config_app, name="config")
+app.add_typer(health_app, name="health")
+app.add_typer(dashboard_app, name="dashboard")
+app.add_typer(query_app, name="query")
+app.add_typer(keys_app, name="keys")
+app.add_typer(db_app, name="db")
+app.add_typer(memory_app, name="memory")
+app.add_typer(clients_app, name="clients")
+app.add_typer(server_app, name="server")
+app.add_typer(persistence_app, name="persistence")
+app.add_typer(replication_app, name="replication")
+app.add_typer(pubsub_app, name="pubsub")
+app.add_typer(streams_app, name="streams")
+app.add_typer(performance_app, name="performance")
+app.add_typer(backup_app, name="backup")
+app.add_typer(maintenance_app, name="maintenance")
+app.add_typer(skill_app, name="skill", hidden=True)
+app.add_typer(doctor_app, name="doctor")
+add_tui_command(app, service_key="redis", version=__version__)
+
+
+@app.command("self-update")
+def self_update_cmd(ctx: typer.Context) -> None:
+    """Check for updates and upgrade kctl-redis."""
+    actx = ctx.obj
+    out = actx.output
+
+    from kctl_lib.self_update import check_update
+    from kctl_lib.self_update import update as do_update
+
+    latest = check_update("kctl-redis", __version__)
+    if latest:
+        out.info(f"Updating to {latest}...")
+        do_update("kctl-redis")
+        out.success(f"Updated to {latest}")
+    else:
+        out.success("Already up to date")
+
+
+@app.command()
+def completions(
+    shell: Annotated[str, typer.Argument(help="Shell type: zsh, bash, fish")] = "zsh",
+    install: Annotated[bool, typer.Option("--install", help="Install completions")] = False,
+) -> None:
+    """Generate or install shell completions."""
+    from kctl_lib.completions import get_completion_script, install_completions
+
+    if install:
+        path = install_completions("kctl-redis", shell)
+        if path:
+            typer.echo(f"Completions installed to {path}")
+        else:
+            typer.echo(f"Could not install completions for {shell}", err=True)
+            raise typer.Exit(code=1)
+    else:
+        script = get_completion_script("kctl-redis", shell)
+        typer.echo(script)
+
+
+# Wrap app so KctlError subclasses surface as clean user-facing messages.
+app = cli_entrypoint(app)
+register_introspection_commands(app)
+
+def _run() -> None:
+    """Entry point with error handling."""
+    try:
+        app()
+    except KctlError as e:
+        handle_cli_error(e)
+
+
+if __name__ == "__main__":
+    _run()