kctl-claude 0.2.0__tar.gz

kctl_claude-0.2.0/.gitignore

@@ -0,0 +1,33 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Environment
+.env
+.env.local

kctl_claude-0.2.0/PKG-INFO

@@ -0,0 +1,17 @@
+Metadata-Version: 2.4
+Name: kctl-claude
+Version: 0.2.0
+Summary: Kodemeio Claude Code CLI — manage local and remote Claude Code environments
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: kctl-lib>=0.4.0
+Requires-Dist: pydantic>=2.10.0
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: rich>=13.9.0
+Requires-Dist: typer>=0.15.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.14.0; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.35.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'

kctl_claude-0.2.0/README.md

@@ -0,0 +1,88 @@
+# kctl-claude
+
+Kodemeio Claude Code CLI — manage local and remote Claude Code environments.
+
+## Installation
+
+```bash
+uv tool install .
+```
+
+## Quick Start
+
+```bash
+kctl-claude config init
+kctl-claude status
+kctl-claude doctor
+kctl-claude env list
+```
+
+## Command Groups
+
+| Group | Description |
+|-------|-------------|
+| `config` | Manage CLI configuration and profiles |
+| `api` | SDK REST API operations |
+| `backup` | Backup and restore Claude Code runtime |
+| `doctor` | Diagnostics and health checks |
+| `env` | Environment file management |
+| `setup` | Setup Claude Code on local, VPS, or Docker |
+| `status` | Status dashboard and health checks |
+| `sync` | Sync config between local `~/.claude` and repo |
+| `verify` | Verify Claude Code config completeness |
+
+Top-level commands: `completions`, `update`
+
+## Configuration
+
+Config lives in `~/.config/kodemeio/config.yaml` under the `claude` service key.
+
+```bash
+# Initialize a profile
+kctl-claude config init
+
+# Add a named profile
+kctl-claude config add work --url https://api.anthropic.com --api-key $ANTHROPIC_API_KEY
+
+# Switch active profile
+kctl-claude config use work
+
+# Show current profile (secrets masked)
+kctl-claude config show
+```
+
+## Global Options
+
+| Option | Short | Description |
+|--------|-------|-------------|
+| `--json` | | Output as JSON |
+| `--quiet` | `-q` | Suppress info messages |
+| `--verbose` | `-v` | Show debug output |
+| `--version` | `-V` | Show version and exit |
+
+## Shell Completions
+
+```bash
+# Generate completions (prints to stdout)
+kctl-claude completions zsh
+kctl-claude completions bash
+kctl-claude completions fish
+
+# Install completions automatically
+kctl-claude completions zsh --install
+kctl-claude completions bash --install
+```
+
+## Self-Update
+
+```bash
+kctl-claude update
+```
+
+## Development
+
+```bash
+uv run pytest tests/ -v
+uv run ruff check src/
+uv run mypy src/
+```

