kctl-waha 0.8.4__tar.gz

kctl_waha-0.8.4/.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_waha-0.8.4/PKG-INFO

@@ -0,0 +1,17 @@
+Metadata-Version: 2.4
+Name: kctl-waha
+Version: 0.8.4
+Summary: Kodemeio WAHA CLI — manage WhatsApp HTTP API instances
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: kctl-lib>=0.12.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_waha-0.8.4/README.md

@@ -0,0 +1,70 @@
+# kctl-waha
+
+Kodemeio WAHA CLI — manage WhatsApp HTTP API sessions and messaging.
+
+## Installation
+
+```bash
+uv tool install .
+```
+
+## Quick Start
+
+```bash
+kctl-waha config init
+kctl-waha health
+kctl-waha dashboard
+kctl-waha sessions list
+```
+
+## Command Groups
+
+| Group | Description |
+|-------|-------------|
+| `config` | Manage CLI configuration and profiles |
+| `health` | Health checks and diagnostics |
+| `dashboard` | System overview dashboard |
+| `sessions` | Manage WhatsApp sessions |
+| `messages` | Send WhatsApp messages |
+| `webhooks` | Manage session webhooks |
+| `bridge` | Manage WAHA bridge sidecar (Chatwoot/Odoo) |
+
+## Global Options
+
+| Option | Short | Description |
+|--------|-------|-------------|
+| `--json` | | Output as JSON |
+| `--quiet` | `-q` | Suppress info messages |
+| `--profile` | `-p` | Config profile name |
+| `--url` | | API URL override |
+| `--api-key` | | API key override |
+| `--bridge-url` | | Bridge URL override |
+| `--version` | `-V` | Show version and exit |
+
+## Configuration
+
+Config lives in `~/.config/kodemeio/config.yaml` under the `waha` service key.
+
+```bash
+# Initialize default profile
+kctl-waha config init
+
+# Add a named profile
+kctl-waha config add prod \
+  --url https://waha.example.com \
+  --api-key $WAHA_API_KEY
+
+# Switch active profile
+kctl-waha config use prod
+
+# Show current profile (key masked)
+kctl-waha config show
+```
+
+## Development
+
+```bash
+uv run pytest tests/ -v
+uv run ruff check src/
+uv run mypy src/
+```

