@adgine/geo-cli 1.2.8

package/skills/adgine-geo-integrations/SKILL.md

@@ -0,0 +1,188 @@
+---
+name: adgine/geo-integrations
+description: Connects, configures, and syncs GA4 and Cloudflare data sources for a
+  GEO project — OAuth setup, property/zone selection, data sync triggers, and
+  Cloudflare Worker deployment for AI crawler tracking. Also queries the
+  integration-specific traffic data (GA4 sessions/sources, CF bot events). Use
+  when the user wants to connect GA4 (连接 GA4 / bind GA4 / GA4 OAuth / Google
+  Analytics 集成), connect Cloudflare (连接 Cloudflare / bind CF API token /
+  接入 CF), sync data (同步 GA4 / 同步 Cloudflare / 拉取数据), or deploy
+  the Cloudflare Worker (部署 Worker / Worker 部署状态).
+  NOT for high-level project traffic summary (no GA4/CF context) — use
+  adgine-geo-analytics. NOT for per-bot crawl drill-downs — use
+  adgine-geo-aiagent. For WordPress — use adgine-geo-wordpress.
+---
+
+# GEO Integrations
+
+Unified skill for the two analytics integrations (GA4 + Cloudflare). Four
+scripts cover OAuth setup, data sync, traffic queries, and Cloudflare Worker
+management for AI traffic tracking.
+
+> WordPress integration lives in the separate **adgine-geo-wordpress** skill
+> (publishing-focused, very different workflow).
+
+## 触发条件
+
+当用户说出以下意图时使用本 skill：
+- 连接/绑定/接入 GA4 或 Cloudflare
+- GA4 OAuth 授权 / 选择 GA4 媒体资源 / 选择 Cloudflare Zone
+- 同步数据 / 拉取数据 / 手动同步
+- 查询 GA4 流量来源 / 查询 Cloudflare bot 事件
+- 部署/检查/删除 Cloudflare Worker
+
+**⛔ 以下意图不属于本 skill：**
+- “流量概览” / “项目流量汇总”（不涉及连接/同步操作）→ **adgine-geo-analytics**
+- “哪些 AI bot 爬了我的网站” / “GPTBot 访问明细” → **adgine-geo-aiagent**
+- “发布到 WordPress” → **adgine-geo-wordpress**
+
+## Output rules — IDs (apply to every reply)
+
+These rules apply to **every list, table, and confirmation message** in this skill. Their goal: keep user-facing output friendly while preserving the IDs the agent needs internally.
+
+1. **Lists & tables — never show raw UUIDs in cells.** Use a 1-based `#` index column instead. Keep a private mental mapping of `#N → actual UUID` so that follow-up commands like *"delete #3"*, *"run citation test on #1 #2"*, *"show details of the 2nd one"* resolve to the right entity.
+   - Index numbers restart from 1 in each new list — they are not stable across calls.
+   - If the user references *"the topic about X"* / *"that Poki vs CrazyGames prompt"*, match by visible content (name / title / domain / prompt text), not by ID.
+
+2. **Single-item operations — prefer a human name over an ID.**
+   - ✅ *"Project **Poki vs Competitors** deleted."*
+   - ✅ *"Topic **Brand mentions in 2024** updated — name → 'Brand mentions 2025'."*
+   - ❌ *"Project `a4305b57-1c79-4cec-a17c-16eb1d959ea6` deleted."*
+   - If the entity has **no human-readable name** (e.g. an anonymous prompt or a job), use a short 8-character prefix: *"Prompt `2a2a8f4f…` deleted."* Never paste the full UUID.
+
+3. **Always exception: `--json` mode.** When the user passes `--json` to a script or explicitly asks for raw JSON / debug output, print the script output verbatim — do not strip IDs.
+
+4. **Internally, the agent still uses full UUIDs** for every API call (`--project-id`, `--topic-id`, `--prompt-id`, etc.). The display rules only affect what is shown back to the user.
+
+---
+
+## Step 1: Make sure GEO_API_KEY is configured
+
+Scripts auto-load `GEO_API_KEY` from `<skills-root>/.env` on import — **no `export` needed, no shell restart needed**. To check the configuration, run any script (it prints the exact `.env` path if the key is missing).
+
+- ✅ Key already in `<skills-root>/.env` → proceed.
+- ❌ Key missing, or user just gave you a new key → go to the **adgine-geo-projects** skill, **Step 0**, which runs `python3 <skills-root>/setup.py <KEY>` to write the key into the correct `.env` file. **Never** write the key to `~/.zshrc`, `~/.bashrc`, Hermes global config, or any user-secrets store.
+
+> ⚠️ **IMPORTANT:** In all shell/exec commands, always reference the key as `$GEO_API_KEY` (the environment variable). Never hardcode the literal value.
+
+## Project selection
+
+```bash
+export GEO_PROJECT_ID=<project-id>
+```
+
+## Scripts
+
+### GA4 setup (OAuth + property selection)
+
+```bash
+python3 scripts/ga4_setup.py auth-url                       # show OAuth URL
+python3 scripts/ga4_setup.py connect --code <auth_code>     # manual code exchange (debug)
+python3 scripts/ga4_setup.py properties                     # list available GA4 properties
+python3 scripts/ga4_setup.py select --property-id <id>      # bind property (triggers 7-day backfill)
+```
+
+### GA4 data (sync + queries)
+
+```bash
+python3 scripts/ga4_data.py sync                                  # pull latest data into local DB
+python3 scripts/ga4_data.py overview     [--start ...] [--end ...]   # sessions/users/pageviews
+python3 scripts/ga4_data.py ai-referrals [--start ...] [--end ...]   # AI platform breakdown
+python3 scripts/ga4_data.py pages        [--page 1] [--limit 20]     # top pages
+python3 scripts/ga4_data.py sources      [--start ...] [--end ...]   # channel split
+```
+
+### Cloudflare connection (token + zones + sync)
+
+```bash
+python3 scripts/cloudflare_connect.py list-zones --token <api_token>   # zones the token can access
+python3 scripts/cloudflare_connect.py connect    --token <api_token>   # bind (auto-matches zone)
+python3 scripts/cloudflare_connect.py sync                             # pull latest CF data
+python3 scripts/cloudflare_connect.py overview [--start ...] [--end ...]
+```
+
+### Cloudflare Worker (AI traffic tracking)
+
+```bash
+python3 scripts/cloudflare_worker.py config                      # get Worker JS code + keys
+python3 scripts/cloudflare_worker.py deploy [--zone-id <id>]     # one-click deploy
+python3 scripts/cloudflare_worker.py deploy-status               # is Worker deployed?
+python3 scripts/cloudflare_worker.py overview [--start ...] [--end ...]
+python3 scripts/cloudflare_worker.py pages   [--page 1] [--limit 20]
+python3 scripts/cloudflare_worker.py undeploy [--keep-script] --yes   # DESTRUCTIVE
+```
+
+> The Cloudflare API token must include **Workers** permissions for deploy /
+> undeploy / Worker analytics. Without it, `deploy-status` returns `deployed=false`
+> (it does not throw).
+
+## Output Format
+
+ASCII tables only inside fenced code blocks. Status vocabulary:
+`Connected` / `Disconnected` / `Pending` / `Yes` / `No`.
+
+## Workflow narrative
+
+### GA4 first-time setup
+1. `ga4_setup.py auth-url` → user opens the URL → Google asks for permission.
+2. After Google callback the GEO platform stores tokens automatically.
+3. `ga4_setup.py properties` → list options.
+4. `ga4_setup.py select --property-id <id>` → bind property.
+5. Backfill runs automatically; check progress with `ga4_data.py overview`.
+
+### Cloudflare first-time setup
+1. User creates a Cloudflare API token (with Zone:Read + Analytics:Read +
+   optionally Workers:Edit).
+2. `cloudflare_connect.py list-zones --token <t>` to verify access.
+3. `cloudflare_connect.py connect --token <t>` to bind.
+4. `cloudflare_connect.py sync` to pull initial data.
+
+### Cloudflare Worker (optional, for AI tracking)
+1. `cloudflare_worker.py config` → grab Worker JS + receiver URL.
+2. `cloudflare_worker.py deploy` → one-click deploy.
+3. `cloudflare_worker.py deploy-status` → verify route is live.
+4. After traffic accrues: `cloudflare_worker.py overview` / `pages`.
+
+## Related endpoints
+
+| Method | Path |
+|---|---|
+| GET    | `/api/projects/{id}/integrations/ga4/auth-url` |
+| POST   | `/api/projects/{id}/integrations/ga4/connect` |
+| GET    | `/api/projects/{id}/integrations/ga4/properties` |
+| POST   | `/api/projects/{id}/integrations/ga4/select-property` |
+| POST   | `/api/projects/{id}/integrations/ga4/sync` |
+| GET    | `/api/projects/{id}/integrations/ga4/overview` |
+| GET    | `/api/projects/{id}/integrations/ga4/ai-referrals` |
+| GET    | `/api/projects/{id}/integrations/ga4/pages` |
+| GET    | `/api/projects/{id}/integrations/ga4/sources` |
+| POST   | `/api/projects/{id}/integrations/cloudflare/list-zones` |
+| POST   | `/api/projects/{id}/integrations/cloudflare/connect` |
+| POST   | `/api/projects/{id}/integrations/cloudflare/sync` |
+| GET    | `/api/projects/{id}/integrations/cloudflare/overview` |
+| GET    | `/api/projects/{id}/integrations/cloudflare/worker-config` |
+| POST   | `/api/projects/{id}/integrations/cloudflare/worker/deploy` |
+| DELETE | `/api/projects/{id}/integrations/cloudflare/worker/deploy` |
+| GET    | `/api/projects/{id}/integrations/cloudflare/worker/deploy-status` |
+| GET    | `/api/projects/{id}/integrations/cloudflare/worker/overview` |
+| GET    | `/api/projects/{id}/integrations/cloudflare/worker/pages` |
+
+---
+
+## Post-task recommendations
+
+After connecting or syncing integrations, suggest the logical next step:
+
+| You just… | → use skill (agent-internal) |
+|---|---|
+| Connected GA4 / Cloudflare | 查看流量概览，确认数据已流入 *(→ adgine-geo-analytics)*|
+| Synced data | 查看 AI 爬虫追踪数据 *(→ adgine-geo-aiagent)*|
+| Deployed Cloudflare Worker | 检查 AI bot traffic 是否开始上报 *(→ adgine-geo-aiagent)*|
+| Checked integration status | 查看项目总览，确认所有集成健康 *(→ adgine-geo-dashboard)*|
+| Disconnected a service | 重新连接以恢复数据流 *(→ adgine-geo-integrations)*|
+
+**⚠️ Output rule:** Do NOT write skill names (e.g. `adgine-geo-xxx`) in user-facing suggestions. Each suggestion must be phrased as a natural-language prompt the user can copy and send directly to the agent.
+
+> 💡 **建议下一步：**
+> 1. **[行动标题]** — *"[可直接发送给 AI 的自然语言提示词]"*
+> 2. **[行动标题]** — *"[可直接发送给 AI 的自然语言提示词]"*