kctl_claude-0.2.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "kctl-claude"
+version = "0.2.0"
+description = "Kodemeio Claude Code CLI — manage local and remote Claude Code environments"
+requires-python = ">=3.12"
+dependencies = [
+    "kctl-lib>=0.4.0",
+    "typer>=0.15.0",
+    "rich>=13.9.0",
+    "pydantic>=2.10.0",
+    "pyyaml>=6.0.2",
+    "httpx>=0.28.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.3.0",
+    "pytest-httpx>=0.35.0",
+    "ruff>=0.9.0",
+    "mypy>=1.14.0",
+    "types-PyYAML>=6.0.0",
+]
+
+[project.scripts]
+kctl-claude = "kctl_claude.cli:_run"
+
+[tool.uv.sources]
+kctl-lib = { workspace = true }
+
+[project.entry-points."kctl_claude.plugins"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/kctl_claude"]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 120
+
+[tool.mypy]
+python_version = "3.12"
+strict = true

kctl_claude-0.2.0/skills/claude-admin/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: claude-admin
+description: >
+  Claude Code environment management via kctl-claude CLI (12 groups, ~33 commands).
+  MUST use for ANY kctl-claude operation.
+  Triggers on: "api", "backup", "check", "compare", "completions", "config", "current", "deploy", "diff", "docker", "doctor", "env", "generate", "health", "init", "kctl-claude", "local", "profile", "profiles", "pull", "push", "remove", "restore", "secrets", "setup", "skill", "status", "sync", "task", "test", "update", "updates", "validate", "verify".
+  Auto-generated: 2026-04-05
+  registry_hash: 7578bca2463c
+---
+
+# claude-admin — kctl-claude CLI Reference
+
+> Auto-generated from `kctl-claude` command registry. Do not edit manually.
+> To regenerate: `kctl-claude skill generate`
+> To add custom content: edit `SKILL.extra.md` in the same directory.
+
+## Overview
+
+**CLI:** `kctl-claude`
+**Command groups:** 12
+**Total commands:** ~33
+**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 |
+
+## Command Reference
+
+### `kctl-claude api`
+
+SDK REST API operations.
+
+| Command | Description |
+|---------|-------------|
+| `api health` | Check SDK API health. |
+| `api task <prompt> [--workspace] [--bare]` | Send a task to Claude Code via SDK API. |
+
+### `kctl-claude backup`
+
+Backup and restore Claude Code runtime.
+
+| Command | Description |
+|---------|-------------|
+| `backup create` | Backup container runtime volume. |
+| `backup restore <backup_dir>` | Restore runtime from backup. |
+
+### `kctl-claude completions`
+
+Generate or install shell completions.
+
+Usage: `kctl-claude completions [--shell] [--install]`
+
+### `kctl-claude config`
+
+Manage CLI configuration and profiles.
+
+| Command | Description |
+|---------|-------------|
+| `config add <name> [--config_dir] [--backup_dir] [--set_default]` | Add or update a profile's Claude configuration. |
+| `config current` | Show the active profile and its Claude configuration. |
+| `config init [--config_dir] [--backup_dir] [--name]` | Initialize CLI configuration (interactive if no flags given). |
+| `config profiles` | List all profiles. |
+| `config remove <name> [--force] [--service_only]` | Remove a profile or just its Claude config. |
+| `config set <key> <value> [--profile_arg]` | Set a configuration value for the current service. |
+| `config show` | Show full configuration. |
+| `config test` | Verify configuration is valid. |
+| `config use <name>` | Switch the default profile. |
+| `config validate` | Validate the current configuration. |
+
+**Examples:**
+```bash
+kctl-claude config set config_dir /path/to/dir
+kctl-claude config set backup_dir /path/to/backups
+kctl-claude config set default_profile work
+```
+
+### `kctl-claude doctor`
+
+Diagnostics and health checks.
+
+### `kctl-claude env`
+
+Environment file management.
+
+| Command | Description |
+|---------|-------------|
+| `env check` | Validate .env file. |
+| `env deploy` | Deploy .env to Hetzner server. |
+| `env generate` | Interactive .env generator. |
+
+### `kctl-claude setup`
+
+Setup Claude Code on local, VPS, or Docker.
+
+| Command | Description |
+|---------|-------------|
+| `setup compare` | Compare setup modes side-by-side. |
+| `setup docker` | Show Docker deployment commands. |
+| `setup init` | Run session initialization (git, SSH, tmux, kctl tools). |
+| `setup local` | Setup local development environment (laptop). |
+| `setup vps [--check] [--skip_repos]` | Setup VPS/bare-metal server (requires sudo). |
+
+### `kctl-claude skill`
+
+Claude Code skill management.
+
+| Command | Description |
+|---------|-------------|
+| `skill generate [--output] [--install] [--check]` | Auto-generate SKILL.md from CLI command registry. |
+
+**Examples:**
+```bash
+kctl-claude skill generate
+kctl-claude skill generate --install
+kctl-claude skill generate --check
+```
+
+### `kctl-claude status`
+
+Status dashboard and health checks.
+
+| Command | Description |
+|---------|-------------|
+| `status health` | Quick health check (exit code 0=ok, 1=issues). |
+| `status updates` | Check for Claude Code updates and show changelog link. |
+
+### `kctl-claude sync`
+
+Sync config between local ~/.claude and repo.
+
+| Command | Description |
+|---------|-------------|
+| `sync diff` | Preview what push would change (dry-run). |
+| `sync pull` | Sync repo config -> local (update local environment). |
+| `sync push` | Sync local config -> repo (for Docker deployment). |
+| `sync secrets` | Deploy kctl credentials to Hetzner. |
+
+### `kctl-claude update`
+
+Check for updates and upgrade kctl-claude.
+
+### `kctl-claude verify`
+
+Verify Claude Code config completeness.
+
+## Configuration
+
+Shared config: `~/.config/kodemeio/config.yaml`
+
+```bash
+kctl-claude config init       # Interactive setup
+kctl-claude config show       # Show current config
+kctl-claude config profiles   # List profiles
+kctl-claude config current    # Show active profile
+kctl-claude config validate   # Verify config
+```

kctl_claude-0.2.0/src/kctl_claude/__init__.py

@@ -0,0 +1,3 @@
+"""kctl-claude — Kodemeio Claude Code CLI."""
+
+__version__ = "0.2.0"

kctl_claude-0.2.0/src/kctl_claude/__main__.py

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

kctl_claude-0.2.0/src/kctl_claude/cli.py

@@ -0,0 +1,137 @@
+"""Main CLI entry point for kctl-claude."""
+
+from __future__ import annotations
+
+
+import sys
+from typing import Annotated
+
+import typer
+
+from kctl_claude import __version__
+from kctl_claude.commands.api_cmd import app as api_app
+from kctl_claude.commands.backup_cmd import app as backup_app
+from kctl_claude.commands.config_cmd import app as config_app
+from kctl_claude.commands.doctor_cmd import app as doctor_app
+from kctl_claude.commands.env_cmd import app as env_app
+from kctl_claude.commands.setup_cmd import app as setup_app
+from kctl_claude.commands.status_cmd import app as status_app
+from kctl_claude.commands.sync_cmd import app as sync_app
+from kctl_claude.commands.verify_cmd import app as verify_app
+from kctl_claude.core.callbacks import AppContext
+from kctl_claude.core.plugins import ENTRY_POINT_GROUP, discover_and_load_plugins
+from kctl_claude.commands.skill_cmd import app as skill_app
+from kctl_lib.self_update import notify_if_outdated
+
+app = typer.Typer(
+    name="kctl-claude",
+    help="Kodemeio Claude Code CLI — manage local and remote Claude Code environments.",
+    invoke_without_command=True,
+    rich_markup_mode="rich",
+    pretty_exceptions_enable=False,
+)
+
+# Register command groups
+app.add_typer(config_app, name="config")
+app.add_typer(status_app, name="status")
+app.add_typer(sync_app, name="sync")
+app.add_typer(verify_app, name="verify")
+app.add_typer(api_app, name="api")
+app.add_typer(env_app, name="env")
+app.add_typer(backup_app, name="backup")
+app.add_typer(setup_app, name="setup")
+app.add_typer(doctor_app, name="doctor")
+app.add_typer(skill_app, name="skill", hidden=True)
+
+# Discover and load plugins
+discover_and_load_plugins(app, ENTRY_POINT_GROUP)
+
+
+@app.callback()
+def main(
+    ctx: typer.Context,
+    json_output: Annotated[bool, typer.Option("--json", help="JSON output")] = False,
+    quiet: Annotated[bool, typer.Option("--quiet", "-q", help="Suppress info messages")] = False,
+    verbose: Annotated[bool, typer.Option("--verbose", "-v", help="Show debug output")] = False,
+    version: Annotated[bool, typer.Option("--version", "-V", help="Show version")] = False,
+) -> None:
+    """Global options applied to all commands."""
+    if version:
+        typer.echo(f"kctl-claude {__version__}")
+        raise typer.Exit()
+
+    ctx.ensure_object(dict)
+    ctx.obj = AppContext(json_mode=json_output, quiet=quiet, verbose=verbose)
+    notify_if_outdated(ctx.obj.output, "kctl-claude", __version__)
+
+    # Record command in history (non-blocking, best-effort)
+    try:
+        from kctl_lib.history import HistoryStore
+
+        store = HistoryStore("kctl-claude")
+        store.ensure_schema(
+            [
+                """CREATE TABLE IF NOT EXISTS commands (
+                    id INTEGER PRIMARY KEY AUTOINCREMENT,
+                    command TEXT NOT NULL,
+                    timestamp TEXT NOT NULL
+                )"""
+            ]
+        )
+        store.record(table="commands", command=" ".join(sys.argv[1:]))
+    except Exception:
+        pass  # History recording is best-effort
+
+    # If no subcommand, show help
+    if ctx.invoked_subcommand is None and not version:
+        typer.echo(ctx.get_help())
+        raise typer.Exit()
+
+
+@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-claude", 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-claude", shell)
+        typer.echo(script)
+
+
+@app.command("update")
+def update_cmd(ctx: typer.Context) -> None:
+    """Check for updates and upgrade kctl-claude."""
+    actx: AppContext = 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-claude", __version__)
+    if latest:
+        out.info(f"Updating to {latest}...")
+        do_update("kctl-claude")
+        out.success(f"Updated to {latest}")
+    else:
+        out.success("Already up to date")
+
+
+def _run() -> None:
+    """Entry point with error handling."""
+    try:
+        app()
+    except KeyboardInterrupt:
+        sys.exit(130)
+    except Exception as e:
+        typer.echo(f"Error: {e}", err=True)
+        sys.exit(1)

