pulse-ai-cli 0.1.0__tar.gz → 0.2.0__tar.gz

{pulse_ai_cli-0.1.0 → pulse_ai_cli-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: pulse-ai-cli
-Version: 0.1.0
+Version: 0.2.0
 Summary: Pulse CLI — document extraction from your terminal (runpulse.com)
 Project-URL: Homepage, https://runpulse.com
 Project-URL: Documentation, https://docs.runpulse.com
@@ -14,6 +14,7 @@ Classifier: Programming Language :: Python :: 3.13
 Requires-Python: >=3.11
 Requires-Dist: click>=8
 Requires-Dist: httpx>=0.27
+Requires-Dist: keyring>=24
 Requires-Dist: rich>=13.7
 Requires-Dist: textual>=0.80
 Requires-Dist: typer>=0.12
@@ -21,13 +22,13 @@ Provides-Extra: dev
 Requires-Dist: pytest>=8; extra == 'dev'
 Requires-Dist: respx>=0.21; extra == 'dev'
 Provides-Extra: keyring
-Requires-Dist: keyring>=24; extra == 'keyring'
 Description-Content-Type: text/markdown
 
 # Pulse CLI
 
 Document extraction from your terminal — markdown, structured JSON schemas,
-splits, and tables, powered by the [Pulse](https://runpulse.com) API.
+splits, tables, and chart reconstruction, powered by the
+[Pulse](https://runpulse.com) API.
 
 ```
 uv tool install pulse-ai-cli
@@ -40,6 +41,8 @@ pulse extract invoice.pdf --schema schemas/invoice.json
 - `pulse schema generate / apply` — AI-draft a JSON Schema, run it against
   any extraction
 - `pulse split` / `pulse tables` — topic-based splitting, table extraction
+- `pulse charts` — reconstruct chart series and export Excel, CSV, or LAS data;
+  add `--no-wait` to submit an async chart job without polling
 - `pulse jobs` — watch, resume, or cancel async jobs
 - `pulse usage` — plan and page/credit usage
 - bare `pulse` — interactive shell with the full command set

{pulse_ai_cli-0.1.0 → pulse_ai_cli-0.2.0}/README.md

@@ -1,7 +1,8 @@
 # Pulse CLI
 
 Document extraction from your terminal — markdown, structured JSON schemas,
-splits, and tables, powered by the [Pulse](https://runpulse.com) API.
+splits, tables, and chart reconstruction, powered by the
+[Pulse](https://runpulse.com) API.
 
 ```
 uv tool install pulse-ai-cli
@@ -14,6 +15,8 @@ pulse extract invoice.pdf --schema schemas/invoice.json
 - `pulse schema generate / apply` — AI-draft a JSON Schema, run it against
   any extraction
 - `pulse split` / `pulse tables` — topic-based splitting, table extraction
+- `pulse charts` — reconstruct chart series and export Excel, CSV, or LAS data;
+  add `--no-wait` to submit an async chart job without polling
 - `pulse jobs` — watch, resume, or cancel async jobs
 - `pulse usage` — plan and page/credit usage
 - bare `pulse` — interactive shell with the full command set

{pulse_ai_cli-0.1.0 → pulse_ai_cli-0.2.0}/docs.md

@@ -23,15 +23,27 @@ Python 3.11+.
 pulse login
 ```
 
-Opens the Pulse platform in your browser; you approve a short code (e.g.
-`ABCD-1234`) while signed in, and the CLI picks up your organization's API
-key automatically (OAuth 2.1 device flow, RFC 8628). The key is validated
-and stored in your OS keychain (or `~/.pulse/config.toml`, chmod 0600, if no
-keychain is available).
-
-No browser handy? `pulse login --api-key <key>` (or `pulse login --no-web`
-to be prompted) logs in with an API key directly — find yours in the Pulse
-platform under API Keys.
+Opens the Pulse platform in your browser; you approve the request while
+signed in, and the CLI creates an API key for this device (OAuth 2.1
+authorization code + PKCE on a loopback redirect, RFC 8252). The key shows up
+under API Keys as `pulse-cli <hostname>`, is validated, and is stored in your
+OS keychain (or `~/.pulse/config.toml`, chmod 0600, if no keychain is
+available). `pulse logout` deletes it again, as does a later `pulse login`
+that replaces it or a login that fails after the key was created; a key you
+pasted yourself is only forgotten.
+
+This key is this machine's login, not a credential for automation: it expires
+after 90 days (`pulse whoami` shows when), and then `pulse login` makes a new
+one. For CI, cron jobs, servers or an MCP client, create a key in the platform
+under API Keys and pass it as `PULSE_API_KEY`.
+
+No browser on this machine (SSH, containers)? `pulse login --device` prints a
+URL and a short code (e.g. `ABCD-1234`) to type in a browser on any device
+(OAuth 2.0 device flow, RFC 8628). Only do this for a login you started
+yourself: never enter a code someone sent you.
+
+`pulse login --api-key <key>` (or `pulse login --no-web` to be prompted) logs
+in with an API key directly — find yours in the Pulse platform under API Keys.
 
 Alternatives, in priority order:
 
@@ -141,6 +153,20 @@ pulse tables <extraction_id> --format html
 `--format html|json`, `--merge` (join tables spanning pages),
 `--charts-to-tables`, `-o <file>`.
 
+### `pulse charts [<extraction_id>]`
+
+Reconstruct chart series from a completed extraction or split:
+
+```bash
+pulse charts <extraction_id> --data-points 200 --agentic-zoom \
+  --export excel --export csv
+pulse charts --split-id <split_id> --export las
+```
+
+Use `--pages "1-3,5"` with an extraction. Split results inherit their pages and
+cannot use `--pages`. `--download-exports <directory>` explicitly consumes the
+authenticated one-time export links; without it the CLI returns the links untouched.
+
 ### `pulse jobs`
 
 Every long-running command runs async under the hood and polls for you.
@@ -196,6 +222,4 @@ the interactive shell.
 
 - `extract --split … --schema …` end-to-end pipeline (split a document, then apply
   a schema per topic in one command).
-- Platform `/activate` approval page for `pulse login --web` (the API-side
-  device flow is live; approval UI is rolling out).
 - Full OAuth token auth for the MCP server (auth-code + PKCE, DCR).

pulse_ai_cli-0.2.0/pulse_cli/__init__.py

@@ -0,0 +1,3 @@
+"""Pulse CLI."""
+
+__version__ = "0.2.0"

{pulse_ai_cli-0.1.0 → pulse_ai_cli-0.2.0}/pulse_cli/app.py

@@ -1,10 +1,12 @@
 """Pulse CLI root app."""
+
 from __future__ import annotations
 
 import typer
 
 from pulse_cli import __version__
 from pulse_cli.commands.auth import login, logout, whoami
+from pulse_cli.commands.charts import charts
 from pulse_cli.commands.extract import extract
 from pulse_cli.commands.jobs import jobs_app
 from pulse_cli.commands.open_platform import open_platform
@@ -25,6 +27,7 @@ _EXAMPLES = [
     ("pulse schema apply <extraction_id> --schema s.json", "structured fields from a past extract"),
     ('pulse split <extraction_id> -t "intro:first part"', "split a document by topic"),
     ("pulse tables <extraction_id>", "pull out tables"),
+    ("pulse charts <extraction_id>", "reconstruct charts and export their data"),
     ("pulse jobs get <job_id> --watch", "watch or resume an async job"),
     ("pulse open <extraction_id>", "view an extraction on the platform"),
     ("pulse usage", "plan + credit/page usage"),
@@ -78,6 +81,7 @@ cli.command()(whoami)
 cli.command()(extract)
 cli.command()(split)
 cli.command()(tables)
+cli.command()(charts)
 cli.command()(usage)
 cli.command("open")(open_platform)
 cli.add_typer(schema_app, name="schema")
@@ -96,7 +100,7 @@ def app() -> None:
         cli()
     except PulseCliError as exc:
         err_console.print(f"[err]error:[/err] {exc}")
-        raise SystemExit(1)
+        raise SystemExit(1) from exc
 
 
 if __name__ == "__main__":

{pulse_ai_cli-0.1.0 → pulse_ai_cli-0.2.0}/pulse_cli/client.py

@@ -1,14 +1,17 @@
-"""Sync HTTP client for the Pulse engine — a CLI port of mcp_server/pulse_client.py.
+"""Sync HTTP client for the Pulse engine — a CLI port of pulse_mcp/pulse_client.py.
 
 Same endpoints, same payload shapes, same submit -> poll semantics, so the CLI
-and MCP gateway behave identically against the engine. Auth is the caller's API
+and MCP gateway behave identically against the v1.engine. Auth is the caller's API
 key forwarded verbatim as ``x-api-key``; the engine enforces auth/credits/limits.
 """
+
 from __future__ import annotations
 
 import json
 import time
-from typing import Any, Callable, Optional
+from collections.abc import Callable
+from typing import Any
+from urllib.parse import urljoin, urlsplit
 
 import httpx
 
@@ -35,7 +38,9 @@ def _form_value(v: Any) -> str:
 
 
 class PulseClient:
-    def __init__(self, api_key: str, base_url: str, *, transport: Optional[httpx.BaseTransport] = None) -> None:
+    def __init__(
+        self, api_key: str, base_url: str, *, transport: httpx.BaseTransport | None = None
+    ) -> None:
         self._client = httpx.Client(
             base_url=base_url.rstrip("/"),
             timeout=DEFAULT_TIMEOUT,
@@ -43,7 +48,7 @@ class PulseClient:
             transport=transport,
         )
 
-    def __enter__(self) -> "PulseClient":
+    def __enter__(self) -> PulseClient:
         return self
 
     def __exit__(self, *exc: Any) -> None:
@@ -55,7 +60,9 @@ class PulseClient:
         try:
             resp = self._client.request(method, path, **kwargs)
         except httpx.TimeoutException as exc:
-            raise PulseEngineError(504, engine_message="The Pulse engine took too long to respond.") from exc
+            raise PulseEngineError(
+                504, engine_message="The Pulse engine took too long to respond."
+            ) from exc
         except httpx.RequestError as exc:
             raise PulseEngineError(
                 502, engine_message=f"Could not reach the Pulse engine at {self._client.base_url}."
@@ -97,7 +104,29 @@ class PulseClient:
     def tables(self, payload: dict) -> dict:
         return self._request("POST", "/tables", json=payload)
 
-    def generate_schema(self, *, prompt: Optional[str] = None, current_schema: Optional[str] = None) -> dict:
+    def charts(self, payload: dict) -> dict:
+        return self._request("POST", "/charts", json=payload)
+
+    def download_artifact(self, url: str) -> bytes:
+        """Download one chart artifact, authenticating only to the Pulse origin."""
+        resolved = urljoin(str(self._client.base_url), url)
+        api_origin = urlsplit(str(self._client.base_url))[:2]
+        artifact_origin = urlsplit(resolved)[:2]
+        if artifact_origin == api_origin:
+            response = self._client.get(resolved, follow_redirects=False)
+        else:
+            response = httpx.get(resolved, timeout=DEFAULT_TIMEOUT, follow_redirects=True)
+        if not response.is_success:
+            try:
+                body: Any = response.json()
+            except Exception:
+                body = response.text
+            raise PulseEngineError.from_response(response.status_code, body)
+        return response.content
+
+    def generate_schema(
+        self, *, prompt: str | None = None, current_schema: str | None = None
+    ) -> dict:
         data: dict[str, str] = {}
         if prompt is not None:
             data["prompt"] = prompt
@@ -116,7 +145,7 @@ class PulseClient:
         job_id: str,
         *,
         interval_seconds: float = POLL_INTERVAL_SECONDS,
-        on_progress: Optional[ProgressCallback] = None,
+        on_progress: ProgressCallback | None = None,
     ) -> dict:
         """Poll GET /job/{job_id} until terminal. The CLI polls indefinitely
         (unlike MCP's inline budget) — Ctrl-C leaves the job running server-side."""
@@ -134,7 +163,9 @@ class PulseClient:
         """Download an offloaded {is_url, url} result (pre-signed S3)."""
         resp = httpx.get(url, timeout=DEFAULT_TIMEOUT, follow_redirects=True)
         if not resp.is_success:
-            raise PulseEngineError(resp.status_code, engine_message="Failed to download result from URL.")
+            raise PulseEngineError(
+                resp.status_code, engine_message="Failed to download result from URL."
+            )
         if "application/json" in resp.headers.get("content-type", ""):
             return resp.json()
         try:
@@ -153,20 +184,23 @@ class PlatformClient:
             headers={"x-api-key": api_key, "user-agent": f"pulse-cli/{__version__}"},
         )
 
-    def __enter__(self) -> "PlatformClient":
+    def __enter__(self) -> PlatformClient:
         return self
 
     def __exit__(self, *exc: Any) -> None:
         self._client.close()
 
-    def _get(self, path: str, params: Optional[dict] = None) -> dict:
+    def _get(self, path: str, params: dict | None = None) -> dict:
         try:
             resp = self._client.get(path, params=params)
         except httpx.TimeoutException as exc:
-            raise PulseEngineError(504, engine_message="The Pulse platform took too long to respond.") from exc
+            raise PulseEngineError(
+                504, engine_message="The Pulse platform took too long to respond."
+            ) from exc
         except httpx.RequestError as exc:
             raise PulseEngineError(
-                502, engine_message=f"Could not reach the Pulse platform at {self._client.base_url}."
+                502,
+                engine_message=f"Could not reach the Pulse platform at {self._client.base_url}.",
             ) from exc
         if resp.is_success:
             return resp.json()
@@ -176,7 +210,7 @@ class PlatformClient:
             body = resp.text
         raise PulseEngineError.from_response(resp.status_code, body)
 
-    def subscription(self) -> Optional[dict]:
+    def subscription(self) -> dict | None:
         """GET /api/v1/billing/subscription — plan/status; None if unreachable."""
         try:
             return self._get("/api/v1/billing/subscription")
@@ -187,7 +221,7 @@ class PlatformClient:
         """GET /api/v1/analytics/usage/current-period — plan + pages for the billing cycle."""
         return self._get("/api/v1/analytics/usage/current-period")
 
-    def usage_breakdown(self, start_date: Optional[str] = None, end_date: Optional[str] = None) -> dict:
+    def usage_breakdown(self, start_date: str | None = None, end_date: str | None = None) -> dict:
         """GET /api/v1/analytics/usage/breakdown — docs/pages/latency, by source.
 
         Without dates the platform defaults to the current billing period

pulse_ai_cli-0.2.0/pulse_cli/commands/auth.py

@@ -0,0 +1,214 @@
+"""`pulse login` / `pulse logout` / `pulse whoami`."""
+
+from __future__ import annotations
+
+import webbrowser
+
+import typer
+
+from pulse_cli import config as cfg
+from pulse_cli import oauth
+from pulse_cli.client import PlatformClient, PulseClient
+from pulse_cli.errors import PulseCliError
+from pulse_cli.output import console, fail, print_json
+
+
+def login(
+    api_key: str | None = typer.Option(
+        None, "--api-key", help="Skip the browser and log in with an API key directly."
+    ),
+    base_url: str | None = typer.Option(
+        None, "--base-url", help="Engine URL override (default: api.runpulse.com)."
+    ),
+    platform_url: str | None = typer.Option(
+        None, "--platform-url", help="Platform API URL (enables `pulse usage`)."
+    ),
+    web: bool = typer.Option(
+        True,
+        "--web/--no-web",
+        help="Browser login (default). --no-web prompts for an API key instead.",
+    ),
+    device: bool = typer.Option(
+        False,
+        "--device",
+        help="Approve from another device, for machines with no browser (SSH, containers).",
+    ),
+) -> None:
+    """Log in via the browser (default) or with an API key; the key is validated, then stored securely."""
+    try:
+        conf = cfg.load(api_url_override=base_url)
+        cfg.ensure_keychain_reachable()
+        previous, previous_on = cfg.stored_api_key()
+    except PulseCliError as exc:
+        raise fail(str(exc)) from exc
+    except Exception as exc:  # a locked keychain or a denied keychain prompt
+        raise _keychain_failure("login", exc) from exc
+    purl = platform_url or conf.platform_url
+    minted: oauth.MintedKey | None = None
+    if api_key:
+        key = api_key
+    elif device or web:
+        minted = _device_flow_login(purl) if device else _browser_login(purl)
+        key = minted.api_key
+    else:
+        key = typer.prompt("Pulse API key", hide_input=True)
+    try:
+        key = key.strip()
+        if not key:
+            raise fail("empty API key")
+        console.print(f"[muted]Validating key against {conf.api_url} …[/muted]")
+        try:
+            with PulseClient(key, conf.api_url) as client:
+                pages = client.pages()
+        except PulseCliError as exc:
+            raise fail(str(exc)) from exc
+        minted_on = purl if minted else (previous_on if key == previous else None)
+        try:
+            store = cfg.save_api_key(
+                key, minted_on=minted_on, expires_at=minted.expires_at if minted else None
+            )
+        except Exception as exc:
+            raise fail(f"could not save the API key ({exc}); the stored key is unchanged.") from exc
+    except BaseException:
+        # Nothing holds a key minted for a login that did not finish.
+        if minted:
+            _delete_device_key(purl, key)
+        raise
+    # The device key this login replaces is held by nothing else.
+    if previous and previous_on and previous != key:
+        _delete_device_key(previous_on, previous)
+    if base_url or platform_url:
+        cfg.save_settings(api_url=base_url, platform_url=platform_url)
+
+    where = "OS keychain" if store == "keyring" else f"{cfg.CONFIG_PATH} (0600)"
+    console.print(f"[ok]Logged in.[/ok] Key {cfg.redact(key)} stored in {where}.")
+    if store == "file":
+        console.print(
+            "[yellow]No OS keychain is available here, so the key is stored in plain text, "
+            "readable only by you.[/yellow]"
+        )
+    if minted and minted.expires_at:
+        console.print(
+            f"[muted]It expires {minted.expires_at}; run `pulse login` again then.[/muted]"
+        )
+    console.print(f"[muted]Pages processed so far:[/muted] {pages.get('total_pages_processed', 0)}")
+
+
+def _browser_login(purl: str) -> oauth.MintedKey:
+    """Approve in this machine's browser, mint this device's own API key."""
+
+    def open_browser(url: str) -> None:
+        console.print("\n  Opening your browser. If it doesn't open, visit:")
+        # One unbroken line: rich folds a long word with real newlines, which a
+        # pasted URL turns into spaces.
+        console.print(f"  {url}", soft_wrap=True, markup=False, highlight=False)
+        console.print("  [muted]No browser on this machine? Use `pulse login --device`.[/muted]\n")
+        webbrowser.open(url)
+
+    try:
+        with console.status("[muted]Waiting for approval in the browser …[/muted]"):
+            tokens = oauth.browser_login(purl, open_browser)
+        return oauth.mint_api_key(purl, tokens["access_token"])
+    except PulseCliError as exc:
+        raise fail(str(exc)) from exc
+
+
+def _device_flow_login(purl: str) -> oauth.MintedKey:
+    """Device flow: type a code in a browser on any device, mint this device's own API key."""
+
+    try:
+        auth = oauth.device_authorization(purl)
+        console.print(f"\n  Go to: [link]{auth['verification_uri']}[/link]")
+        console.print(f"  Type this code: [bold]{auth['user_code']}[/bold]\n")
+        with console.status("[muted]Waiting for approval in the browser …[/muted]"):
+            tokens = oauth.poll_for_tokens(
+                purl,
+                auth["device_code"],
+                interval=int(auth.get("interval", 5)),
+                expires_in=int(auth.get("expires_in", 600)),
+            )
+        return oauth.mint_api_key(purl, tokens["access_token"])
+    except PulseCliError as exc:
+        raise fail(str(exc)) from exc
+
+
+def _keychain_failure(command: str, exc: Exception) -> SystemExit:
+    return fail(
+        f"could not read the OS keychain ({exc}); nothing was changed. Run `pulse {command}` again."
+    )
+
+
+def _delete_device_key(purl: str, key: str) -> bool:
+    """Delete a key `pulse login` minted; a failure only warns."""
+    try:
+        oauth.delete_api_key(purl, key)
+    except PulseCliError as exc:
+        console.print(
+            f"[yellow]Could not delete this device's API key {cfg.redact(key)} on the platform "
+            f"({exc}); it is still active, so remove it under API Keys in the dashboard.[/yellow]"
+        )
+        return False
+    return True
+
+
+def logout() -> None:
+    """Remove the stored API key; a key `pulse login` minted is deleted on the platform too.
+
+    The stored key is the one deleted even when ``PULSE_API_KEY`` overrides it for other commands.
+    """
+    try:
+        cfg.ensure_keychain_reachable()
+        stored, minted_on = cfg.stored_api_key()
+    except PulseCliError as exc:
+        raise fail(str(exc)) from exc
+    except Exception as exc:  # a locked keychain or a denied keychain prompt
+        raise _keychain_failure("logout", exc) from exc
+    deleted = ""
+    if stored and minted_on and _delete_device_key(minted_on, stored):
+        deleted = " Its API key was deleted on the platform."
+    if cfg.clear_api_key():
+        console.print(f"[ok]Logged out.[/ok] Stored API key removed.{deleted}")
+    elif stored:
+        console.print(
+            f"[yellow]Could not remove the stored API key from the OS keychain.{deleted} "
+            "Run `pulse logout` again.[/yellow]"
+        )
+    else:
+        console.print("[muted]No stored API key found.[/muted]")
+
+
+def whoami(
+    json_out: bool = typer.Option(False, "--json", help="Machine-readable output."),
+    base_url: str | None = typer.Option(None, "--base-url", help="Engine URL override."),
+) -> None:
+    """Show the active key (redacted), where it came from, and account status."""
+    conf = cfg.load(api_url_override=base_url)
+    if not conf.api_key:
+        raise fail("not logged in. Run `pulse login`.")
+
+    info: dict = {
+        "api_key": cfg.redact(conf.api_key),
+        "key_source": conf.key_source,
+        "expires_at": conf.expires_at
+        and f"{conf.expires_at}{' (expired)' if conf.expired else ''}",
+        "api_url": conf.api_url,
+    }
+    try:
+        with PulseClient(conf.api_key, conf.api_url) as client:
+            info["total_pages_processed"] = client.pages().get("total_pages_processed")
+    except PulseCliError as exc:
+        info["status"] = f"key check failed: {exc}"
+
+    if conf.platform_url:
+        with PlatformClient(conf.api_key, conf.platform_url) as pc:
+            sub = pc.subscription()
+        if sub:
+            info["plan"] = sub.get("plan") or sub.get("plan_name")
+            info["subscription_status"] = sub.get("status")
+
+    if json_out:
+        print_json(info)
+        return
+    for k, v in info.items():
+        if v is not None:
+            console.print(f"[muted]{k:24}[/muted] [body]{v}[/body]")

pulse_ai_cli-0.2.0/pulse_cli/commands/charts.py

@@ -0,0 +1,116 @@
+"""`pulse charts` — reconstruct charts from an extraction or split."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import typer
+
+from pulse_cli.output import console, fail, print_json
+from pulse_cli.runtime import get_client, resolve_offloaded_result, submit_and_poll
+from pulse_cli.status import is_terminal
+
+EXPORT_FORMATS = {"excel", "csv", "las"}
+
+
+def charts(
+    extraction_id: str | None = typer.Argument(
+        None, help="ID of a completed extraction (omit when using --split-id)."
+    ),
+    split_id: str | None = typer.Option(None, "--split-id", help="ID of a completed split result."),
+    data_points: int = typer.Option(
+        20, "--data-points", min=2, max=500, help="Points returned per series."
+    ),
+    agentic_zoom: bool = typer.Option(
+        False, "--agentic-zoom", help="Refine small chart regions at full resolution."
+    ),
+    page_range: str | None = typer.Option(None, "--pages", help='Extraction pages, e.g. "1-3,5".'),
+    export: list[str] = typer.Option(
+        [],
+        "--export",
+        "-e",
+        help="Repeatable export format: excel, csv, or las. Defaults to excel.",
+    ),
+    download_exports: Path | None = typer.Option(
+        None,
+        "--download-exports",
+        help="Consume the one-time export links and write them to this directory.",
+    ),
+    output: Path | None = typer.Option(
+        None, "--output", "-o", help="Write the complete response JSON to a file."
+    ),
+    no_wait: bool = typer.Option(
+        False, "--no-wait", help="Submit and print the chart job ID without polling."
+    ),
+    json_out: bool = typer.Option(False, "--json"),
+    api_key: str | None = typer.Option(None, "--api-key", envvar="PULSE_API_KEY"),
+    base_url: str | None = typer.Option(None, "--base-url"),
+) -> None:
+    """Reconstruct chart data from a completed extraction or split."""
+    if bool(extraction_id) == bool(split_id):
+        raise fail("provide exactly one extraction_id or --split-id")
+    if split_id and page_range:
+        raise fail("--pages cannot be used with --split-id; pages come from the split")
+
+    formats = [value.strip().lower() for value in export] if export else ["excel"]
+    invalid = sorted(set(formats) - EXPORT_FORMATS)
+    if invalid:
+        raise fail(f"unsupported --export value: {', '.join(invalid)}")
+    formats = list(dict.fromkeys(formats))
+
+    payload = {
+        **({"extraction_id": extraction_id} if extraction_id else {}),
+        **({"split_id": split_id} if split_id else {}),
+        **({"page_range": page_range.strip()} if page_range and page_range.strip() else {}),
+        "async": True,
+        "charts_config": {
+            "data_points": data_points,
+            "agentic_zoom": agentic_zoom,
+            "export_formats": formats,
+        },
+    }
+
+    with get_client(api_key, base_url) as client:
+        submit = client.charts(payload)
+        job = submit_and_poll(client, submit, label="extracting charts", no_wait=no_wait)
+        if no_wait and job.get("job_id"):
+            console.print(f"[muted]submitted →[/muted] [brand]{job['job_id']}[/brand]")
+            return
+        status = str(job.get("status") or "").lower()
+        if is_terminal(status) and status != "completed":
+            error = job.get("error") or f"Chart extraction {status}."
+            raise fail(str(error))
+        job = resolve_offloaded_result(client, job)
+        result = job.get("result") if isinstance(job.get("result"), dict) else job
+        downloaded: list[str] = []
+        if download_exports:
+            download_exports.mkdir(parents=True, exist_ok=True)
+            for artifact in result.get("exports", []):
+                filename = Path(str(artifact.get("filename") or "chart-export")).name
+                destination = download_exports / filename
+                destination.write_bytes(client.download_artifact(artifact["url"]))
+                downloaded.append(str(destination))
+
+    if downloaded:
+        result = {**result, "downloaded_exports": downloaded}
+    if output:
+        output.write_text(json.dumps(result, indent=2, default=str))
+        console.print(f"[ok]✓[/ok] wrote {output}")
+    elif json_out:
+        print_json(result)
+    else:
+        console.print(
+            f"[muted]charts_id =[/muted] [brand]{result.get('charts_id', 'unknown')}[/brand] "
+            f"[muted]· {result.get('count', 0)} chart(s)[/muted]"
+        )
+        print_json(result.get("charts") or result.get("results") or [])
+        if downloaded:
+            for path in downloaded:
+                console.print(f"[muted]SAVED:[/muted] {path}")
+        else:
+            for artifact in result.get("exports", []):
+                console.print(
+                    f"[muted]{str(artifact.get('format', 'export')).upper()}:[/muted] "
+                    f"{artifact.get('url')}"
+                )