package/skills/adgine-geo-integrations/scripts/_client.py

@@ -0,0 +1,341 @@
+#!/usr/bin/env python3
+"""Shared HTTP client utilities for geo-skills scripts.
+
+Used by all scripts in this skill. Uses Python stdlib only — no external dependencies.
+
+This file is the canonical source. It must be copied verbatim into every
+adgine-geo-* skill folder's scripts/ directory. The sync linter at
+scripts/sync-skills/sync-skills.sh (in the GEOAgent repo) flags any drift.
+"""
+import os
+import sys
+import json
+import time
+import atexit
+import unicodedata
+import urllib.request as _req
+import urllib.error as _uerr
+import urllib.parse as _up
+
+def _load_dot_env():
+    """Load .env from the repo root (adgine-geo-skills/) into os.environ.
+
+    Resolved relative to this file's location, so it works regardless of the
+    agent's working directory (e.g. Hermes, OpenClaw, or any other runtime).
+    Existing environment variables are never overwritten.
+    """
+    if os.environ.get("GEO_API_KEY"):
+        return
+    # _client.py is at <repo_root>/adgine-geo-<skill>/scripts/_client.py
+    repo_root = os.path.dirname(
+        os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+    )
+    env_path = os.path.join(repo_root, ".env")
+    if not os.path.isfile(env_path):
+        return
+    with open(env_path) as _f:
+        for _line in _f:
+            _line = _line.strip()
+            if not _line or _line.startswith("#") or "=" not in _line:
+                continue
+            _k, _, _v = _line.partition("=")
+            _k = _k.strip()
+            _v = _v.strip()
+            if _k and _k not in os.environ:
+                os.environ[_k] = _v
+
+
+_load_dot_env()
+
+_VERSION_UNCHECKED = object()
+_version_state = _VERSION_UNCHECKED
+
+
+def _repo_root():
+    return os.path.dirname(
+        os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+    )
+
+
+def _load_check_version_module():
+    import importlib.util
+    path = os.path.join(_repo_root(), "scripts", "check_version.py")
+    if not os.path.isfile(path):
+        return None
+    spec = importlib.util.spec_from_file_location("geo_check_version", path)
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+    return mod
+
+
+def _load_version_state():
+    global _version_state
+    if _version_state is not _VERSION_UNCHECKED:
+        return _version_state
+    _version_state = None
+    try:
+        mod = _load_check_version_module()
+        if mod is not None:
+            _version_state = mod.get_state()
+    except Exception:
+        pass
+    return _version_state
+
+
+def _print_version_notice():
+    """Emit machine + human hints at import if a newer version exists."""
+    state = _load_version_state()
+    if not state or not state.get("update_available"):
+        return
+    cur, lat = state["current"], state["latest"]
+    try:
+        mod = _load_check_version_module()
+        if mod is not None:
+            inline = mod.format_user_inline(state)
+            if inline:
+                sys.stdout.write(inline + "\n\n")
+                sys.stdout.flush()
+    except Exception:
+        pass
+    if state.get("install_type") == "git":
+        msg = (f"adgine-geo-skills {lat} available (current {cur}). "
+               "Tell me: 请帮我更新 adgine-geo-skills 到最新版本")
+    else:
+        msg = (f"adgine-geo-skills {lat} available (current {cur}). "
+               f"Download: {state.get('release_url', '')}")
+    notice = {"update": {"current": cur, "latest": lat, "message": msg}}
+    try:
+        line = f"_notice: {json.dumps(notice, ensure_ascii=False)}\n\n"
+        sys.stdout.write(line)
+        sys.stdout.flush()
+    except Exception:
+        pass
+
+
+def _print_version_footer():
+    """Emit human-readable footer at process exit (WorkBuddy-compatible)."""
+    state = _load_version_state()
+    if not state or not state.get("update_available"):
+        return
+    try:
+        mod = _load_check_version_module()
+        if mod is None:
+            return
+        footer = mod.format_user_footer(state)
+        if footer:
+            sys.stdout.write("\n" + footer + "\n")
+            sys.stdout.flush()
+    except Exception:
+        pass
+
+
+_print_version_notice()
+atexit.register(_print_version_footer)
+
+
+def get_api_config():
+    """Read GEO_API_KEY and GEO_API_BASE_URL from environment.
+
+    Exits with a helpful message if GEO_API_KEY is not set.
+    Returns (key, base_url).
+    """
+    key = os.environ.get("GEO_API_KEY", "")
+    base = os.environ.get("GEO_API_BASE_URL", "https://platform.adgine.ai").rstrip("/")
+    if not key:
+        repo_root = os.path.dirname(
+            os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+        )
+        env_path = os.path.join(repo_root, ".env")
+        example_path = os.path.join(repo_root, ".env.example")
+        setup_path = os.path.join(repo_root, "setup.py")
+        print("ERROR: GEO_API_KEY is not set.")
+        print(f"  Expected location: {env_path}")
+        print()
+        print("  One-shot fix (recommended):")
+        print(f"    python3 {setup_path} <YOUR_KEY>")
+        print()
+        print("  Or set it manually:")
+        if not os.path.isfile(env_path):
+            print(f"    cp {example_path} {env_path}")
+        print(f"    edit {env_path} and set GEO_API_KEY=geo_sk_live_xxx")
+        print()
+        print("  Get your key at: https://platform.adgine.ai")
+        print("  The .env file is gitignored — your key stays local and private.")
+        print()
+        print("  NOTE: adgine-geo-site-audit does NOT require an API key.")
+        print("    Run directly: python3 adgine-geo-site-audit/scripts/geo_collect.py <url>")
+        sys.exit(1)
+    return key, base
+
+
+def get_project_id(arg_value=None):
+    """Resolve project ID from argument or GEO_PROJECT_ID env var.
+
+    Exits with instructions if neither is set.
+    """
+    pid = arg_value or os.environ.get("GEO_PROJECT_ID", "")
+    if not pid:
+        print("ERROR: Project ID is required but not set.")
+        print("  Option 1: export GEO_PROJECT_ID=<project-id>")
+        print("  Option 2: pass --project-id <id> to this script")
+        print("  Run list_projects.py from the adgine-geo-projects skill to see your available projects.")
+        sys.exit(1)
+    return pid
+
+
+def _do_request(method, url, key, body=None, timeout=30):
+    """Execute an HTTP request and return parsed JSON.
+
+    Exits with an error message on HTTP errors or network failures.
+    """
+    data = json.dumps(body).encode("utf-8") if body is not None else None
+    headers = {
+        "Authorization": f"Bearer {key}",
+        "Content-Type": "application/json",
+        "Accept": "application/json",
+        "User-Agent": "geo-skills/1.0",
+    }
+    request = _req.Request(url, data=data, headers=headers, method=method)
+    try:
+        with _req.urlopen(request, timeout=timeout) as resp:
+            raw = resp.read().decode("utf-8")
+            return json.loads(raw) if raw else {}
+    except _uerr.HTTPError as e:
+        raw = e.read().decode("utf-8")[:400]
+        try:
+            err_data = json.loads(raw)
+            msg = err_data.get("message") or err_data.get("detail") or raw
+        except Exception:
+            msg = raw
+        if e.code == 401:
+            print("ERROR: Unauthorized — API key is invalid or revoked.")
+            print("  Generate a new key: https://platform.adgine.ai")
+        elif e.code == 403:
+            print("ERROR: Forbidden — insufficient permissions for this operation.")
+        elif e.code == 404:
+            print(f"ERROR: Not found — {msg}")
+        else:
+            print(f"ERROR: HTTP {e.code} — {msg}")
+        sys.exit(1)
+    except Exception as e:
+        print(f"ERROR: Request failed — {e}")
+        sys.exit(1)
+
+
+def api_get(path, key, base, params=None, timeout=30):
+    url = f"{base}{path}"
+    if params:
+        clean = {k: str(v) for k, v in params.items() if v is not None}
+        if clean:
+            url += "?" + _up.urlencode(clean)
+    return _do_request("GET", url, key, timeout=timeout)
+
+
+def api_post(path, key, base, body=None, timeout=30):
+    return _do_request("POST", f"{base}{path}", key, body, timeout=timeout)
+
+
+def api_patch(path, key, base, body=None, timeout=30):
+    return _do_request("PATCH", f"{base}{path}", key, body, timeout=timeout)
+
+
+def api_put(path, key, base, body=None, timeout=30):
+    return _do_request("PUT", f"{base}{path}", key, body, timeout=timeout)
+
+
+def api_delete(path, key, base, timeout=30):
+    return _do_request("DELETE", f"{base}{path}", key, timeout=timeout)
+
+
+def extract_data(result):
+    """Extract the .data field from a standard geo-api envelope response.
+
+    On success the API returns {"code": 0, "data": <payload>, "message": "ok"}.
+    On non-zero code, this prints the message and exits(1).
+    """
+    if not isinstance(result, dict):
+        return result
+    if "code" in result and result.get("code") not in (0, None):
+        msg = result.get("message") or result.get("detail") or "request failed"
+        print(f"ERROR: API returned code={result.get('code')} — {msg}")
+        sys.exit(1)
+    return result.get("data", result)
+
+
+def poll_job(status_path, key, base, interval=3, max_wait=300,
+             terminal=("completed", "failed", "done", "success", "error")):
+    """Poll a job/task endpoint until it reaches a terminal state.
+
+    Prints an inline spinner with the current phase. Returns the final job dict.
+    """
+    elapsed = 0
+    frames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"]
+    idx = 0
+    last_job = {}
+    while elapsed < max_wait:
+        result = api_get(status_path, key, base)
+        last_job = extract_data(result) or {}
+        status = (last_job.get("status") or "").lower()
+        phase = last_job.get("current_phase") or last_job.get("phase") or status or "pending"
+        print(f"\r  {frames[idx % len(frames)]} {phase}... ({elapsed}s)", end="", flush=True)
+        idx += 1
+        if status in terminal:
+            print()  # newline after spinner
+            return last_job
+        time.sleep(interval)
+        elapsed += interval
+    print()
+    print(f"WARNING: Job is still running after {max_wait}s. Check status manually.")
+    return last_job
+
+
+def print_json(data):
+    """Print data as formatted JSON (UTF-8 safe)."""
+    print(json.dumps(data, ensure_ascii=False, indent=2))
+
+
+def fmt_change(value):
+    """Format a numeric change indicator per CONVENTIONS.md §4.
+
+    Returns: '+N' / '-N' / '0' / '--' (None becomes '--').
+    """
+    if value is None:
+        return "--"
+    try:
+        n = float(value)
+    except (TypeError, ValueError):
+        return "--"
+    if n == 0:
+        return "0"
+    sign = "+" if n > 0 else ""
+    if n == int(n):
+        return f"{sign}{int(n):,}"
+    return f"{sign}{n:,.1f}"
+
+
+def truncate(text, n=60, ellipsis="…"):
+    """Truncate text to n characters, adding ellipsis if cut. ASCII-safe for tables."""
+    if text is None:
+        return "--"
+    s = str(text)
+    if len(s) <= n:
+        return s
+    return s[: max(0, n - len(ellipsis))] + ellipsis
+
+def display_width(s):
+    """Return the display width of a string (CJK chars count as 2 columns)."""
+    w = 0
+    for c in str(s):
+        eaw = unicodedata.east_asian_width(c)
+        w += 2 if eaw in ('W', 'F') else 1
+    return w
+
+
+def pad(s, width, align='left'):
+    """Pad string to display width for CJK-aware table alignment.
+    Replaces f'{s:<N}' (align='left') and f'{s:>N}' (align='right').
+    """
+    s = str(s)
+    dw = display_width(s)
+    spaces = max(0, width - dw) * ' '
+    return spaces + s if align == 'right' else s + spaces

