earlyforge-cli 0.1.0__tar.gz

earlyforge_cli-0.1.0/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.4
+Name: earlyforge-cli
+Version: 0.1.0
+Summary: Command-line client for the EarlyForge Pulse API (free trend data, authenticated)
+Author: EarlyForge
+License: MIT
+Project-URL: Homepage, https://earlyforge.ai
+Project-URL: Documentation, https://docs.earlyforge.ai/guides/api/trends-api
+Project-URL: Source, https://github.com/Earlyforge-official/earlyforge
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: click>=8.1.0
+Requires-Dist: httpx>=0.27.0
+
+# earlyforge-cli
+
+Command-line client for the **EarlyForge Trends API**, with two tiers
+under the same `/v1/api/trends/*` prefix:
+
+- **Pulse mirror** (`pulse top|region|category|trend`) — free on every
+  account, no plan required. The same daily snapshot already shown on
+  [pulse.earlyforge.ai](https://pulse.earlyforge.ai).
+- **Full trends feed** (`pulse full`/`pulse full-trend`) — paid plans
+  only, and **not "all trends unlocked."** Every plan reveals a bigger,
+  but still limited, daily, random, category-diversified budget of trend
+  names — exactly what your organization's dashboard Trends page shows
+  unlocked today, no more, no less.
+
+Not a CLI for articles, briefs, or alerts — the public API never exposes
+those on any plan. Full reference: [docs.earlyforge.ai/guides/api/cli](https://docs.earlyforge.ai/guides/api/cli). Source: [github.com/Earlyforge-official/earlyforge](https://github.com/Earlyforge-official/earlyforge/tree/main/cli-earlyforge).
+
+## Install
+
+Not published yet. Contact [support@earlyforge.ai](mailto:support@earlyforge.ai) for early access.
+
+## Configure
+
+```bash
+export EARLYFORGE_API_KEY=ef_live_xxxxxxxxxxxxxxxx
+```
+
+Get a key from **Settings → API Keys** in the EarlyForge console. Or pass
+`--api-key` on each command instead of the env var.
+
+## Commands
+
+```bash
+earlyforge pulse top [--date YYYY-MM-DD] [--locale fr]
+earlyforge pulse region <REGION> [--date YYYY-MM-DD] [--locale fr]
+earlyforge pulse category <CATEGORY> [--date YYYY-MM-DD] [--locale fr]
+earlyforge pulse trend <TREND_ID>
+earlyforge pulse full [--region US] [--category tech] [--page 1] [--limit 20]
+earlyforge pulse full-trend <TREND_ID>
+```
+
+Every command pretty-prints the JSON response and accepts `--api-key` and
+`--base-url` (default `https://api.earlyforge.ai`, useful for pointing at
+a local gateway in development).
+
+`pulse full` and `pulse full-trend` require a paid-plan API key — a
+free-plan key gets HTTP 402. They are **not** "all trends unlocked":
+every plan, paid included, only reveals a daily, random,
+category-diversified budget of trend names, same as the dashboard's
+Trends page. A trend outside that budget stays in the list with its name
+redacted (`"name_locked": true`) for `pulse full`, or returns HTTP 402
+for `pulse full-trend`.
+
+### Examples
+
+```bash
+earlyforge pulse top
+earlyforge pulse top --locale fr --date 2026-11-01
+earlyforge pulse region US
+earlyforge pulse category politics
+earlyforge pulse trend tr_a1b2c3
+earlyforge pulse full --region US --limit 50
+earlyforge pulse full-trend tr_a1b2c3
+```
+
+## Errors
+
+A non-2xx response prints `Error: ... (<detail>)` to stderr and exits
+with status `1` — the same `401` invalid-key / `404` unknown-trend /
+`502` upstream-unavailable cases documented in the OpenAPI spec, plus
+`402` (`upgrade_required` on `pulse full`/`pulse full-trend` for a
+free-plan key, `trend_locked` on `pulse full-trend` for a trend outside
+today's budget).
+
+## Rate limits
+
+No monthly call quota on this surface — only the shared 60 requests/60s
+burst limit applies, same as the anonymous Pulse page.
+
+## Tests
+
+```bash
+pip install -e . pytest
+pytest
+```

earlyforge_cli-0.1.0/README.md

@@ -0,0 +1,85 @@
+# earlyforge-cli
+
+Command-line client for the **EarlyForge Trends API**, with two tiers
+under the same `/v1/api/trends/*` prefix:
+
+- **Pulse mirror** (`pulse top|region|category|trend`) — free on every
+  account, no plan required. The same daily snapshot already shown on
+  [pulse.earlyforge.ai](https://pulse.earlyforge.ai).
+- **Full trends feed** (`pulse full`/`pulse full-trend`) — paid plans
+  only, and **not "all trends unlocked."** Every plan reveals a bigger,
+  but still limited, daily, random, category-diversified budget of trend
+  names — exactly what your organization's dashboard Trends page shows
+  unlocked today, no more, no less.
+
+Not a CLI for articles, briefs, or alerts — the public API never exposes
+those on any plan. Full reference: [docs.earlyforge.ai/guides/api/cli](https://docs.earlyforge.ai/guides/api/cli). Source: [github.com/Earlyforge-official/earlyforge](https://github.com/Earlyforge-official/earlyforge/tree/main/cli-earlyforge).
+
+## Install
+
+Not published yet. Contact [support@earlyforge.ai](mailto:support@earlyforge.ai) for early access.
+
+## Configure
+
+```bash
+export EARLYFORGE_API_KEY=ef_live_xxxxxxxxxxxxxxxx
+```
+
+Get a key from **Settings → API Keys** in the EarlyForge console. Or pass
+`--api-key` on each command instead of the env var.
+
+## Commands
+
+```bash
+earlyforge pulse top [--date YYYY-MM-DD] [--locale fr]
+earlyforge pulse region <REGION> [--date YYYY-MM-DD] [--locale fr]
+earlyforge pulse category <CATEGORY> [--date YYYY-MM-DD] [--locale fr]
+earlyforge pulse trend <TREND_ID>
+earlyforge pulse full [--region US] [--category tech] [--page 1] [--limit 20]
+earlyforge pulse full-trend <TREND_ID>
+```
+
+Every command pretty-prints the JSON response and accepts `--api-key` and
+`--base-url` (default `https://api.earlyforge.ai`, useful for pointing at
+a local gateway in development).
+
+`pulse full` and `pulse full-trend` require a paid-plan API key — a
+free-plan key gets HTTP 402. They are **not** "all trends unlocked":
+every plan, paid included, only reveals a daily, random,
+category-diversified budget of trend names, same as the dashboard's
+Trends page. A trend outside that budget stays in the list with its name
+redacted (`"name_locked": true`) for `pulse full`, or returns HTTP 402
+for `pulse full-trend`.
+
+### Examples
+
+```bash
+earlyforge pulse top
+earlyforge pulse top --locale fr --date 2026-11-01
+earlyforge pulse region US
+earlyforge pulse category politics
+earlyforge pulse trend tr_a1b2c3
+earlyforge pulse full --region US --limit 50
+earlyforge pulse full-trend tr_a1b2c3
+```
+
+## Errors
+
+A non-2xx response prints `Error: ... (<detail>)` to stderr and exits
+with status `1` — the same `401` invalid-key / `404` unknown-trend /
+`502` upstream-unavailable cases documented in the OpenAPI spec, plus
+`402` (`upgrade_required` on `pulse full`/`pulse full-trend` for a
+free-plan key, `trend_locked` on `pulse full-trend` for a trend outside
+today's budget).
+
+## Rate limits
+
+No monthly call quota on this surface — only the shared 60 requests/60s
+burst limit applies, same as the anonymous Pulse page.
+
+## Tests
+
+```bash
+pip install -e . pytest
+pytest
+```

earlyforge_cli-0.1.0/earlyforge_cli/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

earlyforge_cli-0.1.0/earlyforge_cli/client.py

@@ -0,0 +1,85 @@
+"""Minimal, standalone Trends API client used by the CLI.
+
+Deliberately self-contained (duplicates the method shape of
+tools/sdk-python-earlyforge/earlyforge/client.py) so this package has no
+dependency on another, as-yet-unpublished package. Contract:
+docs/api/public-api-v1/openapi.yaml (repo root).
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+from urllib.parse import quote
+
+import httpx
+
+DEFAULT_BASE_URL = "https://api.earlyforge.ai"
+DEFAULT_TIMEOUT_SECONDS = 15.0
+
+
+class PulseApiError(Exception):
+    def __init__(self, message: str, *, status_code: Optional[int] = None, detail: Optional[str] = None) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.detail = detail
+
+
+class PulseClient:
+    def __init__(self, api_key: str, base_url: str = DEFAULT_BASE_URL) -> None:
+        if not api_key:
+            raise ValueError("api_key is required")
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+
+    def _get(self, path: str, params: Optional[Dict[str, Any]] = None) -> Any:
+        clean_params = {k: v for k, v in (params or {}).items() if v is not None}
+        url = f"{self.base_url}{path}"
+        try:
+            response = httpx.get(
+                url,
+                params=clean_params,
+                headers={"Authorization": f"Bearer {self.api_key}"},
+                timeout=DEFAULT_TIMEOUT_SECONDS,
+            )
+        except httpx.RequestError as exc:
+            raise PulseApiError(f"Could not reach EarlyForge API at {url}: {exc}") from exc
+
+        if response.status_code >= 400:
+            try:
+                detail = response.json().get("detail")
+            except Exception:
+                detail = response.text[:300] or None
+            raise PulseApiError(
+                f"EarlyForge API returned HTTP {response.status_code} for {url}",
+                status_code=response.status_code,
+                detail=detail,
+            )
+        return response.json()
+
+    def top_trends(self, *, date: Optional[str] = None, locale: Optional[str] = None) -> Any:
+        return self._get("/v1/api/trends/top", {"date": date, "locale": locale})
+
+    def trends_by_region(self, region: str, *, date: Optional[str] = None, locale: Optional[str] = None) -> Any:
+        return self._get(f"/v1/api/trends/region/{quote(region, safe='')}", {"date": date, "locale": locale})
+
+    def trends_by_category(self, category: str, *, date: Optional[str] = None, locale: Optional[str] = None) -> Any:
+        return self._get(f"/v1/api/trends/category/{quote(category, safe='')}", {"date": date, "locale": locale})
+
+    def get_trend(self, trend_id: str) -> Any:
+        return self._get(f"/v1/api/trends/{quote(trend_id, safe='')}")
+
+    def full_trends(
+        self,
+        *,
+        region: Optional[str] = None,
+        category: Optional[str] = None,
+        page: int = 1,
+        limit: int = 20,
+    ) -> Any:
+        return self._get(
+            "/v1/api/trends/full",
+            {"region": region, "category": category, "page": page, "limit": limit},
+        )
+
+    def get_full_trend(self, trend_id: str) -> Any:
+        return self._get(f"/v1/api/trends/full/{quote(trend_id, safe='')}")

earlyforge_cli-0.1.0/earlyforge_cli/main.py

@@ -0,0 +1,144 @@
+"""`earlyforge` CLI — command-line access to the EarlyForge Trends API.
+
+Wraps the same endpoints as the Python/JS/PHP SDKs and the MCP server:
+the 4 free Pulse endpoints (top, by region, by category, trend detail)
+plus the paid-plan full trends feed (list + detail). Contract:
+docs/api/public-api-v1/openapi.yaml (repo root).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from typing import Optional
+
+import click
+
+from .client import PulseApiError, PulseClient
+
+
+def _resolve_api_key(api_key: Optional[str]) -> str:
+    resolved = api_key or os.environ.get("EARLYFORGE_API_KEY")
+    if not resolved:
+        raise click.ClickException(
+            "No API key provided. Pass --api-key or set EARLYFORGE_API_KEY. "
+            "Generate one from Settings -> API Keys in the EarlyForge console "
+            "(any account — Pulse access is free)."
+        )
+    return resolved
+
+
+def _print_json(payload: object) -> None:
+    click.echo(json.dumps(payload, indent=2, ensure_ascii=False))
+
+
+@click.group()
+def cli() -> None:
+    """EarlyForge command-line client."""
+
+
+@cli.group()
+def pulse() -> None:
+    """Query the free EarlyForge Pulse API (trend snapshots)."""
+
+
+@pulse.command("top")
+@click.option("--date", default=None, help="Past daily snapshot (YYYY-MM-DD). Omit for latest.")
+@click.option("--locale", default=None, help='Locale for translated fields (e.g. "fr").')
+@click.option("--api-key", default=None, help="API key. Defaults to $EARLYFORGE_API_KEY.")
+@click.option("--base-url", default="https://api.earlyforge.ai", show_default=True)
+def pulse_top(date: Optional[str], locale: Optional[str], api_key: Optional[str], base_url: str) -> None:
+    """Global top trends — same snapshot as the Pulse homepage."""
+    client = PulseClient(api_key=_resolve_api_key(api_key), base_url=base_url)
+    _run(lambda: client.top_trends(date=date, locale=locale))
+
+
+@pulse.command("region")
+@click.argument("region")
+@click.option("--date", default=None, help="Past daily snapshot (YYYY-MM-DD). Omit for latest.")
+@click.option("--locale", default=None, help='Locale for translated fields (e.g. "fr").')
+@click.option("--api-key", default=None, help="API key. Defaults to $EARLYFORGE_API_KEY.")
+@click.option("--base-url", default="https://api.earlyforge.ai", show_default=True)
+def pulse_region(
+    region: str, date: Optional[str], locale: Optional[str], api_key: Optional[str], base_url: str
+) -> None:
+    """Top trends for a region (ISO 3166-1 alpha-2, e.g. US, FR)."""
+    client = PulseClient(api_key=_resolve_api_key(api_key), base_url=base_url)
+    _run(lambda: client.trends_by_region(region, date=date, locale=locale))
+
+
+@pulse.command("category")
+@click.argument("category")
+@click.option("--date", default=None, help="Past daily snapshot (YYYY-MM-DD). Omit for latest.")
+@click.option("--locale", default=None, help='Locale for translated fields (e.g. "fr").')
+@click.option("--api-key", default=None, help="API key. Defaults to $EARLYFORGE_API_KEY.")
+@click.option("--base-url", default="https://api.earlyforge.ai", show_default=True)
+def pulse_category(
+    category: str, date: Optional[str], locale: Optional[str], api_key: Optional[str], base_url: str
+) -> None:
+    """Top trends for a category (e.g. politics, tech)."""
+    client = PulseClient(api_key=_resolve_api_key(api_key), base_url=base_url)
+    _run(lambda: client.trends_by_category(category, date=date, locale=locale))
+
+
+@pulse.command("trend")
+@click.argument("trend_id")
+@click.option("--api-key", default=None, help="API key. Defaults to $EARLYFORGE_API_KEY.")
+@click.option("--base-url", default="https://api.earlyforge.ai", show_default=True)
+def pulse_trend(trend_id: str, api_key: Optional[str], base_url: str) -> None:
+    """Detail for one trend (score, description, sources, timeline)."""
+    client = PulseClient(api_key=_resolve_api_key(api_key), base_url=base_url)
+    _run(lambda: client.get_trend(trend_id))
+
+
+@pulse.command("full")
+@click.option("--region", default=None, help="Filter by region.")
+@click.option("--category", default=None, help="Filter by category.")
+@click.option("--page", default=1, show_default=True, type=int)
+@click.option("--limit", default=20, show_default=True, type=int, help="Max 100.")
+@click.option("--api-key", default=None, help="API key. Defaults to $EARLYFORGE_API_KEY.")
+@click.option("--base-url", default="https://api.earlyforge.ai", show_default=True)
+def pulse_full(
+    region: Optional[str],
+    category: Optional[str],
+    page: int,
+    limit: int,
+    api_key: Optional[str],
+    base_url: str,
+) -> None:
+    """Full trends feed (paid plans only — not "all trends unlocked").
+
+    Every plan still reveals only a daily, random, category-diversified
+    budget of trend names, same as the dashboard's Trends page. Items
+    outside today's budget stay in the list with their name redacted
+    ("name_locked": true). A free-plan key gets HTTP 402.
+    """
+    client = PulseClient(api_key=_resolve_api_key(api_key), base_url=base_url)
+    _run(lambda: client.full_trends(region=region, category=category, page=page, limit=limit))
+
+
+@pulse.command("full-trend")
+@click.argument("trend_id")
+@click.option("--api-key", default=None, help="API key. Defaults to $EARLYFORGE_API_KEY.")
+@click.option("--base-url", default="https://api.earlyforge.ai", show_default=True)
+def pulse_full_trend(trend_id: str, api_key: Optional[str], base_url: str) -> None:
+    """Full detail for one trend (paid plans only).
+
+    Returns HTTP 402 if the trend is outside today's visible-name
+    budget — same restriction the dashboard's own detail panel enforces.
+    """
+    client = PulseClient(api_key=_resolve_api_key(api_key), base_url=base_url)
+    _run(lambda: client.get_full_trend(trend_id))
+
+
+def _run(call) -> None:
+    try:
+        _print_json(call())
+    except PulseApiError as exc:
+        click.echo(f"Error: {exc} ({exc.detail})" if exc.detail else f"Error: {exc}", err=True)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    cli()

earlyforge_cli-0.1.0/earlyforge_cli.egg-info/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.4
+Name: earlyforge-cli
+Version: 0.1.0
+Summary: Command-line client for the EarlyForge Pulse API (free trend data, authenticated)
+Author: EarlyForge
+License: MIT
+Project-URL: Homepage, https://earlyforge.ai
+Project-URL: Documentation, https://docs.earlyforge.ai/guides/api/trends-api
+Project-URL: Source, https://github.com/Earlyforge-official/earlyforge
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: click>=8.1.0
+Requires-Dist: httpx>=0.27.0
+
+# earlyforge-cli
+
+Command-line client for the **EarlyForge Trends API**, with two tiers
+under the same `/v1/api/trends/*` prefix:
+
+- **Pulse mirror** (`pulse top|region|category|trend`) — free on every
+  account, no plan required. The same daily snapshot already shown on
+  [pulse.earlyforge.ai](https://pulse.earlyforge.ai).
+- **Full trends feed** (`pulse full`/`pulse full-trend`) — paid plans
+  only, and **not "all trends unlocked."** Every plan reveals a bigger,
+  but still limited, daily, random, category-diversified budget of trend
+  names — exactly what your organization's dashboard Trends page shows
+  unlocked today, no more, no less.
+
+Not a CLI for articles, briefs, or alerts — the public API never exposes
+those on any plan. Full reference: [docs.earlyforge.ai/guides/api/cli](https://docs.earlyforge.ai/guides/api/cli). Source: [github.com/Earlyforge-official/earlyforge](https://github.com/Earlyforge-official/earlyforge/tree/main/cli-earlyforge).
+
+## Install
+
+Not published yet. Contact [support@earlyforge.ai](mailto:support@earlyforge.ai) for early access.
+
+## Configure
+
+```bash
+export EARLYFORGE_API_KEY=ef_live_xxxxxxxxxxxxxxxx
+```
+
+Get a key from **Settings → API Keys** in the EarlyForge console. Or pass
+`--api-key` on each command instead of the env var.
+
+## Commands
+
+```bash
+earlyforge pulse top [--date YYYY-MM-DD] [--locale fr]
+earlyforge pulse region <REGION> [--date YYYY-MM-DD] [--locale fr]
+earlyforge pulse category <CATEGORY> [--date YYYY-MM-DD] [--locale fr]
+earlyforge pulse trend <TREND_ID>
+earlyforge pulse full [--region US] [--category tech] [--page 1] [--limit 20]
+earlyforge pulse full-trend <TREND_ID>
+```
+
+Every command pretty-prints the JSON response and accepts `--api-key` and
+`--base-url` (default `https://api.earlyforge.ai`, useful for pointing at
+a local gateway in development).
+
+`pulse full` and `pulse full-trend` require a paid-plan API key — a
+free-plan key gets HTTP 402. They are **not** "all trends unlocked":
+every plan, paid included, only reveals a daily, random,
+category-diversified budget of trend names, same as the dashboard's
+Trends page. A trend outside that budget stays in the list with its name
+redacted (`"name_locked": true`) for `pulse full`, or returns HTTP 402
+for `pulse full-trend`.
+
+### Examples
+
+```bash
+earlyforge pulse top
+earlyforge pulse top --locale fr --date 2026-11-01
+earlyforge pulse region US
+earlyforge pulse category politics
+earlyforge pulse trend tr_a1b2c3
+earlyforge pulse full --region US --limit 50
+earlyforge pulse full-trend tr_a1b2c3
+```
+
+## Errors
+
+A non-2xx response prints `Error: ... (<detail>)` to stderr and exits
+with status `1` — the same `401` invalid-key / `404` unknown-trend /
+`502` upstream-unavailable cases documented in the OpenAPI spec, plus
+`402` (`upgrade_required` on `pulse full`/`pulse full-trend` for a
+free-plan key, `trend_locked` on `pulse full-trend` for a trend outside
+today's budget).
+
+## Rate limits
+
+No monthly call quota on this surface — only the shared 60 requests/60s
+burst limit applies, same as the anonymous Pulse page.
+
+## Tests
+
+```bash
+pip install -e . pytest
+pytest
+```

earlyforge_cli-0.1.0/earlyforge_cli.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+README.md
+pyproject.toml
+earlyforge_cli/__init__.py
+earlyforge_cli/client.py
+earlyforge_cli/main.py
+earlyforge_cli.egg-info/PKG-INFO
+earlyforge_cli.egg-info/SOURCES.txt
+earlyforge_cli.egg-info/dependency_links.txt
+earlyforge_cli.egg-info/entry_points.txt
+earlyforge_cli.egg-info/requires.txt
+earlyforge_cli.egg-info/top_level.txt
+tests/test_cli.py

earlyforge_cli-0.1.0/earlyforge_cli.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

earlyforge_cli-0.1.0/earlyforge_cli.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+earlyforge = earlyforge_cli.main:cli

earlyforge_cli-0.1.0/earlyforge_cli.egg-info/requires.txt

@@ -0,0 +1,2 @@
+click>=8.1.0
+httpx>=0.27.0

earlyforge_cli-0.1.0/earlyforge_cli.egg-info/top_level.txt

@@ -0,0 +1 @@
+earlyforge_cli

earlyforge_cli-0.1.0/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "earlyforge-cli"
+version = "0.1.0"
+description = "Command-line client for the EarlyForge Pulse API (free trend data, authenticated)"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "EarlyForge" }]
+dependencies = ["click>=8.1.0", "httpx>=0.27.0"]
+
+[project.scripts]
+earlyforge = "earlyforge_cli.main:cli"
+
+[project.urls]
+Homepage = "https://earlyforge.ai"
+Documentation = "https://docs.earlyforge.ai/guides/api/trends-api"
+Source = "https://github.com/Earlyforge-official/earlyforge"
+
+[tool.setuptools.packages.find]
+include = ["earlyforge_cli*"]

earlyforge_cli-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

earlyforge_cli-0.1.0/tests/test_cli.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+import httpx
+import pytest
+from click.testing import CliRunner
+
+from earlyforge_cli.main import cli
+
+
+def _handler(request: httpx.Request) -> httpx.Response:
+    assert request.headers["authorization"] == "Bearer ef_live_test"
+    if request.url.path == "/v1/api/trends/top":
+        return httpx.Response(200, json={"trends": [], "total": 0})
+    if request.url.path == "/v1/api/trends/full":
+        return httpx.Response(
+            200, json={"items": [{"trend_id": "tr_1"}], "total": 1, "page": 1, "per_page": 20}
+        )
+    return httpx.Response(404, json={"detail": "Not found"})
+
+
+@pytest.fixture(autouse=True)
+def _patch_transport(monkeypatch: pytest.MonkeyPatch) -> None:
+    transport = httpx.MockTransport(_handler)
+
+    def fake_get(url, *, params=None, headers=None, timeout=None):
+        with httpx.Client(transport=transport) as client:
+            return client.get(url, params=params, headers=headers, timeout=timeout)
+
+    monkeypatch.setattr(httpx, "get", fake_get)
+
+
+def test_pulse_top_prints_json() -> None:
+    runner = CliRunner()
+    result = runner.invoke(cli, ["pulse", "top", "--api-key", "ef_live_test"])
+    assert result.exit_code == 0
+    assert '"trends": []' in result.output
+
+
+def test_pulse_full_prints_json() -> None:
+    runner = CliRunner()
+    result = runner.invoke(cli, ["pulse", "full", "--api-key", "ef_live_test"])
+    assert result.exit_code == 0
+    assert '"total": 1' in result.output
+
+
+def test_missing_api_key_errors_cleanly(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.delenv("EARLYFORGE_API_KEY", raising=False)
+    runner = CliRunner()
+    result = runner.invoke(cli, ["pulse", "top"])
+    assert result.exit_code != 0
+    assert "No API key provided" in result.output