ivon-cli 0.1.0__py3-none-any.whl

ivon_cli/__init__.py

@@ -0,0 +1,3 @@
+"""ivon CLI."""
+
+__version__ = "0.1.0"

ivon_cli/api.py

@@ -0,0 +1,266 @@
+"""Thin HTTPS client for the ivon Meta Ads connector API.
+
+Layers:
+
+  * ``ApiError`` / ``NotLoggedIn`` / ``TransportError`` — exception types
+    the command layer maps to exit codes.
+  * device-flow helpers (no auth) — start + poll the CLI login.
+  * ``McpClient`` — JSON-RPC 2.0 client for the hosted MCP server's
+    streamable-http endpoint (/mcp). The ivon API token rides in the
+    Authorization header; the server resolves it to the user's connected
+    Facebook Ads token per request.
+
+The CLI is synchronous by design.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import time
+from contextlib import contextmanager
+from dataclasses import dataclass
+from typing import Any, Iterator, Optional
+
+import httpx
+
+from . import __version__
+from .config import Credentials, api_url, load_credentials
+
+DEFAULT_TIMEOUT = httpx.Timeout(300.0, connect=15.0)
+USER_AGENT = f"ivon-cli/{__version__}"
+DEFAULT_HEADERS = {"User-Agent": USER_AGENT}
+
+# Strip C0 + DEL + select C1 control chars from server-supplied error strings
+# before echoing, so a hostile endpoint can't inject ANSI escape sequences.
+_CONTROL_CHAR_RE = re.compile(r"[\x00-\x08\x0b-\x1f\x7f-\x9f]")
+
+
+def _scrub(s: str) -> str:
+    return _CONTROL_CHAR_RE.sub("?", s)
+
+
+class ApiError(Exception):
+    """HTTP-shaped error from the ivon API."""
+
+    def __init__(self, status: int, body: Any):
+        self.status = status
+        self.body = body
+        super().__init__(self._human(body))
+
+    @staticmethod
+    def _human(body: Any) -> str:
+        raw = ""
+        if isinstance(body, dict):
+            raw = str(
+                body.get("error_description")
+                or body.get("message")
+                or body.get("error")
+                or body
+            )
+        if not raw:
+            raw = str(body)
+        return _scrub(raw)
+
+
+class NotLoggedIn(Exception):
+    """No usable credentials on disk — caller should run `ivon auth login`."""
+
+
+class TransportError(Exception):
+    """Network-level failure (DNS, refused connection, read timeout)."""
+
+
+@contextmanager
+def raw_client(base: Optional[str] = None) -> Iterator[httpx.Client]:
+    base_url = (base or api_url()).rstrip("/")
+    with httpx.Client(
+        base_url=base_url,
+        timeout=DEFAULT_TIMEOUT,
+        headers=DEFAULT_HEADERS,
+    ) as cx:
+        yield cx
+
+
+def _decode(resp: httpx.Response) -> Any:
+    if not resp.content:
+        return None
+    try:
+        return resp.json()
+    except ValueError:
+        return resp.text
+
+
+def _check(resp: httpx.Response) -> Any:
+    if resp.status_code >= 400:
+        raise ApiError(resp.status_code, _decode(resp))
+    return _decode(resp)
+
+
+# ---------------------------------------------------------------------------
+# Device-flow helpers (no auth required)
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class DeviceStart:
+    device_code: str
+    user_code: str
+    verification_uri: str
+    verification_uri_complete: str
+    interval: int
+    expires_in: int
+
+
+def device_flow_start() -> DeviceStart:
+    try:
+        with raw_client() as cx:
+            data = _check(cx.post("/cli/auth/device/start"))
+    except httpx.RequestError as exc:
+        raise TransportError(f"cannot reach {api_url()}: {type(exc).__name__}: {exc}") from exc
+    return DeviceStart(**{k: data[k] for k in DeviceStart.__dataclass_fields__})
+
+
+def device_flow_poll_once(device_code: str) -> Optional[dict]:
+    """Single poll. Returns credentials dict on success, None if pending."""
+    try:
+        with raw_client() as cx:
+            resp = cx.get("/cli/auth/device/poll", params={"device_code": device_code})
+    except httpx.RequestError as exc:
+        raise TransportError(f"cannot reach {api_url()}: {type(exc).__name__}: {exc}") from exc
+    if resp.status_code == 200:
+        return resp.json()
+    body = _decode(resp)
+    if isinstance(body, dict) and body.get("error") == "authorization_pending":
+        return None
+    raise ApiError(resp.status_code, body)
+
+
+def device_flow_wait(device_code: str, interval: int, deadline_s: int = 600) -> dict:
+    """Block until the API token is released or the device code expires."""
+    interval = max(1, int(interval))
+    start = time.time()
+    while True:
+        result = device_flow_poll_once(device_code)
+        if result is not None:
+            return result
+        if time.time() - start > deadline_s:
+            raise ApiError(408, {"error": "expired", "error_description": "Polling deadline reached"})
+        time.sleep(interval)
+
+
+# ---------------------------------------------------------------------------
+# MCP client (JSON-RPC 2.0 over streamable HTTP)
+# ---------------------------------------------------------------------------
+
+
+def _resolve_effective_target(creds: Credentials) -> Credentials:
+    """Refuse to send the saved token to a host it wasn't issued against."""
+    import os as _os
+    import sys as _sys
+    from urllib.parse import urlparse as _urlparse
+
+    env_url = (_os.environ.get("IVON_API_URL") or "").rstrip("/")
+    if not env_url or env_url == creds.api_url.rstrip("/"):
+        return creds
+
+    host = (_urlparse(env_url).hostname or "").lower()
+    loopback = host in ("localhost", "127.0.0.1", "::1") or host.endswith(".localhost")
+    allowed = _os.environ.get("IVON_ALLOW_CUSTOM_API", "") == "1"
+    if not (loopback or allowed):
+        raise ApiError(
+            0,
+            f"IVON_API_URL={env_url} differs from the host you are logged into "
+            f"({creds.api_url}). Refusing to send your saved token to a different "
+            "host. Re-run `ivon auth login` against it, unset IVON_API_URL, or "
+            "set IVON_ALLOW_CUSTOM_API=1 if intentional.",
+        )
+    print(
+        f"ivon: targeting {env_url} (IVON_API_URL override; logged into {creds.api_url})",
+        file=_sys.stderr,
+    )
+    return Credentials(api_token=creds.api_token, email=creds.email, api_url=env_url)
+
+
+class McpClient:
+    """JSON-RPC 2.0 client for the hosted ivon Meta Ads MCP server."""
+
+    def __init__(self, creds: Credentials, timeout_seconds: Optional[float] = None):
+        self.creds = creds
+        timeout = (
+            httpx.Timeout(float(timeout_seconds), connect=15.0)
+            if timeout_seconds is not None
+            else DEFAULT_TIMEOUT
+        )
+        self._cx = httpx.Client(
+            base_url=creds.api_url.rstrip("/"),
+            timeout=timeout,
+            headers={
+                **DEFAULT_HEADERS,
+                "Authorization": f"Bearer {creds.api_token}",
+                "Content-Type": "application/json",
+                "Accept": "application/json, text/event-stream",
+            },
+        )
+        self._next_id = 1
+
+    def close(self) -> None:
+        self._cx.close()
+
+    def __enter__(self) -> "McpClient":
+        return self
+
+    def __exit__(self, *exc) -> None:
+        self.close()
+
+    @classmethod
+    def from_disk(cls, timeout_seconds: Optional[float] = None) -> "McpClient":
+        creds = load_credentials()
+        if not creds:
+            raise NotLoggedIn("No credentials found — run `ivon auth login` first.")
+        creds = _resolve_effective_target(creds)
+        return cls(creds, timeout_seconds=timeout_seconds)
+
+    def rpc(self, method: str, params: Optional[dict] = None) -> Any:
+        body = {"jsonrpc": "2.0", "method": method, "id": self._next_id}
+        if params is not None:
+            body["params"] = params
+        self._next_id += 1
+        try:
+            resp = self._cx.post("/mcp", json=body)
+        except httpx.RequestError as exc:
+            raise TransportError(
+                f"cannot reach {self._cx.base_url}: {type(exc).__name__}: {exc}"
+            ) from exc
+        if resp.status_code == 401:
+            raise NotLoggedIn(
+                "The server rejected your ivon API token — it may have been "
+                "regenerated. Run `ivon auth login` again."
+            )
+        data = _check(resp)
+        if isinstance(data, dict) and data.get("error"):
+            raise ApiError(resp.status_code, data["error"])
+        return data.get("result") if isinstance(data, dict) else data
+
+    # Higher-level wrappers ---------------------------------------------
+
+    def tools_list(self) -> list:
+        result = self.rpc("tools/list")
+        return result.get("tools", []) if isinstance(result, dict) else []
+
+    def tools_call(self, name: str, arguments: Optional[dict] = None) -> Any:
+        result = self.rpc("tools/call", {"name": name, "arguments": arguments or {}})
+        return result
+
+    def tool_text(self, name: str, arguments: Optional[dict] = None) -> Any:
+        """Call a tool and return its text payload, JSON-decoded when possible."""
+        result = self.tools_call(name, arguments)
+        if not isinstance(result, dict):
+            return result
+        content = result.get("content") or []
+        texts = [c.get("text", "") for c in content if c.get("type") == "text"]
+        joined = "\n".join(t for t in texts if t)
+        try:
+            return json.loads(joined)
+        except (ValueError, TypeError):
+            return joined or result

