klaviyo-cli 0.2.0__tar.gz

klaviyo_cli-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,15 @@
+name: CI
+on:
+  push: {branches: [main]}
+  pull_request:
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix: {python-version: ["3.11", "3.12", "3.13"]}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv python install ${{ matrix.python-version }}
+      - run: uv venv --python ${{ matrix.python-version }} && uv pip install -e ".[dev]"
+      - run: uv run pytest tests/ -v

klaviyo_cli-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,13 @@
+name: Publish to PyPI
+on:
+  release: {types: [published]}
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions: {id-token: write}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1

klaviyo_cli-0.2.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.egg-info/
+dist/
+.venv/
+.pytest_cache/
+.superpowers/

klaviyo_cli-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrew Beauchamp
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

klaviyo_cli-0.2.0/PKG-INFO

@@ -0,0 +1,169 @@
+Metadata-Version: 2.4
+Name: klaviyo-cli
+Version: 0.2.0
+Summary: Unofficial Klaviyo CLI: campaigns, segments, flows, metrics, scheduling. Built for humans and AI agents.
+Project-URL: Homepage, https://github.com/BeauchampAndrew/klaviyo-cli
+Project-URL: Issues, https://github.com/BeauchampAndrew/klaviyo-cli/issues
+Author-email: Andrew Beauchamp <andrew@bsandco.us>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,cli,ecommerce,email-marketing,klaviyo
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Communications :: Email
+Requires-Python: >=3.11
+Requires-Dist: click>=8.0
+Requires-Dist: requests>=2.28
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# klaviyo-cli
+
+A command-line interface for Klaviyo: campaigns, segments, flows, metrics, and scheduling. Built for humans and AI agents.
+
+```bash
+uvx --from klaviyo-cli klaviyo --help
+```
+
+No install needed. Or install it: `pipx install klaviyo-cli` or `uv tool install klaviyo-cli`. Requires Python 3.11+.
+
+Built and maintained by [BS&Co](https://bsandco.us), a retention marketing agency for eCommerce brands.
+
+> Unofficial. Not affiliated with, endorsed, or supported by Klaviyo, Inc.
+
+## Quickstart
+
+```bash
+export KLAVIYO_API_KEY=pk_...
+```
+
+Get a private API key from Klaviyo under Settings > API Keys. Read commands need read scopes; commands that change data (patch, schedule, create, upload) need write scopes.
+
+```bash
+klaviyo list-campaigns --days 30
+klaviyo account-health
+```
+
+## Using with Claude Code and AI agents
+
+`--json` is a global flag: put it before the command name for machine-readable output on any command:
+
+```bash
+klaviyo --json list-campaigns --days 30
+```
+
+Destructive Klaviyo operations are blocked at the CLI level. Klaviyo's DELETE endpoints for profiles, lists, segments, campaigns, and flows are not reachable through this tool, even via the raw `api` passthrough. Only template deletion is allowlisted (`transport.py`, `DELETE_ALLOWED_PATHS`). This is why it's safe to hand `klaviyo-cli` to an agent with a live API key: the agent can read anything and change campaign content, timing, and audiences, but it cannot delete subscriber data, segments, or send history. One command can stop mail going to real people: `suppress`. It deletes nothing, but because it halts sends it requires an explicit `--yes` flag or an interactive confirmation before it runs.
+
+Drop this in your repo's `CLAUDE.md` so an agent knows the tool exists:
+
+```markdown
+## Klaviyo
+Use the `klaviyo` CLI for Klaviyo data and actions (campaigns, segments,
+flows, metrics). Auth via KLAVIYO_API_KEY env var. Pass --json before the
+command for machine-readable output (e.g. `klaviyo --json list-campaigns`).
+Run `klaviyo --help` for the full command list.
+```
+
+## Command reference
+
+Run `klaviyo COMMAND --help` for full options on any command.
+
+### Campaigns
+| Command | Description |
+|---|---|
+| `list-campaigns` | List/filter campaigns by status, channel, and date (beyond name search) |
+| `search-campaigns` | Search campaigns by name |
+| `get-campaign` | Show details for a specific campaign |
+| `get-creative` | Dump a campaign's creative (subject + text/HTML) via its template |
+| `list-drafts` | List draft email campaigns for a client |
+| `patch-campaign` | Update campaign send time and/or audiences |
+| `schedule` | Schedule a campaign for sending |
+| `campaign-performance` | Show campaign revenue and engagement metrics |
+| `metrics` | Show sent campaigns for a client within a date window |
+
+### Segments
+| Command | Description |
+|---|---|
+| `list-audiences` | List all lists and segments for a client |
+| `search-segments` | Find segments by name keyword; shows a one-line definition summary |
+| `get-segment` | Show a segment's definition (conditions, metric IDs resolved) + count |
+| `segment-count` | Get profile count for a single segment (rate limited: 1/s, 15/min) |
+| `segment-sizes` | Show all segments with profile counts |
+| `create-segment` | Create a segment from a definition, guarding against duplicates |
+
+### Flows
+| Command | Description |
+|---|---|
+| `flows` | List all flows for a client, with optional sort and name search |
+| `get-flow` | Show a flow's basics in one call; `--definition` adds trigger, action chain, reentry |
+| `flow-detail` | Show full flow structure: trigger, filters, emails with subjects, delays, splits |
+| `flow-performance` | Show flow revenue and engagement metrics |
+| `create-flow` | Create a flow (in draft) from a definition, guarding against duplicates |
+
+### Profiles
+| Command | Description |
+|---|---|
+| `get-profile` | Look up a profile by email or ID; `--subscriptions` adds consent state and suppressions |
+| `segment-members` | List profiles in a segment: email, name, and when they joined |
+| `suppress` | Suppress profiles from email marketing in bulk (requires `--yes` or confirmation) |
+| `unsuppress` | Remove manual suppressions in bulk (never resubscribes anyone) |
+| `suppression-jobs` | List bulk suppression jobs (suppress + unsuppress) with status and counts |
+
+### Events
+| Command | Description |
+|---|---|
+| `push-event` | Push a custom event to a profile by email (creates the profile if needed) |
+| `events` | List recent events for a metric ID, newest first, with the profile attached |
+
+### Metrics
+| Command | Description |
+|---|---|
+| `account-health` | Show profiles count, lists, and metrics for a client |
+| `list-metrics` | List event metrics with their IDs and integration (ID<->name catalog) |
+| `form-performance` | Show pop-up/form views, submits, and submit rates |
+
+### SMS
+| Command | Description |
+|---|---|
+| `upload-sms` | Create an SMS campaign draft in Klaviyo |
+
+### Raw API
+| Command | Description |
+|---|---|
+| `api` | Raw API pass-through: `klaviyo api <METHOD> <path>` |
+
+That's 32 commands total.
+
+## Multi-account profiles
+
+For managing more than one Klaviyo account, put credentials in `~/.config/klaviyo-cli/config.toml`:
+
+```toml
+default_profile = "acme"
+
+[profiles.acme]
+api_key = "pk_acme_..."
+
+[profiles.other-brand]
+api_key = "pk_other_..."
+```
+
+Select a profile with `--profile` (or `-p`), or set `KLAVIYO_PROFILE`:
+
+```bash
+klaviyo --profile other-brand account-health
+KLAVIYO_PROFILE=other-brand klaviyo account-health
+```
+
+Precedence: an explicit `--profile` (or `KLAVIYO_PROFILE`) wins first. Otherwise `KLAVIYO_API_KEY` is used if set. Otherwise the CLI falls back to `default_profile` in the config file.
+
+Agencies running the CLI across many clients can go further and embed it: re-expose every command under a host CLI with per-client auth resolution, so `yourcli campaign-performance acme --days 30` resolves credentials for `acme` before the call. See the `wrap_with_account` and `build_host_group` docstrings in `src/klaviyo_cli/embed.py`.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+Built and maintained by [BS&Co](https://bsandco.us), a retention marketing agency for eCommerce brands.

klaviyo_cli-0.2.0/README.md

@@ -0,0 +1,147 @@
+# klaviyo-cli
+
+A command-line interface for Klaviyo: campaigns, segments, flows, metrics, and scheduling. Built for humans and AI agents.
+
+```bash
+uvx --from klaviyo-cli klaviyo --help
+```
+
+No install needed. Or install it: `pipx install klaviyo-cli` or `uv tool install klaviyo-cli`. Requires Python 3.11+.
+
+Built and maintained by [BS&Co](https://bsandco.us), a retention marketing agency for eCommerce brands.
+
+> Unofficial. Not affiliated with, endorsed, or supported by Klaviyo, Inc.
+
+## Quickstart
+
+```bash
+export KLAVIYO_API_KEY=pk_...
+```
+
+Get a private API key from Klaviyo under Settings > API Keys. Read commands need read scopes; commands that change data (patch, schedule, create, upload) need write scopes.
+
+```bash
+klaviyo list-campaigns --days 30
+klaviyo account-health
+```
+
+## Using with Claude Code and AI agents
+
+`--json` is a global flag: put it before the command name for machine-readable output on any command:
+
+```bash
+klaviyo --json list-campaigns --days 30
+```
+
+Destructive Klaviyo operations are blocked at the CLI level. Klaviyo's DELETE endpoints for profiles, lists, segments, campaigns, and flows are not reachable through this tool, even via the raw `api` passthrough. Only template deletion is allowlisted (`transport.py`, `DELETE_ALLOWED_PATHS`). This is why it's safe to hand `klaviyo-cli` to an agent with a live API key: the agent can read anything and change campaign content, timing, and audiences, but it cannot delete subscriber data, segments, or send history. One command can stop mail going to real people: `suppress`. It deletes nothing, but because it halts sends it requires an explicit `--yes` flag or an interactive confirmation before it runs.
+
+Drop this in your repo's `CLAUDE.md` so an agent knows the tool exists:
+
+```markdown
+## Klaviyo
+Use the `klaviyo` CLI for Klaviyo data and actions (campaigns, segments,
+flows, metrics). Auth via KLAVIYO_API_KEY env var. Pass --json before the
+command for machine-readable output (e.g. `klaviyo --json list-campaigns`).
+Run `klaviyo --help` for the full command list.
+```
+
+## Command reference
+
+Run `klaviyo COMMAND --help` for full options on any command.
+
+### Campaigns
+| Command | Description |
+|---|---|
+| `list-campaigns` | List/filter campaigns by status, channel, and date (beyond name search) |
+| `search-campaigns` | Search campaigns by name |
+| `get-campaign` | Show details for a specific campaign |
+| `get-creative` | Dump a campaign's creative (subject + text/HTML) via its template |
+| `list-drafts` | List draft email campaigns for a client |
+| `patch-campaign` | Update campaign send time and/or audiences |
+| `schedule` | Schedule a campaign for sending |
+| `campaign-performance` | Show campaign revenue and engagement metrics |
+| `metrics` | Show sent campaigns for a client within a date window |
+
+### Segments
+| Command | Description |
+|---|---|
+| `list-audiences` | List all lists and segments for a client |
+| `search-segments` | Find segments by name keyword; shows a one-line definition summary |
+| `get-segment` | Show a segment's definition (conditions, metric IDs resolved) + count |
+| `segment-count` | Get profile count for a single segment (rate limited: 1/s, 15/min) |
+| `segment-sizes` | Show all segments with profile counts |
+| `create-segment` | Create a segment from a definition, guarding against duplicates |
+
+### Flows
+| Command | Description |
+|---|---|
+| `flows` | List all flows for a client, with optional sort and name search |
+| `get-flow` | Show a flow's basics in one call; `--definition` adds trigger, action chain, reentry |
+| `flow-detail` | Show full flow structure: trigger, filters, emails with subjects, delays, splits |
+| `flow-performance` | Show flow revenue and engagement metrics |
+| `create-flow` | Create a flow (in draft) from a definition, guarding against duplicates |
+
+### Profiles
+| Command | Description |
+|---|---|
+| `get-profile` | Look up a profile by email or ID; `--subscriptions` adds consent state and suppressions |
+| `segment-members` | List profiles in a segment: email, name, and when they joined |
+| `suppress` | Suppress profiles from email marketing in bulk (requires `--yes` or confirmation) |
+| `unsuppress` | Remove manual suppressions in bulk (never resubscribes anyone) |
+| `suppression-jobs` | List bulk suppression jobs (suppress + unsuppress) with status and counts |
+
+### Events
+| Command | Description |
+|---|---|
+| `push-event` | Push a custom event to a profile by email (creates the profile if needed) |
+| `events` | List recent events for a metric ID, newest first, with the profile attached |
+
+### Metrics
+| Command | Description |
+|---|---|
+| `account-health` | Show profiles count, lists, and metrics for a client |
+| `list-metrics` | List event metrics with their IDs and integration (ID<->name catalog) |
+| `form-performance` | Show pop-up/form views, submits, and submit rates |
+
+### SMS
+| Command | Description |
+|---|---|
+| `upload-sms` | Create an SMS campaign draft in Klaviyo |
+
+### Raw API
+| Command | Description |
+|---|---|
+| `api` | Raw API pass-through: `klaviyo api <METHOD> <path>` |
+
+That's 32 commands total.
+
+## Multi-account profiles
+
+For managing more than one Klaviyo account, put credentials in `~/.config/klaviyo-cli/config.toml`:
+
+```toml
+default_profile = "acme"
+
+[profiles.acme]
+api_key = "pk_acme_..."
+
+[profiles.other-brand]
+api_key = "pk_other_..."
+```
+
+Select a profile with `--profile` (or `-p`), or set `KLAVIYO_PROFILE`:
+
+```bash
+klaviyo --profile other-brand account-health
+KLAVIYO_PROFILE=other-brand klaviyo account-health
+```
+
+Precedence: an explicit `--profile` (or `KLAVIYO_PROFILE`) wins first. Otherwise `KLAVIYO_API_KEY` is used if set. Otherwise the CLI falls back to `default_profile` in the config file.
+
+Agencies running the CLI across many clients can go further and embed it: re-expose every command under a host CLI with per-client auth resolution, so `yourcli campaign-performance acme --days 30` resolves credentials for `acme` before the call. See the `wrap_with_account` and `build_host_group` docstrings in `src/klaviyo_cli/embed.py`.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+Built and maintained by [BS&Co](https://bsandco.us), a retention marketing agency for eCommerce brands.

klaviyo_cli-0.2.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "klaviyo-cli"
+version = "0.2.0"
+description = "Unofficial Klaviyo CLI: campaigns, segments, flows, metrics, scheduling. Built for humans and AI agents."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [{ name = "Andrew Beauchamp", email = "andrew@bsandco.us" }]
+keywords = ["klaviyo", "cli", "email-marketing", "ecommerce", "ai-agents"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Topic :: Communications :: Email",
+]
+dependencies = ["click>=8.0", "requests>=2.28"]
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0"]
+
+[project.urls]
+Homepage = "https://github.com/BeauchampAndrew/klaviyo-cli"
+Issues = "https://github.com/BeauchampAndrew/klaviyo-cli/issues"
+
+[project.scripts]
+klaviyo = "klaviyo_cli.cli:entry"
+
+[project.entry-points."klaviyo_cli.hosts"]
+# (empty in this package; host packages like workspace-cli register here)
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/klaviyo_cli"]

klaviyo_cli-0.2.0/src/klaviyo_cli/__init__.py

@@ -0,0 +1,3 @@
+"""klaviyo-cli: unofficial Klaviyo CLI."""
+
+__version__ = "0.2.0"

klaviyo_cli-0.2.0/src/klaviyo_cli/_util.py

@@ -0,0 +1,189 @@
+"""Shared helpers for command modules: timezone parsing, date ranges, output."""
+
+import json as json_module
+import re
+from datetime import datetime
+
+import click
+from zoneinfo import ZoneInfo
+
+from .transport import KLAVIYO_BASE
+
+TZ_MAP = {
+    "EST": "America/New_York",
+    "EDT": "America/New_York",
+    "CST": "America/Chicago",
+    "CDT": "America/Chicago",
+    "MST": "America/Denver",
+    "MDT": "America/Denver",
+    "PST": "America/Los_Angeles",
+    "PDT": "America/Los_Angeles",
+}
+
+
+def _parse_send_time(date_str: str, time_str: str) -> str:
+    """Parse MM-DD-YYYY + 'HH:MM AM/PM TZ' into an ISO 8601 string with timezone."""
+    # Normalize date from MM-DD-YYYY → YYYY-MM-DD
+    parts = date_str.strip().split("-")
+    if len(parts) == 3 and len(parts[2]) == 4:
+        # MM-DD-YYYY
+        month, day, year = parts
+        iso_date = f"{year}-{month}-{day}"
+    else:
+        # Assume already YYYY-MM-DD
+        iso_date = date_str.strip()
+
+    time_parts = time_str.strip().split()
+    tz_name = "America/New_York"  # default
+
+    if len(time_parts) == 3:
+        # "3:00 PM EST"
+        t, ampm, tz_abbr = time_parts
+        t_str = f"{t} {ampm}"
+        fmt = "%I:%M %p"
+        tz_name = TZ_MAP.get(tz_abbr.upper(), tz_abbr)
+    elif len(time_parts) == 2:
+        if time_parts[1].upper() in ("AM", "PM"):
+            # "3:00 PM"
+            t_str = time_str.strip()
+            fmt = "%I:%M %p"
+        else:
+            # "15:00 CST"
+            t_str = time_parts[0]
+            fmt = "%H:%M"
+            tz_name = TZ_MAP.get(time_parts[1].upper(), time_parts[1])
+    else:
+        # "15:00"
+        t_str = time_parts[0]
+        fmt = "%H:%M"
+
+    dt = datetime.strptime(f"{iso_date} {t_str}", f"%Y-%m-%d {fmt}")
+    dt = dt.replace(tzinfo=ZoneInfo(tz_name))
+    return dt.isoformat()
+
+
+def _resolve_date_range(days: int, since: str | None, until: str | None):
+    """Resolve a (start, end, label) tuple from --days / --since / --until.
+
+    If either --since or --until is provided, the explicit bounds win. Otherwise
+    falls back to (now - days) .. now. Dates are parsed as YYYY-MM-DD in UTC; the
+    end date is inclusive (23:59:59).
+    """
+    from datetime import datetime, timedelta, timezone
+
+    end = datetime.now(timezone.utc)
+    start = end - timedelta(days=days)
+    label = f"last {days} days"
+
+    if since or until:
+        if since:
+            try:
+                start = datetime.strptime(since, "%Y-%m-%d").replace(tzinfo=timezone.utc)
+            except ValueError:
+                raise click.ClickException(f"Invalid --since date {since!r} — expected YYYY-MM-DD")
+        if until:
+            try:
+                parsed = datetime.strptime(until, "%Y-%m-%d")
+                end = parsed.replace(hour=23, minute=59, second=59, tzinfo=timezone.utc)
+            except ValueError:
+                raise click.ClickException(f"Invalid --until date {until!r} — expected YYYY-MM-DD")
+        label = f"{start.strftime('%Y-%m-%d')} to {end.strftime('%Y-%m-%d')}"
+
+    return start, end, label
+
+
+def output(data, use_json: bool = False):
+    """Print data — raw JSON if use_json, otherwise assume caller formatted it."""
+    if use_json:
+        print(json_module.dumps(data, indent=2, default=str))
+    else:
+        if isinstance(data, str):
+            print(data)
+        else:
+            # Fallback for unformatted data — callers should format before calling
+            print(json_module.dumps(data, indent=2, default=str))
+
+
+# ---------------------------------------------------------------------------
+# Segment definition helpers
+# ---------------------------------------------------------------------------
+#
+# Klaviyo segment conditions reference metrics by opaque ID (e.g. "profile-metric"
+# conditions carry a metric_id like "XJcga2" rather than a name like "Opened
+# Email"). Reading or building any metric-based segment requires the ID->name
+# map, so these helpers back both list-metrics and the segment commands.
+
+_WINDOW_UNIT = {"day": "d", "week": "w", "month": "mo", "hour": "h", "year": "y"}
+_OP_SYMBOL = {"greater-than": ">", "greater-than-or-equal": ">=",
+              "less-than": "<", "less-than-or-equal": "<=", "equals": "="}
+
+
+def _resolve_metrics(call) -> dict:
+    """Return {metric_id: {"name": str, "integration": str}} for all metrics."""
+    out: dict = {}
+    path = "/api/metrics/"
+    while path:
+        data = call("GET", path)
+        for m in data.get("data", []):
+            attrs = m.get("attributes", {})
+            out[m["id"]] = {
+                "name": attrs.get("name", "?"),
+                "integration": (attrs.get("integration") or {}).get("name", ""),
+            }
+        next_link = data.get("links", {}).get("next")
+        path = next_link.replace(KLAVIYO_BASE, "") if next_link else None
+    return out
+
+
+def _format_condition(cond: dict, metric_map: dict) -> str:
+    """Render a single segment condition to a human-readable string."""
+    t = cond.get("type")
+    if t == "profile-marketing-consent":
+        consent = cond.get("consent") or {}
+        ch = consent.get("channel", "?")
+        if consent.get("can_receive_marketing") is False:
+            return f"can NOT receive {ch} marketing (suppressed or no consent)"
+        return f"can receive {ch} marketing"
+    if t == "profile-property":
+        prop = cond.get("property", "?")
+        m = re.match(r"properties\['(.+)'\]", prop)
+        prop = m.group(1) if m else prop
+        f = cond.get("filter") or {}
+        ft = f.get("type")
+        if ft == "existence":
+            return f"{prop} is {f.get('operator', '?')}"
+        if ft == "boolean":
+            return f"{prop} = {f.get('value')}"
+        val = f.get("value")
+        return f"{prop} {f.get('operator', '?')}{'' if val is None else ' ' + str(val)}"
+    if t == "profile-metric":
+        mid = cond.get("metric_id")
+        name = metric_map.get(mid, {}).get("name", mid)
+        mf = cond.get("measurement_filter") or {}
+        op = _OP_SYMBOL.get(mf.get("operator"), mf.get("operator", "?"))
+        val = mf.get("value")
+        tf = cond.get("timeframe_filter") or {}
+        window = ""
+        if tf.get("operator") == "in-the-last":
+            unit = _WINDOW_UNIT.get(tf.get("unit"), tf.get("unit", ""))
+            window = f" in last {tf.get('quantity')}{unit}"
+        return f"{name} {op}{val}{window}"
+    return t or "?"
+
+
+def _render_definition(definition: dict, metric_map: dict, oneline: bool = False):
+    """Render condition_groups. Groups are AND'd; conditions within OR'd.
+
+    Returns a list of per-group strings, or a single AND-joined string when
+    oneline=True.
+    """
+    groups = (definition or {}).get("condition_groups", [])
+    rendered = [" OR ".join(_format_condition(c, metric_map) for c in g.get("conditions", []))
+                for g in groups]
+    if oneline:
+        return " AND ".join(f"({g})" if " OR " in g else g for g in rendered)
+    return rendered
+
+
+def _norm_name(s: str) -> str:
+    return re.sub(r"\s+", " ", (s or "").strip().lower())

klaviyo_cli-0.2.0/src/klaviyo_cli/cli.py

@@ -0,0 +1,48 @@
+"""CLI group: `klaviyo` command. Commands live in klaviyo_cli/commands/."""
+
+from importlib.metadata import entry_points
+
+import click
+
+from .config import resolve_transport
+
+
+def build_context(profile: str | None) -> dict:
+    """Build ctx.obj auth pieces. Transport resolves lazily on first call."""
+    transport = None
+
+    def call(method, path, body=None, revision=None):
+        nonlocal transport
+        if transport is None:
+            transport = resolve_transport(profile)
+        return transport.call(method, path, body=body, revision=revision)
+
+    return {"call": call, "label": profile or "default"}
+
+
+@click.group()
+@click.option("--json", "use_json", is_flag=True, help="Output raw JSON")
+@click.option("-p", "--profile", envvar="KLAVIYO_PROFILE", default=None,
+              help="Named account profile from ~/.config/klaviyo-cli/config.toml")
+@click.version_option(package_name="klaviyo-cli")
+@click.pass_context
+def main(ctx, use_json, profile):
+    """Unofficial Klaviyo CLI: campaigns, segments, flows, metrics, scheduling.
+
+    Auth: set KLAVIYO_API_KEY, or use --profile with a config file.
+    Not affiliated with or endorsed by Klaviyo, Inc.
+    """
+    ctx.obj = {"json": use_json, **build_context(profile)}
+
+
+def entry():
+    """Console-script entry. Host packages (klaviyo_cli.hosts entry points)
+    may supply a replacement group (e.g. an agency wrapper with per-client auth)."""
+    for ep in entry_points(group="klaviyo_cli.hosts"):
+        group = ep.load()()
+        if group is not None:
+            return group()
+    return main()
+
+
+from . import commands  # noqa: E402,F401  (registers subcommands on `main`)

klaviyo_cli-0.2.0/src/klaviyo_cli/commands/__init__.py

@@ -0,0 +1,9 @@
+"""Import command modules so they register on the main group."""
+from . import campaigns  # noqa: F401
+from . import segments  # noqa: F401
+from . import flows  # noqa: F401
+from . import metrics  # noqa: F401
+from . import profiles  # noqa: F401
+from . import events  # noqa: F401
+from . import sms  # noqa: F401
+from . import raw  # noqa: F401