kctl_claude-0.2.0/src/kctl_claude/commands/api_cmd.py

@@ -0,0 +1,97 @@
+"""kctl-claude api — interact with the SDK REST API."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import httpx
+import typer
+
+from kctl_claude.core.callbacks import AppContext
+
+app = typer.Typer(help="SDK REST API operations.")
+
+DEFAULT_URL = "http://localhost:3100"
+
+
+def _base_url() -> str:
+    import os
+
+    return os.environ.get("SDK_BASE_URL", DEFAULT_URL)
+
+
+def _api_key() -> str:
+    import os
+
+    return os.environ.get("SDK_API_KEY", "")
+
+
+@app.command()
+def health(ctx: typer.Context) -> None:
+    """Check SDK API health."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+    try:
+        resp = httpx.get(f"{_base_url()}/health", timeout=5)
+        try:
+            data = resp.json()
+        except Exception:
+            data = {}
+        if actx.json_mode:
+            out.raw_json(data)
+        else:
+            out.success(f"Status: {data.get('status', 'unknown')}")
+            out.success(f"Tasks: {data.get('inFlight', 0)}/{data.get('maxConcurrent', 3)} in flight")
+    except (httpx.ConnectError, httpx.TimeoutException) as e:
+        out.error(f"SDK API unreachable: {e}")
+        raise typer.Exit(code=1) from None
+
+
+@app.command()
+def task(
+    ctx: typer.Context,
+    prompt: Annotated[str, typer.Argument(help="Task prompt for Claude Code")],
+    workspace: Annotated[str, typer.Option("--workspace", "-w", help="Workspace name")] = "",
+    bare: Annotated[bool, typer.Option("--bare", help="Skip auto-discovery")] = False,
+) -> None:
+    """Send a task to Claude Code via SDK API."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    # Validate workspace path to prevent traversal attacks
+    if workspace and (".." in workspace or workspace.startswith("/")):
+        out.error("Invalid workspace path")
+        raise typer.Exit(code=1)
+
+    headers = {"Content-Type": "application/json"}
+    key = _api_key()
+    if key:
+        headers["Authorization"] = f"Bearer {key}"
+
+    body: dict = {"prompt": prompt}
+    if workspace:
+        body["workspace"] = workspace
+    if bare:
+        body["bare"] = True
+
+    try:
+        resp = httpx.post(f"{_base_url()}/task", json=body, headers=headers, timeout=310)
+        try:
+            data = resp.json()
+        except Exception:
+            data = {}
+        if actx.json_mode:
+            out.raw_json(data)
+        else:
+            if resp.status_code == 200:
+                out.success("Task completed")
+                out.text(data.get("result", str(data)))
+            else:
+                out.error(f"Error {resp.status_code}: {data.get('error', str(data))}")
+                raise typer.Exit(code=1)
+    except httpx.TimeoutException:
+        out.error("Task timed out (310s)")
+        raise typer.Exit(code=1) from None
+    except httpx.ConnectError as e:
+        out.error(f"SDK API unreachable: {e}")
+        raise typer.Exit(code=1) from None

kctl_claude-0.2.0/src/kctl_claude/commands/backup_cmd.py

@@ -0,0 +1,53 @@
+"""kctl-claude backup — runtime volume backup/restore."""
+
+from __future__ import annotations
+
+import subprocess
+from typing import Annotated
+
+import typer
+from kctl_lib.exceptions import CommandError
+
+from kctl_claude.core.callbacks import AppContext
+from kctl_claude.core.runner import run_script
+
+app = typer.Typer(help="Backup and restore Claude Code runtime.")
+
+
+@app.command("create")
+def create_backup(ctx: typer.Context) -> None:
+    """Backup container runtime volume."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+    repo = actx.repo_dir
+    if not repo:
+        out.error("Repo not found.")
+        raise typer.Exit(code=1)
+    script = repo / "scripts" / "backup-runtime.sh"
+    try:
+        run_script(script, capture=False)
+        out.success("Backup created")
+    except CommandError as e:
+        out.error(f"Backup failed (exit {e.returncode}): {e.stderr}")
+        raise typer.Exit(code=1) from None
+
+
+@app.command()
+def restore(
+    ctx: typer.Context,
+    backup_dir: Annotated[str, typer.Argument(help="Path to backup directory")],
+) -> None:
+    """Restore runtime from backup."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+    out.info(f"Restoring from {backup_dir}...")
+    result = subprocess.run(
+        ["docker", "cp", f"{backup_dir}/.", "kodemeio-claude:/home/dev/.claude/"],
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode == 0:
+        out.success("Restore complete")
+    else:
+        out.error(f"Restore failed (exit {result.returncode}): {result.stderr.strip()}")
+        raise typer.Exit(code=1)