kctl-cf 0.3.0__py3-none-any.whl

kctl_cf/__init__.py

@@ -0,0 +1,3 @@
+"""kctl-cf: Kodemeio Cloudflare CLI."""
+
+__version__ = "0.3.0"

kctl_cf/__main__.py

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

kctl_cf/cli.py

@@ -0,0 +1,189 @@
+"""Main CLI entry point for kctl-cf."""
+
+from __future__ import annotations
+
+
+from typing import Annotated
+
+import typer
+
+from kctl_cf import __version__
+from kctl_cf.commands.access import app as access_app
+from kctl_cf.commands.analytics import app as analytics_app
+from kctl_cf.commands.argo import app as argo_app
+from kctl_cf.commands.cache import app as cache_app
+from kctl_cf.commands.config_cmd import app as config_app
+from kctl_cf.commands.custom_hostnames import app as custom_hostnames_app
+from kctl_cf.commands.email_routing import app as email_routing_app
+from kctl_cf.commands.export import app as export_app
+from kctl_cf.commands.health import app as health_app
+from kctl_cf.commands.load_balancers import app as load_balancers_app
+from kctl_cf.commands.page_rules import app as page_rules_app
+from kctl_cf.commands.pages import app as pages_app
+from kctl_cf.commands.r2 import app as r2_app
+from kctl_cf.commands.records import app as records_app
+from kctl_cf.commands.redirects import app as redirects_app
+from kctl_cf.commands.selftest import app as selftest_app
+from kctl_cf.commands.spectrum import app as spectrum_app
+from kctl_cf.commands.speed import app as speed_app
+from kctl_cf.commands.ssl import app as ssl_app
+from kctl_cf.commands.status import app as status_app
+from kctl_cf.commands.terraform import app as terraform_app
+from kctl_cf.commands.tokens import app as tokens_app
+from kctl_cf.commands.tunnels import app as tunnels_app
+from kctl_cf.commands.waf import app as waf_app
+from kctl_cf.commands.waiting_rooms import app as waiting_rooms_app
+from kctl_cf.commands.workers import app as workers_app
+from kctl_cf.commands.zones import app as zones_app
+from kctl_cf.core.callbacks import AppContext
+from kctl_cf.core.exceptions import APIError, AuthenticationError, ConfigError, KctlError
+from kctl_cf.core.exceptions import ConnectionError as KctlConnectionError
+from kctl_cf.core.plugins import discover_and_load_plugins
+from kctl_lib.self_update import notify_if_outdated
+
+
+def version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"kctl-cf {__version__}")
+        raise typer.Exit()
+
+
+app = typer.Typer(
+    name="kctl-cf",
+    help="Kodemeio Cloudflare CLI - manage DNS, tunnels, WAF, cache, Workers, R2, email routing, access.",
+    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,
+    format: Annotated[str, typer.Option("--format", "-f", help="Output format: pretty/json/csv/yaml")] = "pretty",
+    no_header: Annotated[bool, typer.Option("--no-header", help="Omit header row in CSV output")] = False,
+    profile: Annotated[str | None, typer.Option("--profile", "-p", help="Config profile name")] = None,
+    api_token: Annotated[str | None, typer.Option("--api-token", help="API token override")] = None,
+    account_id: Annotated[str | None, typer.Option("--account-id", help="Account ID override")] = None,
+    version: Annotated[
+        bool, typer.Option("--version", "-V", callback=version_callback, is_eager=True, help="Show version")
+    ] = False,
+) -> None:
+    """Kodemeio Cloudflare CLI."""
+    ctx.ensure_object(dict)
+    ctx.obj = AppContext(
+        json_mode=json_output,
+        quiet=quiet,
+        format=format,
+        no_header=no_header,
+        profile=profile,
+        api_token_override=api_token,
+        account_id_override=account_id,
+    )
+    notify_if_outdated(ctx.obj.output, "kctl-cf", __version__)
+
+
+app.add_typer(config_app, name="config")
+app.add_typer(zones_app, name="zones")
+app.add_typer(records_app, name="records")
+app.add_typer(tokens_app, name="tokens")
+app.add_typer(tunnels_app, name="tunnels")
+app.add_typer(health_app, name="health")
+app.add_typer(waf_app, name="waf")
+app.add_typer(cache_app, name="cache")
+app.add_typer(ssl_app, name="ssl")
+app.add_typer(workers_app, name="workers")
+app.add_typer(r2_app, name="r2")
+app.add_typer(export_app, name="export")
+app.add_typer(terraform_app, name="terraform")
+app.add_typer(email_routing_app, name="email-routing")
+app.add_typer(page_rules_app, name="page-rules")
+app.add_typer(pages_app, name="pages")
+app.add_typer(redirects_app, name="redirects")
+app.add_typer(access_app, name="access")
+app.add_typer(speed_app, name="speed")
+app.add_typer(status_app, name="status")
+app.add_typer(analytics_app, name="analytics")
+app.add_typer(selftest_app, name="selftest")
+app.add_typer(argo_app, name="argo")
+app.add_typer(custom_hostnames_app, name="custom-hostnames")
+app.add_typer(load_balancers_app, name="load-balancers")
+app.add_typer(spectrum_app, name="spectrum")
+app.add_typer(waiting_rooms_app, name="waiting-rooms")
+# Load plugins from entry points
+discover_and_load_plugins(app)
+
+# Register short aliases and skill generation
+from kctl_cf.commands.aliases import register_aliases  # noqa: E402
+from kctl_cf.commands.skill_cmd import app as skill_app  # noqa: E402
+
+register_aliases(app)
+from kctl_cf.commands.doctor_cmd import app as doctor_app  # noqa: E402
+
+app.add_typer(doctor_app, name="doctor")
+app.add_typer(skill_app, name="skill", hidden=True)
+
+
+@app.command("self-update")
+def self_update_cmd(ctx: typer.Context) -> None:
+    """Check for updates and upgrade kctl-cf."""
+    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-cf", __version__)
+    if latest:
+        out.info(f"Updating to {latest}...")
+        do_update("kctl-cf")
+        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-cf", 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-cf", shell)
+        typer.echo(script)
+
+
+def _run() -> None:
+    try:
+        app()
+    except KctlConnectionError as e:
+        typer.echo(f"Connection error: {e}", err=True)
+        raise typer.Exit(1) from e
+    except AuthenticationError as e:
+        typer.echo(f"Auth error: {e}", err=True)
+        raise typer.Exit(1) from e
+    except APIError as e:
+        typer.echo(f"API error: {e}", err=True)
+        raise typer.Exit(1) from e
+    except ConfigError as e:
+        typer.echo(f"Config error: {e}", err=True)
+        raise typer.Exit(1) from e
+    except KctlError as e:
+        typer.echo(f"Error: {e}", err=True)
+        raise typer.Exit(1) from e
+
+
+if __name__ == "__main__":
+    _run()
+# test