package/skills/adgine-geo-integrations/scripts/cloudflare_connect.py

@@ -0,0 +1,155 @@
+#!/usr/bin/env python3
+"""Cloudflare: token connect, zone discovery, traffic sync & overview.
+
+Subcommands:
+  list-zones --token <api_token>   — list zones accessible by a given API token
+  connect    --token <api_token>   — connect Cloudflare (saves token, auto-matches zone)
+  sync                             — pull latest Cloudflare analytics into local DB
+  overview   [--start <>] [--end <>] — Cloudflare traffic overview + daily trend
+
+Worker management (AI-traffic tracking) lives in cloudflare_worker.py.
+
+Usage:
+  python3 scripts/cloudflare_connect.py list-zones --token <cf_api_token>
+  python3 scripts/cloudflare_connect.py connect --token <cf_api_token>
+  python3 scripts/cloudflare_connect.py sync
+  python3 scripts/cloudflare_connect.py overview --start 2025-11-01
+"""
+import sys
+import os
+import argparse
+
+sys.path.insert(0, os.path.dirname(__file__))
+from _client import (
+    get_api_config, get_project_id,
+    api_get, api_post,
+    extract_data, print_json, truncate,
+    pad,
+)
+
+def _fmt_num(n):
+    if n is None:
+        return "--"
+    try:
+        f = float(n)
+        if f == int(f):
+            return f"{int(f):,}"
+        return f"{f:,.1f}"
+    except (TypeError, ValueError):
+        return str(n)
+
+
+def cmd_list_zones(args, key, base, pid):
+    result = api_post(f"/api/projects/{pid}/integrations/cloudflare/list-zones", key, base,
+                      body={"api_token": args.token})
+    data = extract_data(result)
+    items = data if isinstance(data, list) else (data or {}).get("zones", [])
+    if args.json:
+        print_json(items)
+        return
+    if not items:
+        print("No zones accessible with that token.")
+        return
+    print(f"Cloudflare zones ({len(items)})")
+    print()
+    print("```")
+    print("┌──────────────────────┬────────────────────────────┐")
+    print("│ Zone ID              │ Name                       │")
+    print("├──────────────────────┼────────────────────────────┤")
+    for z in items:
+        zid = truncate(z.get("id") or z.get("zone_id"), 20)
+        name = truncate(z.get("name") or z.get("domain"), 26)
+        print(f"│ {pad(zid, 20)} │ {pad(name, 26)} │")
+    print("└──────────────────────┴────────────────────────────┘")
+    print("```")
+
+
+def cmd_connect(args, key, base, pid):
+    result = api_post(f"/api/projects/{pid}/integrations/cloudflare/connect", key, base,
+                      body={"api_token": args.token})
+    data = extract_data(result) or {}
+    if args.json:
+        print_json(data)
+        return
+    print("Cloudflare connected.")
+    for k in ("zone_id", "zone_name", "account_id"):
+        if k in data:
+            print(f"  {k}: {data.get(k)}")
+
+
+def cmd_sync(args, key, base, pid):
+    result = api_post(f"/api/projects/{pid}/integrations/cloudflare/sync", key, base)
+    data = extract_data(result) or {}
+    if args.json:
+        print_json(data)
+        return
+    print("Cloudflare sync started.")
+    for k in ("status", "rows_synced", "started_at"):
+        if k in data:
+            print(f"  {k}: {data.get(k)}")
+
+
+def cmd_overview(args, key, base, pid):
+    params = {}
+    if args.start:
+        params["start_date"] = args.start
+    if args.end:
+        params["end_date"] = args.end
+    result = api_get(f"/api/projects/{pid}/integrations/cloudflare/overview", key, base,
+                     params=params or None)
+    data = extract_data(result) or {}
+    if args.json:
+        print_json(data)
+        return
+    print("Cloudflare Overview")
+    print()
+    print("```")
+    print("┌────────────────────┬──────────────┐")
+    print("│ Metric             │        Value │")
+    print("├────────────────────┼──────────────┤")
+    for k, label in [
+        ("total_requests", "Total requests"),
+        ("bandwidth", "Bandwidth"),
+        ("page_views", "Page views"),
+        ("unique_visitors", "Unique visitors"),
+        ("threats_blocked", "Threats blocked"),
+    ]:
+        if k in data:
+            print(f"│ {pad(label, 18)} │ {_fmt_num(data.get(k)):>12} │")
+    print("└────────────────────┴──────────────┘")
+    print("```")
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Cloudflare connection & traffic queries")
+    parser.add_argument("--project-id", help="Project ID (or set GEO_PROJECT_ID env var)")
+    parser.add_argument("--json", action="store_true", help="Output raw JSON")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_lz = sub.add_parser("list-zones")
+    p_lz.add_argument("--token", required=True, help="Cloudflare API token")
+
+    p_c = sub.add_parser("connect")
+    p_c.add_argument("--token", required=True, help="Cloudflare API token")
+
+    sub.add_parser("sync")
+
+    p_o = sub.add_parser("overview")
+    p_o.add_argument("--start", help="Start date YYYY-MM-DD")
+    p_o.add_argument("--end", help="End date YYYY-MM-DD")
+
+    args = parser.parse_args()
+    key, base = get_api_config()
+    pid = get_project_id(args.project_id)
+
+    handlers = {
+        "list-zones": cmd_list_zones,
+        "connect": cmd_connect,
+        "sync": cmd_sync,
+        "overview": cmd_overview,
+    }
+    handlers[args.command](args, key, base, pid)
+
+
+if __name__ == "__main__":
+    main()