vocalize-cli 0.3.0__tar.gz → 0.4.0__tar.gz

{vocalize_cli-0.3.0 → vocalize_cli-0.4.0}/CHANGELOG.md

@@ -3,6 +3,12 @@
 All notable changes to this project are documented here. Format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## 0.4.0
+
+### Added
+
+- `vocalize usage` — ElevenLabs quota and local cache at a glance.
+
 ## 0.3.0
 
 ### Added

{vocalize_cli-0.3.0 → vocalize_cli-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: vocalize-cli
-Version: 0.3.0
+Version: 0.4.0
 Summary: A CLI that turns text, markdown, or piped stdin into speech via the ElevenLabs API, with markdown-table-aware preprocessing.
 Project-URL: Homepage, https://github.com/matthager12-collab/vocalize
 Project-URL: Repository, https://github.com/matthager12-collab/vocalize
@@ -139,6 +139,9 @@ cat notes.md | vocalize speak-file -
 # List available voices and grab an ID
 vocalize voices
 
+# Check your quota and cache
+vocalize usage
+
 # Use a specific voice/model, save without playing
 vocalize speak-file report.md --voice <voice-id> --model eleven_flash_v2_5 \
   --output out.mp3 --no-play
@@ -258,6 +261,36 @@ run in Claude Code's own environment, not your interactive shell — if
 `VOCALIZE_BIN` to the full path (e.g. `/path/to/.venv/bin/vocalize`) to
 point the hook at it directly.
 
+### Speaking files, artifacts, and more
+
+Two primitives cover almost everything: `vocalize speak-file <path>` speaks
+any local file (markdown flattened first), and the hook's `--latest` mode
+speaks the most recent Claude Code response. Anything Claude itself has to
+fetch — a claude.ai artifact, for instance — has to be fetched *by Claude*
+(the CLI has no session), summarized, and piped in:
+
+```bash
+printf '%s' "the summary text" | vocalize speak-file -
+```
+
+If you wire this into a slash command of your own, treat it as a security
+surface, because **every character you speak is sent to ElevenLabs**. The
+guard principles that matter, in order:
+
+1. Resolve paths (`realpath`, expand `~`, casefold) and check an
+   **allow-list** of speakable directories — symlinks and `../` defeat
+   string matching on the raw argument.
+2. Hard-refuse secret-shaped files (`.env*`, keys, credentials) and your
+   sensitive directories; confirm before speaking anything else unusual.
+3. Summarize long or fetched content in an **isolated subagent** that
+   returns only the summary — content you fetched can carry instructions
+   aimed at your session.
+4. Pipe summaries over stdin (as above) — no temp files, nothing in argv.
+5. Confirm before any read that will spend real quota; a free tier is
+   10,000 characters a month.
+6. Remember the disk cache: everything spoken leaves an mp3 under
+   `~/.cache/vocalize/`.
+
 ## How it's built
 
 Four decisions shaped the design:

{vocalize_cli-0.3.0 → vocalize_cli-0.4.0}/README.md

@@ -105,6 +105,9 @@ cat notes.md | vocalize speak-file -
 # List available voices and grab an ID
 vocalize voices
 
+# Check your quota and cache
+vocalize usage
+
 # Use a specific voice/model, save without playing
 vocalize speak-file report.md --voice <voice-id> --model eleven_flash_v2_5 \
   --output out.mp3 --no-play
@@ -224,6 +227,36 @@ run in Claude Code's own environment, not your interactive shell — if
 `VOCALIZE_BIN` to the full path (e.g. `/path/to/.venv/bin/vocalize`) to
 point the hook at it directly.
 
+### Speaking files, artifacts, and more
+
+Two primitives cover almost everything: `vocalize speak-file <path>` speaks
+any local file (markdown flattened first), and the hook's `--latest` mode
+speaks the most recent Claude Code response. Anything Claude itself has to
+fetch — a claude.ai artifact, for instance — has to be fetched *by Claude*
+(the CLI has no session), summarized, and piped in:
+
+```bash
+printf '%s' "the summary text" | vocalize speak-file -
+```
+
+If you wire this into a slash command of your own, treat it as a security
+surface, because **every character you speak is sent to ElevenLabs**. The
+guard principles that matter, in order:
+
+1. Resolve paths (`realpath`, expand `~`, casefold) and check an
+   **allow-list** of speakable directories — symlinks and `../` defeat
+   string matching on the raw argument.
+2. Hard-refuse secret-shaped files (`.env*`, keys, credentials) and your
+   sensitive directories; confirm before speaking anything else unusual.
+3. Summarize long or fetched content in an **isolated subagent** that
+   returns only the summary — content you fetched can carry instructions
+   aimed at your session.
+4. Pipe summaries over stdin (as above) — no temp files, nothing in argv.
+5. Confirm before any read that will spend real quota; a free tier is
+   10,000 characters a month.
+6. Remember the disk cache: everything spoken leaves an mp3 under
+   `~/.cache/vocalize/`.
+
 ## How it's built
 
 Four decisions shaped the design:

{vocalize_cli-0.3.0 → vocalize_cli-0.4.0}/tests/test_cli.py

@@ -255,6 +255,51 @@ def test_no_speed_flag_leaves_speed_unset(monkeypatch, tmp_path):
     assert captured_settings[0].speed is None
 
 
+def test_usage_command_prints_tier_used_limit_and_percent(monkeypatch, tmp_path):
+    monkeypatch.setattr(cli_module, "build_client", lambda key: object())
+    monkeypatch.setattr(
+        cli_module,
+        "get_usage",
+        lambda client: {"tier": "creator", "used": 12345, "limit": 100000, "resets_at": None},
+    )
+    # Empty tmp_path also covers the "cache empty" branch.
+    monkeypatch.setattr(cli_module, "DEFAULT_CACHE_DIR", tmp_path)
+    runner = CliRunner()
+
+    result = runner.invoke(main, ["usage", "--api-key", "fake-key"])
+
+    assert result.exit_code == 0, result.output
+    assert "creator" in result.output
+    assert "12,345" in result.output
+    assert "100,000" in result.output
+    assert "12.3%" in result.output
+    assert "cache empty" in result.output
+
+
+def test_usage_command_reports_local_cache_file_count(monkeypatch, tmp_path):
+    from datetime import datetime, timezone
+
+    reset_unix = 1735689600
+    expected_date = datetime.fromtimestamp(reset_unix, tz=timezone.utc).astimezone().strftime("%Y-%m-%d")
+    monkeypatch.setattr(cli_module, "build_client", lambda key: object())
+    monkeypatch.setattr(
+        cli_module,
+        "get_usage",
+        lambda client: {"tier": "free", "used": 0, "limit": 10000, "resets_at": reset_unix},
+    )
+    (tmp_path / "a.mp3").write_bytes(b"x" * 1000)
+    (tmp_path / "b.mp3").write_bytes(b"y" * 2000)
+    (tmp_path / "not-audio.txt").write_bytes(b"ignore me")
+    monkeypatch.setattr(cli_module, "DEFAULT_CACHE_DIR", tmp_path)
+    runner = CliRunner()
+
+    result = runner.invoke(main, ["usage", "--api-key", "fake-key"])
+
+    assert result.exit_code == 0, result.output
+    assert "2 files" in result.output
+    assert expected_date in result.output
+
+
 def test_invalid_speed_gives_a_clean_error_not_a_traceback(monkeypatch, tmp_path, capsys):
     _isolate_config(monkeypatch, tmp_path)
     monkeypatch.setattr(

{vocalize_cli-0.3.0 → vocalize_cli-0.4.0}/tests/test_tts.py

@@ -6,7 +6,7 @@ import pytest
 
 from vocalize.config import Settings
 from vocalize.exceptions import TTSRequestError
-from vocalize.tts import _cache_key, list_voices, synthesize
+from vocalize.tts import _cache_key, get_usage, list_voices, synthesize
 
 
 class FakeTTSNamespace:
@@ -30,6 +30,26 @@ class FakeVoicesNamespace:
         return SimpleNamespace(voices=self._voices)
 
 
+class FakeUserNamespace:
+    def __init__(self, tier="free", used=1000, limit=10000, resets_at=1700000000, raise_error=None):
+        self._tier = tier
+        self._used = used
+        self._limit = limit
+        self._resets_at = resets_at
+        self._raise_error = raise_error
+        self.subscription = SimpleNamespace(get=self._get)
+
+    def _get(self):
+        if self._raise_error:
+            raise self._raise_error
+        return SimpleNamespace(
+            tier=self._tier,
+            character_count=self._used,
+            character_limit=self._limit,
+            next_character_count_reset_unix=self._resets_at,
+        )
+
+
 class FakeClient:
     def __init__(self, chunks=(b"fake", b"-audio"), raise_error=None, voices=None):
         self.text_to_speech = FakeTTSNamespace(chunks=chunks, raise_error=raise_error)
@@ -144,3 +164,28 @@ def test_cache_key_is_unchanged_when_speed_is_unset():
     old_payload = f"{settings.voice_id}|{settings.model_id}|{settings.output_format}|hi"
 
     assert _cache_key("hi", settings) == hashlib.sha256(old_payload.encode("utf-8")).hexdigest()
+
+
+def test_get_usage_returns_tier_used_limit_and_reset():
+    client = SimpleNamespace(
+        user=FakeUserNamespace(tier="creator", used=4200, limit=100000, resets_at=1735689600)
+    )
+
+    result = get_usage(client)
+
+    assert result == {"tier": "creator", "used": 4200, "limit": 100000, "resets_at": 1735689600}
+
+
+def test_get_usage_passes_through_a_missing_reset_time():
+    client = SimpleNamespace(user=FakeUserNamespace(resets_at=None))
+
+    result = get_usage(client)
+
+    assert result["resets_at"] is None
+
+
+def test_get_usage_wraps_sdk_errors():
+    client = SimpleNamespace(user=FakeUserNamespace(raise_error=RuntimeError("unauthorized")))
+
+    with pytest.raises(TTSRequestError, match="unauthorized"):
+        get_usage(client)

{vocalize_cli-0.3.0 → vocalize_cli-0.4.0}/vocalize/__init__.py

@@ -7,4 +7,4 @@ formatting into something that actually sounds good spoken aloud
 which is close to useless).
 """
 
-__version__ = "0.3.0"
+__version__ = "0.4.0"

{vocalize_cli-0.3.0 → vocalize_cli-0.4.0}/vocalize/cli.py

@@ -4,6 +4,7 @@
     vocalize speak-file report.md --play
     cat notes.md | vocalize speak-file - --play
     vocalize voices
+    vocalize usage
     vocalize config
     vocalize auth login
 """
@@ -11,6 +12,7 @@
 from __future__ import annotations
 
 import sys
+from datetime import datetime, timezone
 from pathlib import Path
 
 import click
@@ -22,7 +24,7 @@ from .auth import delete_key, key_source, login, masked, probe_keychain, prompt_
 from .config import DEFAULT_MODEL, DEFAULT_VOICE, resolve_api_key, resolve_settings
 from .exceptions import TTSRequestError, VocalizeError
 from .preprocess import flatten_markdown, truncate_for_budget
-from .tts import DEFAULT_CACHE_DIR, build_client, list_voices, synthesize
+from .tts import DEFAULT_CACHE_DIR, build_client, get_usage, list_voices, synthesize
 from .wizard import run_wizard
 
 
@@ -107,6 +109,47 @@ def voices(api_key) -> None:
         click.echo(f"{v['id']}\t{v['name']}")
 
 
+def _human_readable_size(num_bytes: int) -> str:
+    size = float(num_bytes)
+    for unit in ("B", "KB", "MB", "GB"):
+        if size < 1024 or unit == "GB":
+            return f"{size:.0f} {unit}" if unit == "B" else f"{size:.1f} {unit}"
+        size /= 1024
+    return f"{size:.1f} GB"
+
+
+@main.command()
+@click.option("--api-key", default=None)
+def usage(api_key) -> None:
+    """Show ElevenLabs quota usage and local cache stats."""
+    key = resolve_api_key(api_key)
+    client = build_client(key)
+    stats = get_usage(client)
+
+    used, limit = stats["used"], stats["limit"]
+    percent = (used / limit * 100) if limit else 0.0
+    remaining = max(limit - used, 0)
+
+    click.echo(f"Tier: {stats['tier']}")
+    click.echo(f"Used: {used:,} / {limit:,} characters ({percent:.1f}%)")
+    click.echo(f"Remaining: {remaining:,} characters")
+    if stats["resets_at"] is not None:
+        # UTC-aware, then converted to the system's local zone explicitly —
+        # a bare fromtimestamp() is implicitly local, which ruff (DTZ006)
+        # flags as ambiguous.
+        local_reset = datetime.fromtimestamp(stats["resets_at"], tz=timezone.utc).astimezone()
+        click.echo(f"Resets: {local_reset.strftime('%Y-%m-%d')}")
+
+    click.echo("")
+    # Local cache stats are pure filesystem lookups — no API call, no quota.
+    cache_files = list(DEFAULT_CACHE_DIR.glob("*.mp3")) if DEFAULT_CACHE_DIR.is_dir() else []
+    if not cache_files:
+        click.echo("Local cache: cache empty")
+    else:
+        total_bytes = sum(f.stat().st_size for f in cache_files)
+        click.echo(f"Local cache: {len(cache_files)} files, {_human_readable_size(total_bytes)}")
+
+
 @main.command("config")
 def config_cmd() -> None:
     """Interactive setup: pick voice, model, and speed."""

{vocalize_cli-0.3.0 → vocalize_cli-0.4.0}/vocalize/tts.py

@@ -110,6 +110,25 @@ def list_voices(client) -> list[dict]:
     ]
 
 
+def get_usage(client) -> dict:
+    """Return ElevenLabs subscription usage: tier, used, limit, resets_at.
+
+    `resets_at` is the unix timestamp of the next character-count reset,
+    or None on tiers that don't report one. This call costs no quota.
+    """
+    try:
+        subscription = client.user.subscription.get()
+    except Exception as exc:
+        raise TTSRequestError(f"Could not fetch usage: {exc}") from exc
+
+    return {
+        "tier": subscription.tier,
+        "used": subscription.character_count,
+        "limit": subscription.character_limit,
+        "resets_at": subscription.next_character_count_reset_unix,
+    }
+
+
 def build_client(api_key: str):
     """Construct the real ElevenLabs SDK client. Imported lazily so the
     rest of the package (and its tests) don't require the `elevenlabs`