kctl_cf/commands/access.py

@@ -0,0 +1,447 @@
+"""Zero Trust Access management commands."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from kctl_cf.core.callbacks import AppContext
+from kctl_cf.core.utils import require_account
+
+app = typer.Typer(help="Manage Cloudflare Zero Trust Access.")
+
+
+def _parse_access_rules(c: AppContext, rules: list[str] | None) -> list[dict]:
+    """Parse access rules from CLI format (email:user@x.com, email_domain:x.com, everyone:)."""
+    if not rules:
+        return []
+    parsed = []
+    for rule in rules:
+        if ":" not in rule:
+            c.output.error(
+                f"Invalid rule format: {rule!r} (expected type:value, e.g. 'email:user@x.com' or 'everyone:')"
+            )
+            raise typer.Exit(1)
+        rule_type, rule_value = rule.split(":", 1)
+        if rule_type == "email":
+            parsed.append({"email": {"email": rule_value}})
+        elif rule_type == "email_domain":
+            parsed.append({"email_domain": {"domain": rule_value}})
+        elif rule_type == "everyone":
+            parsed.append({"everyone": {}})
+        else:
+            parsed.append({rule_type: {"value": rule_value}})
+    return parsed
+
+
+@app.command()
+def apps(ctx: typer.Context) -> None:
+    """List Access applications."""
+    c: AppContext = ctx.obj
+    acct = require_account(c)
+    result = c.client.get(f"/accounts/{acct}/access/apps")
+    if not isinstance(result, list):
+        result = []
+    rows = []
+    for a in result:
+        rows.append(
+            [
+                a.get("id", "")[:12],
+                a.get("name", ""),
+                a.get("domain", ""),
+                a.get("type", ""),
+                a.get("session_duration", ""),
+                a.get("created_at", "")[:19],
+            ]
+        )
+    c.output.table(
+        "Access Applications",
+        [("ID", "dim"), ("Name", "cyan"), ("Domain", "green"), ("Type", ""), ("Session", "dim"), ("Created", "dim")],
+        rows,
+        data_for_json=result,
+    )
+
+
+@app.command("get-app")
+def get_app(
+    ctx: typer.Context,
+    app_id: Annotated[str, typer.Argument(help="Application ID")],
+) -> None:
+    """Get details for an Access application."""
+    c: AppContext = ctx.obj
+    acct = require_account(c)
+    result = c.client.get(f"/accounts/{acct}/access/apps/{app_id}")
+    if not isinstance(result, dict):
+        result = {}
+    policies_count = len(result.get("policies", [])) if isinstance(result.get("policies"), list) else 0
+    sections = [
+        (
+            "Application",
+            [
+                ("ID", result.get("id", "")),
+                ("Name", result.get("name", "")),
+                ("Domain", result.get("domain", "")),
+                ("Type", result.get("type", "")),
+                ("AUD", result.get("aud", "")[:40]),
+                ("Session Duration", result.get("session_duration", "")),
+                ("Auto-Redirect to IdP", str(result.get("auto_redirect_to_identity", False))),
+            ],
+        ),
+        (
+            "Settings",
+            [
+                ("Policies", str(policies_count)),
+                ("App Launcher Visible", str(result.get("app_launcher_visible", True))),
+                ("Skip Interstitial", str(result.get("skip_interstitial", False))),
+                ("Created", result.get("created_at", "")[:19]),
+                ("Updated", result.get("updated_at", "")[:19]),
+            ],
+        ),
+    ]
+    c.output.detail(f"Access App — {result.get('name', app_id)}", sections, data_for_json=result)
+
+
+@app.command()
+def policies(
+    ctx: typer.Context,
+    app_id: Annotated[str, typer.Argument(help="Application ID")],
+) -> None:
+    """List policies for an Access application."""
+    c: AppContext = ctx.obj
+    acct = require_account(c)
+    result = c.client.get(f"/accounts/{acct}/access/apps/{app_id}/policies")
+    if not isinstance(result, list):
+        result = []
+    rows = []
+    for p in result:
+        include = p.get("include", [])
+        include_str = ", ".join(str(i.get("email", {}).get("email", "") or i) for i in include[:3]) if include else ""
+        rows.append(
+            [
+                p.get("id", "")[:12],
+                p.get("name", ""),
+                p.get("decision", ""),
+                str(p.get("precedence", "")),
+                include_str[:40],
+            ]
+        )
+    c.output.table(
+        f"Access Policies — {app_id[:12]}",
+        [("ID", "dim"), ("Name", "cyan"), ("Decision", "green"), ("Precedence", "dim"), ("Include", "")],
+        rows,
+        data_for_json=result,
+    )
+
+
+@app.command()
+def groups(ctx: typer.Context) -> None:
+    """List Access groups."""
+    c: AppContext = ctx.obj
+    acct = require_account(c)
+    result = c.client.get(f"/accounts/{acct}/access/groups")
+    if not isinstance(result, list):
+        result = []
+    rows = []
+    for g in result:
+        include = g.get("include", [])
+        include_count = len(include) if isinstance(include, list) else 0
+        rows.append(
+            [
+                g.get("id", "")[:12],
+                g.get("name", ""),
+                str(include_count),
+                g.get("created_at", "")[:19],
+                g.get("updated_at", "")[:19],
+            ]
+        )
+    c.output.table(
+        "Access Groups",
+        [("ID", "dim"), ("Name", "cyan"), ("Include Rules", "green"), ("Created", "dim"), ("Updated", "dim")],
+        rows,
+        data_for_json=result,
+    )
+
+
+@app.command("create-group")
+def create_group(
+    ctx: typer.Context,
+    name: Annotated[str, typer.Option("--name", help="Group name")],
+    include: Annotated[
+        list[str] | None,
+        typer.Option("--include", help="Include rules (email:user@example.com or email_domain:example.com)"),
+    ] = None,
+    require: Annotated[
+        list[str] | None, typer.Option("--require", help="Require rules (same format as include)")
+    ] = None,
+) -> None:
+    """Create an Access group."""
+    c: AppContext = ctx.obj
+    acct = require_account(c)
+    payload: dict = {
+        "name": name,
+        "include": _parse_access_rules(c, include),
+    }
+    if require:
+        payload["require"] = _parse_access_rules(c, require)
+
+    result = c.client.post(f"/accounts/{acct}/access/groups", json=payload)
+    group_id = result.get("id", "") if isinstance(result, dict) else ""
+    c.output.success(f"Access group created: {group_id}")
+
+
+@app.command("delete-group")
+def delete_group(
+    ctx: typer.Context,
+    group_id: Annotated[str, typer.Argument(help="Access group ID to delete")],
+    force: Annotated[bool, typer.Option("--force", help="Required to confirm deletion")] = False,
+) -> None:
+    """Delete an Access group. Requires --force to confirm."""
+    c: AppContext = ctx.obj
+    if not force:
+        c.output.error("Delete blocked: pass --force to confirm deletion")
+        raise typer.Exit(1)
+    acct = require_account(c)
+    c.client.delete(f"/accounts/{acct}/access/groups/{group_id}")
+    c.output.success(f"Access group deleted: {group_id}")
+
+
+@app.command("create-app")
+def create_app(
+    ctx: typer.Context,
+    name: Annotated[str, typer.Option("--name", help="Application name")],
+    domain: Annotated[str, typer.Option("--domain", help="Application domain")],
+    app_type: Annotated[
+        str, typer.Option("--type", help="Application type (self_hosted, ssh, vnc, bookmark)")
+    ] = "self_hosted",
+    session_duration: Annotated[str, typer.Option("--session-duration", help="Session duration (e.g. 24h)")] = "24h",
+) -> None:
+    """Create an Access application."""
+    c: AppContext = ctx.obj
+    acct = require_account(c)
+    payload = {
+        "name": name,
+        "domain": domain,
+        "type": app_type,
+        "session_duration": session_duration,
+    }
+    result = c.client.post(f"/accounts/{acct}/access/apps", json=payload)
+    app_id = result.get("id", "") if isinstance(result, dict) else ""
+    c.output.success(f"Access application created: {app_id}")
+
+
+@app.command("update-app")
+def update_app(
+    ctx: typer.Context,
+    app_id: Annotated[str, typer.Argument(help="Application ID")],
+    name: Annotated[str | None, typer.Option("--name", help="New name")] = None,
+    domain: Annotated[str | None, typer.Option("--domain", help="New domain")] = None,
+    session_duration: Annotated[str | None, typer.Option("--session-duration", help="Session duration")] = None,
+) -> None:
+    """Update an Access application (merges with existing settings)."""
+    c: AppContext = ctx.obj
+    acct = require_account(c)
+    if not any([name, domain, session_duration]):
+        c.output.warn("No fields to update")
+        return
+    existing = c.client.get(f"/accounts/{acct}/access/apps/{app_id}")
+    if not isinstance(existing, dict):
+        existing = {}
+    payload: dict = {
+        "name": name or existing.get("name", ""),
+        "domain": domain or existing.get("domain", ""),
+        "type": existing.get("type", "self_hosted"),
+        "session_duration": session_duration or existing.get("session_duration", "24h"),
+    }
+    c.client.put(f"/accounts/{acct}/access/apps/{app_id}", json=payload)
+    c.output.success(f"Access application updated: {app_id}")
+
+
+@app.command("delete-app")
+def delete_app(
+    ctx: typer.Context,
+    app_id: Annotated[str, typer.Argument(help="Application ID to delete")],
+    force: Annotated[bool, typer.Option("--force", help="Required to confirm deletion")] = False,
+) -> None:
+    """Delete an Access application. Requires --force to confirm."""
+    c: AppContext = ctx.obj
+    if not force:
+        c.output.error("Delete blocked: pass --force to confirm deletion")
+        raise typer.Exit(1)
+    acct = require_account(c)
+    c.client.delete(f"/accounts/{acct}/access/apps/{app_id}")
+    c.output.success(f"Access application deleted: {app_id}")
+
+
+@app.command("create-policy")
+def create_policy(
+    ctx: typer.Context,
+    app_id: Annotated[str, typer.Argument(help="Application ID")],
+    name: Annotated[str, typer.Option("--name", help="Policy name")],
+    decision: Annotated[str, typer.Option("--decision", help="Decision (allow, deny, non_identity, bypass)")] = "allow",
+    include: Annotated[
+        list[str] | None,
+        typer.Option("--include", help="Include rules (email:user@x.com or email_domain:x.com)"),
+    ] = None,
+) -> None:
+    """Create a policy for an Access application."""
+    c: AppContext = ctx.obj
+    acct = require_account(c)
+    include_rules = _parse_access_rules(c, include)
+    payload = {"name": name, "decision": decision, "include": include_rules}
+    result = c.client.post(f"/accounts/{acct}/access/apps/{app_id}/policies", json=payload)
+    policy_id = result.get("id", "") if isinstance(result, dict) else ""
+    c.output.success(f"Access policy created: {policy_id}")
+
+
+@app.command("update-policy")
+def update_policy(
+    ctx: typer.Context,
+    app_id: Annotated[str, typer.Argument(help="Application ID")],
+    policy_id: Annotated[str, typer.Argument(help="Policy ID")],
+    name: Annotated[str | None, typer.Option("--name", help="New policy name")] = None,
+    decision: Annotated[str | None, typer.Option("--decision", help="New decision")] = None,
+) -> None:
+    """Update a policy for an Access application (merges with existing)."""
+    c: AppContext = ctx.obj
+    acct = require_account(c)
+    if not any([name, decision]):
+        c.output.warn("No fields to update")
+        return
+    existing = c.client.get(f"/accounts/{acct}/access/apps/{app_id}/policies/{policy_id}")
+    if not isinstance(existing, dict):
+        existing = {}
+    payload: dict = {
+        "name": name or existing.get("name", ""),
+        "decision": decision or existing.get("decision", "allow"),
+        "include": existing.get("include", []),
+    }
+    c.client.put(f"/accounts/{acct}/access/apps/{app_id}/policies/{policy_id}", json=payload)
+    c.output.success(f"Access policy updated: {policy_id}")
+
+
+@app.command("delete-policy")
+def delete_policy(
+    ctx: typer.Context,
+    app_id: Annotated[str, typer.Argument(help="Application ID")],
+    policy_id: Annotated[str, typer.Argument(help="Policy ID to delete")],
+    force: Annotated[bool, typer.Option("--force", help="Required to confirm deletion")] = False,
+) -> None:
+    """Delete a policy for an Access application. Requires --force to confirm."""
+    c: AppContext = ctx.obj
+    if not force:
+        c.output.error("Delete blocked: pass --force to confirm deletion")
+        raise typer.Exit(1)
+    acct = require_account(c)
+    c.client.delete(f"/accounts/{acct}/access/apps/{app_id}/policies/{policy_id}")
+    c.output.success(f"Access policy deleted: {policy_id}")
+
+
+@app.command()
+def idps(ctx: typer.Context) -> None:
+    """List Access identity providers."""
+    c: AppContext = ctx.obj
+    acct = require_account(c)
+    result = c.client.get(f"/accounts/{acct}/access/identity_providers")
+    if not isinstance(result, list):
+        result = []
+    rows = []
+    for idp in result:
+        rows.append(
+            [
+                idp.get("id", "")[:12],
+                idp.get("name", ""),
+                idp.get("type", ""),
+                idp.get("created_at", "")[:19],
+            ]
+        )
+    c.output.table(
+        "Identity Providers",
+        [("ID", "dim"), ("Name", "cyan"), ("Type", "green"), ("Created", "dim")],
+        rows,
+        data_for_json=result,
+    )
+
+
+@app.command("service-tokens")
+def service_tokens(ctx: typer.Context) -> None:
+    """List Access service tokens."""
+    c: AppContext = ctx.obj
+    acct = require_account(c)
+    result = c.client.get(f"/accounts/{acct}/access/service_tokens")
+    if not isinstance(result, list):
+        result = []
+    rows = []
+    for t in result:
+        rows.append(
+            [
+                t.get("id", "")[:12],
+                t.get("name", ""),
+                t.get("client_id", "")[:20],
+                t.get("expires_at", "")[:19] if t.get("expires_at") else "never",
+                t.get("created_at", "")[:19],
+            ]
+        )
+    c.output.table(
+        "Service Tokens",
+        [("ID", "dim"), ("Name", "cyan"), ("Client ID", ""), ("Expires", "green"), ("Created", "dim")],
+        rows,
+        data_for_json=result,
+    )
+
+
+@app.command("create-service-token")
+def create_service_token(
+    ctx: typer.Context,
+    name: Annotated[str, typer.Option("--name", help="Service token name")],
+    duration: Annotated[str, typer.Option("--duration", help="Token duration (e.g. 8760h for 1 year)")] = "8760h",
+) -> None:
+    """Create an Access service token."""
+    c: AppContext = ctx.obj
+    acct = require_account(c)
+    payload = {"name": name, "duration": duration}
+    result = c.client.post(f"/accounts/{acct}/access/service_tokens", json=payload)
+    if not isinstance(result, dict):
+        result = {}
+    if c.output.json_mode:
+        c.output.raw_json(result)
+    else:
+        c.output.success(f"Service token created: {result.get('id', '')}")
+        c.output.kv("Client ID", result.get("client_id", ""))
+        c.output.warn("Client Secret (save this — shown only once):")
+        c.output.text(result.get("client_secret", ""))
+
+
+@app.command("rotate-service-token")
+def rotate_service_token(
+    ctx: typer.Context,
+    token_id: Annotated[str, typer.Argument(help="Service token ID")],
+) -> None:
+    """Rotate an Access service token (generates new secret)."""
+    c: AppContext = ctx.obj
+    acct = require_account(c)
+    result = c.client.post(f"/accounts/{acct}/access/service_tokens/{token_id}/rotate")
+    if not isinstance(result, dict):
+        result = {}
+    if c.output.json_mode:
+        c.output.raw_json(result)
+    else:
+        c.output.success(f"Service token rotated: {token_id}")
+        c.output.warn("New Client Secret (save this — shown only once):")
+        c.output.text(result.get("client_secret", ""))
+
+
+@app.command("delete-service-token")
+def delete_service_token(
+    ctx: typer.Context,
+    token_id: Annotated[str, typer.Argument(help="Service token ID to delete")],
+    force: Annotated[bool, typer.Option("--force", help="Required to confirm deletion")] = False,
+) -> None:
+    """Delete an Access service token. Requires --force to confirm."""
+    c: AppContext = ctx.obj
+    if not force:
+        c.output.error("Delete blocked: pass --force to confirm deletion")
+        raise typer.Exit(1)
+    acct = require_account(c)
+    c.client.delete(f"/accounts/{acct}/access/service_tokens/{token_id}")
+    c.output.success(f"Service token deleted: {token_id}")