kctl_waha-0.8.4/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "kctl-waha"
+version = "0.8.4"
+description = "Kodemeio WAHA CLI — manage WhatsApp HTTP API instances"
+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",
+    "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-waha = "kctl_waha.cli:_run"
+
+[tool.uv.sources]
+kctl-lib = { workspace = true }
+
+[project.entry-points."kctl_waha.plugins"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/kctl_waha"]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 120
+
+[tool.mypy]
+python_version = "3.12"
+strict = true

kctl_waha-0.8.4/skills/waha-admin/SKILL.md

@@ -0,0 +1,213 @@
+---
+name: waha-admin
+description: >
+  WAHA WhatsApp HTTP API administration via kctl-waha CLI (13 groups, ~36 commands). MUST use for ANY kctl-waha operation. See SKILL.md ## Triggers for keywords.
+  Auto-generated: 2026-05-22
+  registry_hash: df5921b2fc0d
+---
+
+# waha-admin — kctl-waha CLI Reference
+
+> Auto-generated from `kctl-waha` command registry. Do not edit manually.
+> To regenerate: `kctl-waha skill generate`
+> To add custom content: edit `SKILL.extra.md` in the same directory.
+
+## Overview
+
+**CLI:** `kctl-waha`
+**Command groups:** 13
+**Total commands:** ~36
+**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-waha <group> <verb> ...`, use these AI-facing affordances:
+
+1. **Find a command by keyword** — substring filter, returns sorted leaf paths:
+   ```bash
+   kctl-waha commands list --filter <keyword>
+   ```
+   Example: `kctl-waha 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-waha 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-waha <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:
+
+"bridge", "check", "commands", "completions", "config", "current", "dashboard", "doctor", "generate", "health", "init", "kctl-waha", "logout", "messages", "migrate", "profile", "profiles", "remove", "restart", "self-update", "send", "send-image", "sessions", "setup-chatwoot", "setup-webhook", "skill", "start", "stop", "test", "tree", "tui", "webhooks"
+
+## Command Reference
+
+### `kctl-waha bridge`
+
+Manage WAHA bridge sidecar.
+
+| Command | Description |
+|---------|-------------|
+| `bridge health` | Check bridge sidecar health. |
+| `bridge setup-chatwoot [--name] [--callback_url]` | Setup Chatwoot inbox integration via bridge. |
+| `bridge setup-webhook [--session] [--webhook_url]` | Setup WAHA webhook via bridge. |
+| `bridge status` | Show bridge setup status (WAHA, Chatwoot, Odoo config). |
+
+### `kctl-waha 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-waha completions`
+
+Generate or install shell completions.
+
+Usage: `kctl-waha completions [--shell] [--install]`
+
+### `kctl-waha config`
+
+Manage CLI configuration and profiles.
+
+| Command | Description |
+|---------|-------------|
+| `config add <name> [--url] [--api_key] [--bridge_url] [--set_default]` | Add or update a profile's WAHA connection. |
+| `config current` | Show the active profile and connection status. |
+| `config init [--url] [--api_key] [--bridge_url] [--name]` | Initialize CLI configuration (interactive if no flags given). |
+| `config migrate` | Migrate config from flat format to service-scoped format. |
+| `config profiles` | List all profiles with WAHA connection status. |
+| `config remove <name> [--force] [--service_only]` | Remove a profile or just its WAHA config. |
+| `config set <key> <value> [--profile_arg]` | Set a configuration value for the current service. |
+| `config show` | Show full configuration (API keys masked). |
+| `config test` | Test API connection with current configuration. |
+| `config use <name>` | Switch the default profile. |
+
+**Examples:**
+```bash
+kctl-waha config set url https://waha.new.io
+kctl-waha config set api_key new-key-value
+kctl-waha config set bridge_url http://localhost:3050
+kctl-waha config set default_profile production
+```
+
+### `kctl-waha dashboard`
+
+System overview dashboard.
+
+### `kctl-waha doctor`
+
+Run diagnostic checks.
+
+### `kctl-waha health`
+
+Health checks and diagnostics.
+
+### `kctl-waha messages`
+
+Send WhatsApp messages.
+
+| Command | Description |
+|---------|-------------|
+| `messages send <phone> <text> [--session]` | Send a text message. |
+| `messages send-image <phone> <url> [--caption] [--session]` | Send an image message. |
+
+**Examples:**
+```bash
+kctl-waha messages send 6281234567890 "Hello!"
+kctl-waha messages send +628123456 "Hi there" --session my-session
+kctl-waha messages send-image 6281234567890 https://example.com/image.png
+kctl-waha messages send-image 6281234567890 https://example.com/photo.jpg --caption "Check this out"
+```
+
+### `kctl-waha self-update`
+
+Check for updates and upgrade kctl-waha.
+
+### `kctl-waha sessions`
+
+Manage WhatsApp sessions.
+
+| Command | Description |
+|---------|-------------|
+| `sessions delete <name> [--force]` | Delete a WhatsApp session. |
+| `sessions get [--name]` | Show session details. |
+| `sessions list [--all_sessions]` | List WhatsApp sessions. |
+| `sessions logout [--name] [--force]` | Logout from a WhatsApp session. |
+| `sessions me [--name]` | Show current session account info. |
+| `sessions qr [--name]` | Get QR code for session authentication. |
+| `sessions restart [--name]` | Restart a WhatsApp session (stop + start). |
+| `sessions start [--name] [--engine]` | Start a WhatsApp session. |
+| `sessions stop [--name]` | Stop a WhatsApp session. |
+
+### `kctl-waha skill`
+
+Claude Code skill management.
+
+| Command | Description |
+|---------|-------------|
+| `skill generate [--output] [--install] [--check]` | Auto-generate SKILL.md from CLI command registry. |
+
+**Examples:**
+```bash
+kctl-waha skill generate
+kctl-waha skill generate --install
+kctl-waha skill generate --check
+```
+
+### `kctl-waha tui`
+
+Launch the interactive TUI.
+
+Usage: `kctl-waha tui [--profile]`
+
+### `kctl-waha webhooks`
+
+Manage session webhooks.
+
+| Command | Description |
+|---------|-------------|
+| `webhooks list` | List webhook configurations for all sessions. |
+| `webhooks set <session> <url> [--events] [--hmac_key]` | Set webhook configuration for a session. |
+
+**Examples:**
+```bash
+kctl-waha webhooks set default --url https://bridge.kodeme.io/webhook
+kctl-waha webhooks set default --url https://n8n.kodeme.io/waha --events message,session.status
+kctl-waha webhooks set default --url https://hook.io/waha --hmac-key mysecret
+```
+
+## Configuration
+
+Shared config: `~/.config/kodemeio/config.yaml`
+
+```bash
+kctl-waha config init       # Interactive setup
+kctl-waha config show       # Show current config
+kctl-waha config profiles   # List profiles
+kctl-waha config current    # Show active profile
+kctl-waha config validate   # Verify config
+```

kctl_waha-0.8.4/src/kctl_waha/__init__.py

@@ -0,0 +1,5 @@
+"""Kodemeio WAHA CLI."""
+
+from __future__ import annotations
+
+__version__ = "0.8.4"

kctl_waha-0.8.4/src/kctl_waha/__main__.py

@@ -0,0 +1,7 @@
+"""Allow running as python -m kctl_waha."""
+
+from __future__ import annotations
+
+from kctl_waha.cli import app
+
+app()

kctl_waha-0.8.4/src/kctl_waha/cli.py

@@ -0,0 +1,132 @@
+"""Main CLI entry point for kctl-waha."""
+
+from __future__ import annotations
+
+
+from typing import Annotated
+
+import typer
+from kctl_lib import KctlError, handle_cli_error
+from kctl_lib import cli_entrypoint, register_introspection_commands
+
+from kctl_waha import __version__
+from kctl_waha.commands.bridge import app as bridge_app
+from kctl_waha.commands.config_cmd import app as config_app
+from kctl_waha.commands.dashboard import app as dashboard_app
+from kctl_waha.commands.health import app as health_app
+from kctl_waha.commands.messages import app as messages_app
+from kctl_waha.commands.sessions import app as sessions_app
+from kctl_waha.commands.webhooks import app as webhooks_app
+from kctl_waha.core.callbacks import AppContext
+from kctl_waha.commands.skill_cmd import app as skill_app
+from kctl_waha.commands.doctor_cmd import app as doctor_app
+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-waha {__version__}")
+        raise typer.Exit()
+
+
+app = typer.Typer(
+    name="kctl-waha",
+    help="Kodemeio WAHA CLI - manage WhatsApp HTTP API instances.",
+    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,
+    url: Annotated[str | None, typer.Option("--url", help="API URL override")] = None,
+    api_key: Annotated[str | None, typer.Option("--api-key", help="API key override")] = None,
+    bridge_url: Annotated[str | None, typer.Option("--bridge-url", help="Bridge URL override")] = None,
+    version: Annotated[
+        bool, typer.Option("--version", "-V", callback=version_callback, is_eager=True, help="Show version")
+    ] = False,
+) -> None:
+    """Kodemeio WAHA CLI."""
+    ctx.ensure_object(dict)
+    ctx.obj = AppContext(
+        json_mode=json_output,
+        quiet=quiet,
+        profile=profile,
+        url_override=url,
+        api_key_override=api_key,
+        bridge_url_override=bridge_url,
+    )
+    notify_if_outdated(ctx.obj.output, "kctl-waha", __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(sessions_app, name="sessions")
+app.add_typer(messages_app, name="messages")
+app.add_typer(webhooks_app, name="webhooks")
+app.add_typer(bridge_app, name="bridge")
+app.add_typer(skill_app, name="skill", hidden=True)
+app.add_typer(doctor_app, name="doctor")
+add_tui_command(app, service_key="waha", version=__version__)
+
+
+@app.command("self-update")
+def self_update_cmd(ctx: typer.Context) -> None:
+    """Check for updates and upgrade kctl-waha."""
+    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-waha", __version__)
+    if latest:
+        out.info(f"Updating to {latest}...")
+        do_update("kctl-waha")
+        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-waha", 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-waha", 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()