ivon_cli/cmds/auth.py

@@ -0,0 +1,116 @@
+"""`ivon auth` — login / logout / status via the device-code flow."""
+
+from __future__ import annotations
+
+import os
+import webbrowser
+
+import typer
+
+from ..api import McpClient, NotLoggedIn, device_flow_start, device_flow_wait
+from ..config import (
+    Credentials,
+    api_url,
+    clear_credentials,
+    credentials_path,
+    is_default_api_url,
+    is_loopback_url,
+    is_safe_custom_api_url,
+    load_credentials,
+)
+
+app = typer.Typer(help="Authenticate the ivon CLI.")
+
+
+@app.command()
+def login(
+    allow_custom_api: bool = typer.Option(
+        False,
+        "--allow-custom-api",
+        help="Permit logging in against a non-default IVON_API_URL endpoint.",
+    ),
+) -> None:
+    """Log in via your browser (Google sign-in on ivon.ai)."""
+    target = api_url()
+    if not is_default_api_url():
+        # Loopback is the documented local-dev flow — allow with a notice.
+        # Anything else is the endpoint-phishing vector: require https plus
+        # an explicit opt-in before sending a fresh login there.
+        if is_loopback_url(target):
+            typer.secho(f"ivon: logging in against local endpoint {target}", err=True)
+        else:
+            allowed = allow_custom_api or os.environ.get("IVON_ALLOW_CUSTOM_API", "") == "1"
+            if not is_safe_custom_api_url(target) or not allowed:
+                typer.secho(
+                    f"ivon: refusing to authenticate against custom endpoint {target}.\n"
+                    "Pass --allow-custom-api (or set IVON_ALLOW_CUSTOM_API=1) if this "
+                    "is intentional.",
+                    fg=typer.colors.RED,
+                    err=True,
+                )
+                raise typer.Exit(code=4)
+            typer.secho(f"ivon: logging in against custom endpoint {target}", err=True)
+
+    start = device_flow_start()
+    typer.echo("To sign in, open this URL in your browser:")
+    typer.secho(f"  {start.verification_uri_complete}", fg=typer.colors.CYAN)
+    typer.echo("and confirm this one-time code:")
+    typer.secho(f"  {start.user_code}", fg=typer.colors.GREEN, bold=True)
+    try:
+        webbrowser.open(start.verification_uri_complete)
+    except Exception:
+        pass  # best-effort; the URL is printed above
+
+    typer.echo("Waiting for approval…")
+    result = device_flow_wait(start.device_code, interval=start.interval, deadline_s=start.expires_in)
+
+    creds = Credentials(
+        api_token=result["api_token"],
+        email=result.get("email", ""),
+        api_url=target,
+    )
+    from ..config import save_credentials
+
+    save_credentials(creds)
+    typer.secho(f"Logged in as {creds.email or '(unknown)'}", fg=typer.colors.GREEN)
+    typer.echo(f"Credentials saved to {credentials_path()}")
+
+
+@app.command()
+def logout() -> None:
+    """Remove the saved credentials from this machine."""
+    if clear_credentials():
+        typer.echo("Logged out — credentials removed.")
+    else:
+        typer.echo("No credentials were stored.")
+
+
+@app.command()
+def status() -> None:
+    """Show who you're logged in as and whether Facebook Ads is connected."""
+    creds = load_credentials()
+    if not creds:
+        typer.echo("Not logged in. Run `ivon auth login`.")
+        raise typer.Exit(code=4)
+    typer.echo(f"Logged in as: {creds.email or '(unknown)'}")
+    typer.echo(f"API endpoint: {creds.api_url}")
+    typer.echo(f"API token:    {creds.api_token[:12]}…")
+    try:
+        with McpClient.from_disk(timeout_seconds=30) as client:
+            info = client.tool_text("get_login_link")
+        if isinstance(info, dict):
+            method = info.get("authentication_method", "")
+            if "Already" in str(info.get("message", "")):
+                fb = info.get("facebook_user")
+                typer.secho(
+                    f"Facebook Ads: connected{f' ({fb})' if fb else ''}",
+                    fg=typer.colors.GREEN,
+                )
+            else:
+                url = info.get("login_url") or info.get("sign_in_url") or ""
+                typer.secho("Facebook Ads: not connected", fg=typer.colors.YELLOW)
+                if url:
+                    typer.echo(f"Connect at:   {url}")
+    except NotLoggedIn as exc:
+        typer.secho(f"Token check failed: {exc}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=4)

ivon_cli/cmds/install.py

@@ -0,0 +1,72 @@
+"""`ivon install skill` — drop the ivon Meta Ads agent guide into a project.
+
+The usage guide bundled in the wheel (data/ivon_meta_ads_skill.md) is
+written where each agent runner natively discovers it:
+
+  .claude/skills/ivon-meta-ads/SKILL.md   Claude Code skill (frontmatter kept)
+  .codex/prompts/ivon-meta-ads.md         Codex prompt → /ivon-meta-ads
+  .agents/ivon-meta-ads.md                generic agent guide (plain markdown)
+
+Default target is the current directory; pass --path to install elsewhere
+(e.g. `ivon install skill --path ~` for a user-global install).
+
+The bundled copy is regenerated from .claude/skills/ivon-meta-ads/SKILL.md
+in the ivon repo (the canonical source) at release time.
+"""
+
+from __future__ import annotations
+
+from importlib import resources
+from pathlib import Path
+from typing import List, Optional, Tuple
+
+import typer
+
+app = typer.Typer(help="Install ivon agent assets locally.", no_args_is_help=True)
+
+# (label, relative target path, keep YAML frontmatter?)
+_TARGETS: List[Tuple[str, str, bool]] = [
+    ("Claude Code", ".claude/skills/ivon-meta-ads/SKILL.md", True),
+    ("Codex", ".codex/prompts/ivon-meta-ads.md", False),
+    ("Agents", ".agents/ivon-meta-ads.md", False),
+]
+
+
+def _bundled_skill() -> str:
+    return (
+        resources.files("ivon_cli")
+        .joinpath("data/ivon_meta_ads_skill.md")
+        .read_text(encoding="utf-8")
+    )
+
+
+def _strip_frontmatter(text: str) -> str:
+    """Drop a leading ----delimited YAML block (only Claude Code reads it)."""
+    if not text.startswith("---"):
+        return text
+    end = text.find("\n---", 3)
+    if end == -1:
+        return text
+    return text[end + 4 :].lstrip("\n")
+
+
+@app.command()
+def skill(
+    path: Optional[str] = typer.Option(
+        None, "--path", help="Directory to install into (default: current directory)."
+    ),
+) -> None:
+    """Install the ivon Meta Ads usage guide for Claude Code, Codex, and agents."""
+    root = Path(path).expanduser() if path else Path.cwd()
+    content = _bundled_skill()
+
+    for label, rel_path, keep_frontmatter in _TARGETS:
+        target = root / rel_path
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(
+            content if keep_frontmatter else _strip_frontmatter(content),
+            encoding="utf-8",
+        )
+        typer.secho(f"  {label:12} → {target}", fg=typer.colors.GREEN)
+
+    typer.echo("\nInstalled. Claude Code picks it up automatically; restart the session if open.")

ivon_cli/cmds/mcp.py

@@ -0,0 +1,52 @@
+"""`ivon mcp` — helpers for wiring the hosted MCP server into MCP clients."""
+
+from __future__ import annotations
+
+import json
+
+import typer
+
+from ..api import NotLoggedIn
+from ..config import load_credentials
+
+app = typer.Typer(help="MCP client configuration helpers.")
+
+
+@app.command()
+def config(
+    show_token: bool = typer.Option(
+        False,
+        "--show-token",
+        help="Embed your real API token (otherwise a placeholder is printed).",
+    ),
+) -> None:
+    """Print MCP client config for the hosted ivon Meta Ads server."""
+    creds = load_credentials()
+    if not creds:
+        raise NotLoggedIn("No credentials found — run `ivon auth login` first.")
+
+    token = creds.api_token if show_token else "<your ivon API token>"
+    url = f"{creds.api_url}/mcp"
+
+    typer.secho("# Claude Code", bold=True)
+    typer.echo(
+        f'claude mcp add --transport http ivon-meta-ads "{url}" '
+        f'--header "Authorization: Bearer {token}"'
+    )
+    typer.echo("")
+    typer.secho("# Claude Desktop / generic MCP client (mcpServers entry)", bold=True)
+    typer.echo(
+        json.dumps(
+            {
+                "ivon-meta-ads": {
+                    "type": "http",
+                    "url": url,
+                    "headers": {"Authorization": f"Bearer {token}"},
+                }
+            },
+            indent=2,
+        )
+    )
+    if not show_token:
+        typer.echo("")
+        typer.echo("Your token is on https://ivon.ai/profile — or rerun with --show-token.")

ivon_cli/cmds/meta.py

@@ -0,0 +1,135 @@
+"""`ivon meta` — Meta Ads commands wrapping the hosted MCP server's tools.
+
+Every subcommand is a thin shell over `tools/call` on the ivon Meta Ads MCP
+server. `ivon meta tools` lists the full surface; `ivon meta call` invokes
+any tool generically with `-p key=value` params, so the CLI never lags the
+MCP server's capabilities.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, List, Optional
+
+import typer
+
+from ..api import McpClient
+
+app = typer.Typer(help="Meta (Facebook) Ads commands.")
+
+
+def _parse_params(params: List[str]) -> dict:
+    """Parse repeated -p key=value flags. Values parse as JSON when possible
+    (numbers, booleans, objects, arrays), else as strings."""
+    out: dict = {}
+    for raw in params:
+        if "=" not in raw:
+            raise typer.BadParameter(f"expected key=value, got {raw!r}")
+        key, value = raw.split("=", 1)
+        try:
+            out[key] = json.loads(value)
+        except ValueError:
+            out[key] = value
+    return out
+
+
+def _emit(result: Any) -> None:
+    if isinstance(result, (dict, list)):
+        typer.echo(json.dumps(result, indent=2))
+    else:
+        typer.echo(str(result))
+
+
+@app.command()
+def tools() -> None:
+    """List all tools exposed by the ivon Meta Ads MCP server."""
+    with McpClient.from_disk(timeout_seconds=60) as client:
+        for tool in client.tools_list():
+            desc = (tool.get("description") or "").strip().splitlines()
+            first = desc[0].strip() if desc else ""
+            typer.echo(f"{tool['name']:32}  {first}")
+
+
+@app.command()
+def call(
+    tool: str = typer.Argument(..., help="Tool name (see `ivon meta tools`)."),
+    params: List[str] = typer.Option(
+        [], "--param", "-p", help="Tool argument as key=value (value parsed as JSON when possible). Repeatable."
+    ),
+    timeout: float = typer.Option(300.0, "--timeout", help="Request timeout in seconds."),
+) -> None:
+    """Call any MCP tool generically."""
+    arguments = _parse_params(params)
+    with McpClient.from_disk(timeout_seconds=timeout) as client:
+        _emit(client.tool_text(tool, arguments))
+
+
+@app.command()
+def accounts(
+    limit: int = typer.Option(10, help="Maximum number of accounts to return."),
+) -> None:
+    """List the ad accounts your connected Facebook user can access."""
+    with McpClient.from_disk() as client:
+        _emit(client.tool_text("get_ad_accounts", {"limit": limit}))
+
+
+@app.command()
+def campaigns(
+    account: str = typer.Option(..., "--account", "-a", help="Ad account id (act_… prefix optional)."),
+    status: Optional[str] = typer.Option(None, help="Filter: ACTIVE, PAUSED, ARCHIVED…"),
+    limit: int = typer.Option(10, help="Maximum number of campaigns."),
+) -> None:
+    """List campaigns in an ad account."""
+    args: dict = {"account_id": account, "limit": limit}
+    if status:
+        args["status_filter"] = status
+    with McpClient.from_disk() as client:
+        _emit(client.tool_text("get_campaigns", args))
+
+
+@app.command()
+def adsets(
+    account: str = typer.Option(..., "--account", "-a", help="Ad account id."),
+    campaign: Optional[str] = typer.Option(None, "--campaign", "-c", help="Campaign id to filter by."),
+    limit: int = typer.Option(10, help="Maximum number of ad sets."),
+) -> None:
+    """List ad sets in an account (optionally for one campaign)."""
+    args: dict = {"account_id": account, "limit": limit}
+    if campaign:
+        args["campaign_id"] = campaign
+    with McpClient.from_disk() as client:
+        _emit(client.tool_text("get_adsets", args))
+
+
+@app.command()
+def ads(
+    account: str = typer.Option(..., "--account", "-a", help="Ad account id."),
+    campaign: Optional[str] = typer.Option(None, "--campaign", "-c", help="Campaign id to filter by."),
+    adset: Optional[str] = typer.Option(None, "--adset", help="Ad set id to filter by."),
+    limit: int = typer.Option(10, help="Maximum number of ads."),
+) -> None:
+    """List ads in an account (optionally for one campaign / ad set)."""
+    args: dict = {"account_id": account, "limit": limit}
+    if campaign:
+        args["campaign_id"] = campaign
+    if adset:
+        args["adset_id"] = adset
+    with McpClient.from_disk() as client:
+        _emit(client.tool_text("get_ads", args))
+
+
+@app.command()
+def insights(
+    object_id: str = typer.Argument(..., help="Account (act_…), campaign, ad set, or ad id."),
+    time_range: str = typer.Option("last_30d", "--time-range", "-t", help="Preset: today, yesterday, last_7d, last_30d, …"),
+    breakdown: Optional[str] = typer.Option(None, help="Optional breakdown, e.g. age, gender, country."),
+    level: Optional[str] = typer.Option(None, help="Aggregation level: ad, adset, campaign, account."),
+) -> None:
+    """Get performance insights for an account, campaign, ad set, or ad."""
+    args: dict = {"object_id": object_id, "time_range": time_range}
+    if breakdown:
+        args["breakdown"] = breakdown
+    if level:
+        args["level"] = level
+    with McpClient.from_disk() as client:
+        _emit(client.tool_text("get_insights", args))

ivon_cli/config.py

@@ -0,0 +1,127 @@
+"""ivon CLI — runtime config + on-disk credentials.
+
+Two responsibilities:
+
+  1. Resolve the API base URL (env override → Modal prod default).
+  2. Persist the ivon API token in `~/.ivon/credentials` with strict 0600
+     permissions, written atomically (tempfile + rename).
+
+**Security note** (mirrors the rgba CLI's V1/V4 review): ``IVON_API_URL``
+and ``IVON_CONFIG_DIR`` are honored as runtime overrides, but a hostile env
+could use either to phish a fresh login or redirect token storage. The
+login flow refuses non-default, non-loopback endpoints unless
+``IVON_ALLOW_CUSTOM_API=1`` is set, and authed calls refuse to send the
+saved token to a host other than the one it was issued against.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import stat
+import tempfile
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Optional
+from urllib.parse import urlparse
+
+# Default points at the deployed Modal app. Override at runtime with
+# IVON_API_URL=http://127.0.0.1:8765 for local development.
+DEFAULT_API_URL = "https://lemontree-media-llc--ivon-meta-ads-mcp-app.modal.run"
+
+
+def api_url() -> str:
+    return os.environ.get("IVON_API_URL", DEFAULT_API_URL).rstrip("/")
+
+
+def is_default_api_url() -> bool:
+    return api_url() == DEFAULT_API_URL
+
+
+def is_loopback_url(url: str) -> bool:
+    """True for localhost/127.0.0.1/::1 endpoints — the local-dev flow."""
+    host = (urlparse(url).hostname or "").lower()
+    return host in ("localhost", "127.0.0.1", "::1") or host.endswith(".localhost")
+
+
+def is_safe_custom_api_url(url: str) -> bool:
+    """Accept an explicit override only if it's https *or* loopback."""
+    parsed = urlparse(url)
+    if parsed.scheme not in ("http", "https"):
+        return False
+    if parsed.scheme == "https":
+        return True
+    return is_loopback_url(url)
+
+
+def config_dir() -> Path:
+    override = os.environ.get("IVON_CONFIG_DIR")
+    if override:
+        return Path(override)
+    return Path.home() / ".ivon"
+
+
+def credentials_path() -> Path:
+    return config_dir() / "credentials"
+
+
+@dataclass
+class Credentials:
+    api_token: str
+    email: str
+    api_url: str
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "Credentials":
+        return cls(
+            api_token=data["api_token"],
+            email=data.get("email", ""),
+            api_url=data.get("api_url", DEFAULT_API_URL),
+        )
+
+
+def load_credentials() -> Optional[Credentials]:
+    path = credentials_path()
+    if not path.exists():
+        return None
+    try:
+        with path.open("r") as f:
+            return Credentials.from_dict(json.load(f))
+    except (OSError, json.JSONDecodeError, KeyError):
+        # Corrupt or unreadable — treat as logged-out.
+        return None
+
+
+def save_credentials(creds: Credentials) -> None:
+    """Atomic 0600 write into ~/.ivon/credentials."""
+    config_dir().mkdir(parents=True, exist_ok=True)
+    target = credentials_path()
+    fd, tmp_path = tempfile.mkstemp(
+        prefix=".credentials.", dir=str(config_dir()), text=True
+    )
+    try:
+        with os.fdopen(fd, "w") as f:
+            json.dump(creds.to_dict(), f, indent=2)
+        os.chmod(tmp_path, stat.S_IRUSR | stat.S_IWUSR)  # 0600
+        os.replace(tmp_path, target)
+    except Exception:
+        try:
+            os.unlink(tmp_path)
+        except OSError:
+            pass
+        raise
+
+
+def clear_credentials() -> bool:
+    """Delete ~/.ivon/credentials. Returns True if a file was removed."""
+    path = credentials_path()
+    if not path.exists():
+        return False
+    try:
+        path.unlink()
+        return True
+    except OSError:
+        return False

ivon_cli/data/ivon_meta_ads_skill.md

@@ -0,0 +1,125 @@
+---
+name: ivon-meta-ads
+description: ivon Meta Ads connector — manage Facebook/Instagram ads via the `ivon` CLI or the hosted MCP server (37 tools; campaigns, ad sets, creatives, insights, targeting). Triggers: "facebook ads", "meta ads", "instagram ads", "launch a campaign", "ad performance / insights", "audience targeting", "use the ivon CLI".
+---
+
+# ivon Meta Ads connector
+
+One hosted MCP server (Modal) exposes the user's Facebook Ads account as 37
+tools. Two ways in: the `ivon` CLI (shell) or MCP (`/mcp` endpoint, Bearer
+auth). Both use the same long-lived ivon API token; the server resolves it
+to the user's connected Facebook token per request — you never handle
+Facebook credentials.
+
+## Install + auth
+
+```bash
+pip install ivon-cli            # or: pip install -e cli/  (from the ivon repo)
+
+ivon auth login                 # device flow → browser → Google sign-in on ivon.ai
+ivon auth status                # whoami + Facebook Ads connection state
+```
+
+If status says Facebook Ads is **not connected**, stop and send the user to
+https://ivon.ai/profile?tab=connectors — only they can grant ads access.
+Tool calls in that state return `{"error": {"type": "not_connected", ...}}`
+with the same URL; relay it, don't retry.
+
+## MCP client setup (alternative to the CLI)
+
+```bash
+ivon mcp config                 # prints ready-to-paste Claude Code / Desktop config
+# essentially:
+claude mcp add --transport http ivon-meta-ads \
+  "https://lemontree-media-llc--ivon-meta-ads-mcp-app.modal.run/mcp" \
+  --header "Authorization: Bearer <ivon API token>"
+```
+
+## Discover + call any tool
+
+The CLI is a thin wrapper over the MCP tools — these two commands reach the
+entire surface, so prefer them over guessing:
+
+```bash
+ivon meta tools                          # list all 37 tools (one line each)
+ivon meta call <tool> -p key=value …     # call any tool; values parse as JSON
+ivon meta call create_adset -p account_id=act_1 \
+  -p targeting='{"geo_locations":{"countries":["US"]}}' …
+```
+
+Convenience verbs for the common reads:
+
+```bash
+ivon meta accounts                              # ad accounts
+ivon meta campaigns -a act_123 [--status ACTIVE]
+ivon meta adsets -a act_123 [-c <campaign_id>]
+ivon meta ads -a act_123 [--adset <adset_id>]
+ivon meta insights act_123 -t last_7d [--breakdown age] [--level campaign]
+```
+
+## Tool map (by intent)
+
+| Intent | Tools |
+|---|---|
+| Orient | `get_ad_accounts`, `get_account_info`, `get_account_pages` |
+| Read structure | `get_campaigns`, `get_adsets`, `get_ads`, `get_*_details` |
+| Performance | `get_insights` (presets: today, yesterday, last_7d, last_30d, last_90d, maximum…; breakdowns: age, gender, country, publisher_platform…) |
+| Research audience | `search_interests`, `get_interest_suggestions`, `search_behaviors`, `search_demographics`, `search_geo_locations`, `estimate_audience_size` |
+| Build | `upload_ad_image`, `compute_image_crops`, `create_campaign`, `create_adset`, `create_ad_creative`, `create_ad` |
+| Operate | `update_campaign`, `update_adset`, `update_ad`, `update_ad_creative`, `create_budget_schedule` |
+| Inspect creative | `get_ad_creatives`, `get_creative_details`, `get_ad_image`, `get_image_by_hash`, `get_ad_video` |
+| Competitors | `search_ads_archive` (public Ad Library) |
+| Connection | `get_login_link` (status + connect URL) |
+
+## Launch workflow (the full chain)
+
+Order matters — each step needs an id from the previous one:
+
+```bash
+# 1. account + page identity
+ivon meta accounts                                   # → act_<id>
+ivon meta call get_account_pages -p account_id=act_X # → page_id (ads run under a Page)
+
+# 2. campaign (objective: OUTCOME_TRAFFIC | OUTCOME_SALES | OUTCOME_LEADS |
+#    OUTCOME_AWARENESS | OUTCOME_ENGAGEMENT | OUTCOME_APP_PROMOTION)
+ivon meta call create_campaign -p account_id=act_X -p name="Spring Sale" \
+  -p objective=OUTCOME_TRAFFIC                        # → campaign_id
+
+# 3. ad set — budget lives here unless the campaign got one (CBO)
+ivon meta call create_adset -p account_id=act_X -p campaign_id=<id> \
+  -p name="US broad" -p optimization_goal=LINK_CLICKS -p billing_event=IMPRESSIONS \
+  -p daily_budget=2000 -p targeting='{"geo_locations":{"countries":["US"]},"age_min":18}'
+
+# 4. creative — upload image first, then build under the Page
+ivon meta call upload_ad_image -p account_id=act_X -p image_url=https://…  # → hash
+ivon meta call create_ad_creative -p account_id=act_X -p page_id=<page_id> \
+  -p image_hash=<hash> -p message="Primary text" -p headline="Headline" \
+  -p link_url=https://example.com -p call_to_action_type=SHOP_NOW          # → creative_id
+
+# 5. ad
+ivon meta call create_ad -p account_id=act_X -p adset_id=<id> \
+  -p creative_id=<id> -p name="Spring Sale — img A"
+```
+
+## Hard rules
+
+- **Money is minor units**: `daily_budget=2000` = $20.00/day. Say the
+  dollar amount back to the user before creating anything with a budget.
+- **Everything is created PAUSED** by design. Activating spend
+  (`-p status=ACTIVE`, or `update_*` to ACTIVE) requires explicit user
+  confirmation — never activate on your own initiative.
+- **Destructive/spend changes** (status flips, budget changes, deletes):
+  confirm with the user first; read back what will change.
+- `special_ad_categories` is legally required for housing / credit /
+  employment / political ads — ask if the business could fall in one.
+- Creative content is mostly immutable once delivering: to change a live
+  ad's content, create a new creative and swap via
+  `update_ad -p creative_id=…`.
+
+## Errors you'll see
+
+- `not_connected` → user must connect at https://ivon.ai/profile?tab=connectors.
+- `code: 190` → Facebook session expired; same reconnect URL.
+- `code: 4/17/32` (rate limit) → wait a few minutes; don't hammer retries.
+- HTTP 401 from the server → bad/rotated ivon token: `ivon auth login` again
+  (tokens rotate when the user clicks Regenerate on ivon.ai/profile).

ivon_cli/exit_codes.py

@@ -0,0 +1,16 @@
+"""Exit codes for the ivon CLI.
+
+0  success
+1  API error (server returned an error body)
+2  usage error (Typer/Click handles this)
+3  transport error (DNS, refused connection, timeout)
+4  not logged in
+130 interrupted (Ctrl-C)
+"""
+
+OK = 0
+API_ERROR = 1
+USAGE = 2
+TRANSPORT = 3
+NOT_LOGGED_IN = 4
+INTERRUPTED = 130

ivon_cli/main.py

@@ -0,0 +1,67 @@
+"""ivon CLI entry point."""
+
+from __future__ import annotations
+
+import sys
+
+import typer
+
+from . import __version__
+from .api import ApiError, NotLoggedIn, TransportError
+from .cmds import auth as auth_cmds
+from .cmds import install as install_cmds
+from .cmds import mcp as mcp_cmds
+from .cmds import meta as meta_cmds
+from . import exit_codes
+
+app = typer.Typer(
+    name="ivon",
+    help="ivon — autonomous marketing team CLI. Meta Ads connector commands + MCP access.",
+    no_args_is_help=True,
+)
+
+app.add_typer(auth_cmds.app, name="auth")
+app.add_typer(meta_cmds.app, name="meta")
+app.add_typer(mcp_cmds.app, name="mcp")
+app.add_typer(install_cmds.app, name="install")
+
+
+@app.command()
+def me() -> None:
+    """Alias for `ivon auth status`."""
+    auth_cmds.status()
+
+
+@app.command()
+def version() -> None:
+    """Print the CLI version."""
+    typer.echo(f"ivon-cli {__version__}")
+
+
+def main() -> int:
+    try:
+        # With standalone_mode=False Click *returns* a command's Exit code
+        # instead of sys.exit()ing — propagate it.
+        result = app(standalone_mode=False)
+        return int(result) if isinstance(result, int) else exit_codes.OK
+    except typer.Exit as exc:
+        return int(exc.exit_code or 0)
+    except KeyboardInterrupt:
+        print("\nivon: interrupted", file=sys.stderr)
+        return exit_codes.INTERRUPTED
+    except NotLoggedIn as exc:
+        print(f"ivon: {exc}", file=sys.stderr)
+        return exit_codes.NOT_LOGGED_IN
+    except TransportError as exc:
+        print(f"ivon: {exc}", file=sys.stderr)
+        return exit_codes.TRANSPORT
+    except ApiError as exc:
+        print(f"ivon: {exc}", file=sys.stderr)
+        return exit_codes.API_ERROR
+    except typer.Abort:
+        print("\nivon: aborted", file=sys.stderr)
+        return exit_codes.INTERRUPTED
+
+
+if __name__ == "__main__":
+    sys.exit(main())

ivon_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,65 @@
+Metadata-Version: 2.4
+Name: ivon-cli
+Version: 0.1.0
+Summary: ivon CLI — Meta Ads connector commands + MCP access for the ivon autonomous marketing team
+Author: ivon (LemonTree Media)
+License: Proprietary
+Project-URL: Homepage, https://ivon.ai
+Project-URL: Documentation, https://ivon.ai/profile
+Keywords: ivon,meta,facebook,ads,mcp,cli
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: typer<1.0,>=0.12
+Requires-Dist: httpx<1.0,>=0.27
+
+# ivon CLI
+
+Command-line access to the ivon Meta Ads connector — the same hosted MCP
+server that powers ivon's agents, wrapped in human-friendly commands.
+
+## Install
+
+```bash
+pip install -e cli/          # from the repo root (or publish to PyPI later)
+```
+
+## Login
+
+```bash
+ivon auth login              # opens browser → Google sign-in on ivon.ai → done
+ivon auth status             # who am I + Facebook Ads connection state
+ivon auth logout
+```
+
+Credentials are stored in `~/.ivon/credentials` (0600). The token is your
+long-lived ivon API token — regenerate it on https://ivon.ai/profile to
+revoke all CLI / MCP access.
+
+## Meta Ads commands
+
+```bash
+ivon meta tools                                   # list every MCP tool
+ivon meta accounts                                # your ad accounts
+ivon meta campaigns -a act_123 --status ACTIVE
+ivon meta adsets -a act_123 -c <campaign_id>
+ivon meta ads -a act_123
+ivon meta insights act_123 -t last_7d --breakdown age
+ivon meta call create_campaign -p account_id=act_123 -p name="Spring Sale" \
+    -p objective=OUTCOME_TRAFFIC -p status=PAUSED
+```
+
+`ivon meta call <tool> -p key=value` reaches any tool on the server —
+values parse as JSON when possible (`-p limit=25`, `-p targeting='{"geo_locations":{"countries":["US"]}}'`).
+
+## MCP client setup
+
+```bash
+ivon mcp config              # prints Claude Code / Claude Desktop config
+ivon mcp config --show-token # same, with your real token embedded
+```
+
+## Environment overrides
+
+- `IVON_API_URL` — point at a different backend (loopback allowed for dev;
+  other hosts need `IVON_ALLOW_CUSTOM_API=1`).
+- `IVON_CONFIG_DIR` — credentials directory (default `~/.ivon`).

ivon_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+ivon_cli/__init__.py,sha256=uy6i4gNKlDS_vsyl0DoMm1siKnfKAf3YxsNFc6bzy2Q,39
+ivon_cli/api.py,sha256=bULbRr9JrwZ6HPlDHDeVsAUjUGoIS42VrQxMeSElyTM,9179
+ivon_cli/config.py,sha256=U_kddUZMNcTOjY4ctN66qvZb3mMmCHgzD4vUR0eYKsY,3722
+ivon_cli/exit_codes.py,sha256=1v9ZXtg9M3ftAZs1VJxm5RmadJeq25rvXmWfXm6efT0,313
+ivon_cli/main.py,sha256=lDc_laSUaY0G6D6zpAbCvphtf2jeaFnAJRDMxDurPeY,1864
+ivon_cli/cmds/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ivon_cli/cmds/auth.py,sha256=Ut0GapTPZgOQLyfqaqw6TiBXgY2gAXzJCAEexU0dvp8,4288
+ivon_cli/cmds/install.py,sha256=qt37iNp7r6OwEpKM3qYpuLkjOXagO7tMDB-gMADAq_E,2491
+ivon_cli/cmds/mcp.py,sha256=qU4dWKrGoDWOnJOQAZ9QwZCvCRzNgUDTg5wI6IYv4lY,1509
+ivon_cli/cmds/meta.py,sha256=lc0zs4mzdcJBYOMjfQ-OXzbwh9tzwDyfanVLgal_cHM,5081
+ivon_cli/data/ivon_meta_ads_skill.md,sha256=sz25XYhxOJRWWLhsDPyWyA62eYD7kaqJ5qq54Jyi1Vo,5950
+ivon_cli-0.1.0.dist-info/METADATA,sha256=sRvf5u5emXFFE629rLP7FOPIxBuCSr2xpZnzFAhyGOo,2148
+ivon_cli-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+ivon_cli-0.1.0.dist-info/entry_points.txt,sha256=D-6c0nBfOLJtIiV6VAMRQJm6dsI2uePhZF9wWhp_J30,44
+ivon_cli-0.1.0.dist-info/top_level.txt,sha256=ORVlPfIpN0cY9g946Mv-qtiaka1W8eot8la3yzK_KGs,9
+ivon_cli-0.1.0.dist-info/RECORD,,

ivon_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

ivon_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ivon = ivon_cli.main:main

ivon_cli-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+ivon_cli