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

vocalize_cli-0.4.0/CHANGELOG.md

@@ -0,0 +1,89 @@
+# Changelog
+
+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 auth` command group for storing your ElevenLabs API key in the OS
+  keychain (macOS Keychain, Windows Credential Locker, or Linux Secret
+  Service) instead of an environment variable or `.env` file.
+  - `vocalize auth login` prompts for the key (hidden input), validates it
+    against the ElevenLabs API, and stores it. `--stdin` reads the key from a
+    pipe instead, for secret managers — e.g.
+    `op read op://vault/elevenlabs/key | vocalize auth login --stdin`.
+  - `vocalize auth status` shows where the active key is coming from (flag,
+    environment, `.env` file, keychain, or not found), with a masked preview.
+  - `vocalize auth logout` removes the stored key.
+- `vocalize config` now offers to set up your API key when none is found,
+  before walking through voice, model, and speed — so setup is install, then
+  `vocalize config`, done.
+
+### Changed
+
+- API key resolution order is now: `--api-key` flag, then
+  `ELEVENLABS_API_KEY`, then a `.env` file in the current directory, then the
+  OS keychain.
+
+## 0.2.1
+
+### Fixed
+
+- The config wizard now paints on the controlling terminal (`/dev/tty`)
+  instead of stdout, so it still works under output-capturing wrappers like
+  `op run` instead of corrupting their captured output.
+
+## 0.2.0
+
+### Added
+
+- A TOML config file (`~/.config/vocalize/config.toml` or
+  `$XDG_CONFIG_HOME/vocalize/config.toml`) and matching environment
+  variables for voice, model, and speed, resolved as flag, then env var,
+  then config file, then default.
+- `--speed` flag and `speed` config/env setting (0.7-1.2).
+- `vocalize config`, an interactive wizard that walks through voice (with a
+  live preview of the highlighted choice), model, and speed, then writes the
+  config file — no need to hand-write TOML.
+
+## 0.1.1
+
+### Added
+
+- `--latest` flag on the Claude Code Stop hook, for speaking your most
+  recent response on demand instead of installing an automatic hook.
+
+### Changed
+
+- Fenced code blocks are now spoken as a single short placeholder instead of
+  being read out character by character.
+
+### Fixed
+
+- The CLI's reported version now comes from one place instead of two.
+
+## 0.1.0
+
+Initial release.
+
+### Added
+
+- `vocalize speak`, `vocalize speak-file`, and `vocalize voices` commands,
+  backed by the ElevenLabs TTS API.
+- A markdown-to-speech preprocessing pass: tables, bullet lists, links, and
+  code blocks are rewritten into short declarative sentences before
+  synthesis.
+- A disk cache keyed by a hash of (text, voice, model, format, speed), so
+  repeat runs don't re-spend API quota.
+- A Claude Code Stop hook (`hooks/claude_stop_hook.py`,
+  `hooks/install_hook.py`) that speaks Claude's response after every turn.
+- Published to PyPI as `vocalize-cli`; CI running lint and tests with
+  coverage on every push.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: vocalize-cli
-Version: 0.2.1
+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
@@ -20,6 +20,7 @@ Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
 Requires-Python: >=3.10
 Requires-Dist: click>=8.1
 Requires-Dist: elevenlabs>=2.0
+Requires-Dist: keyring>=25
 Requires-Dist: tomli>=2.0; python_version < '3.11'
 Provides-Extra: dev
 Requires-Dist: build; extra == 'dev'
@@ -40,6 +41,25 @@ natural-sounding speech using the [ElevenLabs](https://elevenlabs.io) API —
 plus a hook that wires it directly into [Claude Code](https://claude.com/claude-code),
 so Claude's responses get read aloud automatically in your terminal or IDE.
 
+## Quickstart
+
+```bash
+pipx install vocalize-cli
+```
+
+```bash
+vocalize config
+```
+
+Walks you through your API key, a voice, and a speed, and saves it all.
+
+```bash
+vocalize speak "hello"
+```
+
+To set up just the key, skip the wizard and run `vocalize auth login` — it
+stores the key in your OS keychain.
+
 ## Why this exists
 
 Text-to-speech readers are good at *voices* and bad at *structure*. Point one
@@ -79,7 +99,23 @@ pip install -e .
 Get a free ElevenLabs API key at
 [elevenlabs.io/app/settings/api-keys](https://elevenlabs.io/app/settings/api-keys)
 (free tier: 10,000 characters/month, API access included, no commercial
-license). Then either:
+license). Then, recommended, store it in your OS keychain:
+
+```bash
+vocalize auth login
+```
+
+This prompts for the key (input hidden), validates it against the
+ElevenLabs API, and stores it via your OS's own keychain (macOS Keychain,
+Windows Credential Locker, Linux Secret Service) — no plaintext file to
+manage. Piping it in from a secret manager works too:
+
+```bash
+op read op://vault/elevenlabs/key | vocalize auth login --stdin
+```
+
+An environment variable or `.env` file work as well, and take priority over
+the keychain if both are set:
 
 ```bash
 export ELEVENLABS_API_KEY=your-key-here
@@ -103,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
@@ -146,6 +185,7 @@ writing anything.
 
 | Setting | Flag | Env var | Config file key | Default |
 |---|---|---|---|---|
+| API key | `--api-key` | `ELEVENLABS_API_KEY` | not read from the config file | stored via `vocalize auth` |
 | Voice ID | `--voice` | `VOCALIZE_VOICE` | `voice` | `21m00Tcm4TlvDq8ikWAM` ("Rachel") |
 | Model ID | `--model` | `VOCALIZE_MODEL` | `model` | `eleven_multilingual_v2` |
 | Speed | `--speed` | `VOCALIZE_SPEED` | `speed` | unset — the API's own 1.0 |
@@ -167,8 +207,11 @@ stderr, so a typo doesn't pass unnoticed but doesn't stop the run either.
 `speed` must be a number between 0.7 and 1.2 — anything else is a one-line
 error naming the source it came from.
 
-The API key is separate and never read from this file: use `--api-key`,
-`ELEVENLABS_API_KEY`, or a `.env` file.
+The API key is separate and never read from this file. It resolves in its
+own order: `--api-key` flag, then `ELEVENLABS_API_KEY`, then a `.env` file
+in the current directory, then the OS keychain. `vocalize auth login` sets
+up the keychain entry; `vocalize auth status` shows which of those sources
+is currently supplying the key.
 
 ## Claude Code integration
 
@@ -218,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:
@@ -293,8 +366,8 @@ All tests run offline: the ElevenLabs client is dependency-injected into
   so it's always safe to delete some or all of it — nothing will break,
   you'll just re-pay for a re-synthesized clip.
 - **`--api-key` on the command line is visible to other local processes**
-  (anything that can run `ps`). Prefer the `ELEVENLABS_API_KEY` environment
-  variable or a `.env` file instead.
+  (anything that can run `ps`). Prefer `vocalize auth login`, the
+  `ELEVENLABS_API_KEY` environment variable, or a `.env` file instead.
 - `vocalize voices` lists only the first page of results from the
   ElevenLabs API.
 

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

@@ -7,6 +7,25 @@ natural-sounding speech using the [ElevenLabs](https://elevenlabs.io) API —
 plus a hook that wires it directly into [Claude Code](https://claude.com/claude-code),
 so Claude's responses get read aloud automatically in your terminal or IDE.
 
+## Quickstart
+
+```bash
+pipx install vocalize-cli
+```
+
+```bash
+vocalize config
+```
+
+Walks you through your API key, a voice, and a speed, and saves it all.
+
+```bash
+vocalize speak "hello"
+```
+
+To set up just the key, skip the wizard and run `vocalize auth login` — it
+stores the key in your OS keychain.
+
 ## Why this exists
 
 Text-to-speech readers are good at *voices* and bad at *structure*. Point one
@@ -46,7 +65,23 @@ pip install -e .
 Get a free ElevenLabs API key at
 [elevenlabs.io/app/settings/api-keys](https://elevenlabs.io/app/settings/api-keys)
 (free tier: 10,000 characters/month, API access included, no commercial
-license). Then either:
+license). Then, recommended, store it in your OS keychain:
+
+```bash
+vocalize auth login
+```
+
+This prompts for the key (input hidden), validates it against the
+ElevenLabs API, and stores it via your OS's own keychain (macOS Keychain,
+Windows Credential Locker, Linux Secret Service) — no plaintext file to
+manage. Piping it in from a secret manager works too:
+
+```bash
+op read op://vault/elevenlabs/key | vocalize auth login --stdin
+```
+
+An environment variable or `.env` file work as well, and take priority over
+the keychain if both are set:
 
 ```bash
 export ELEVENLABS_API_KEY=your-key-here
@@ -70,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
@@ -113,6 +151,7 @@ writing anything.
 
 | Setting | Flag | Env var | Config file key | Default |
 |---|---|---|---|---|
+| API key | `--api-key` | `ELEVENLABS_API_KEY` | not read from the config file | stored via `vocalize auth` |
 | Voice ID | `--voice` | `VOCALIZE_VOICE` | `voice` | `21m00Tcm4TlvDq8ikWAM` ("Rachel") |
 | Model ID | `--model` | `VOCALIZE_MODEL` | `model` | `eleven_multilingual_v2` |
 | Speed | `--speed` | `VOCALIZE_SPEED` | `speed` | unset — the API's own 1.0 |
@@ -134,8 +173,11 @@ stderr, so a typo doesn't pass unnoticed but doesn't stop the run either.
 `speed` must be a number between 0.7 and 1.2 — anything else is a one-line
 error naming the source it came from.
 
-The API key is separate and never read from this file: use `--api-key`,
-`ELEVENLABS_API_KEY`, or a `.env` file.
+The API key is separate and never read from this file. It resolves in its
+own order: `--api-key` flag, then `ELEVENLABS_API_KEY`, then a `.env` file
+in the current directory, then the OS keychain. `vocalize auth login` sets
+up the keychain entry; `vocalize auth status` shows which of those sources
+is currently supplying the key.
 
 ## Claude Code integration
 
@@ -185,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:
@@ -260,8 +332,8 @@ All tests run offline: the ElevenLabs client is dependency-injected into
   so it's always safe to delete some or all of it — nothing will break,
   you'll just re-pay for a re-synthesized clip.
 - **`--api-key` on the command line is visible to other local processes**
-  (anything that can run `ps`). Prefer the `ELEVENLABS_API_KEY` environment
-  variable or a `.env` file instead.
+  (anything that can run `ps`). Prefer `vocalize auth login`, the
+  `ELEVENLABS_API_KEY` environment variable, or a `.env` file instead.
 - `vocalize voices` lists only the first page of results from the
   ElevenLabs API.
 

{vocalize_cli-0.2.1 → vocalize_cli-0.4.0}/pyproject.toml

@@ -25,6 +25,7 @@ classifiers = [
 dependencies = [
     "elevenlabs>=2.0",
     "click>=8.1",
+    "keyring>=25",
     "tomli>=2.0; python_version < '3.11'",
 ]
 

vocalize_cli-0.4.0/tests/conftest.py

@@ -0,0 +1,56 @@
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "hooks"))
+
+import pytest
+
+
+@pytest.fixture(autouse=True)
+def _no_dotenv(monkeypatch):
+    """Prevent tests from loading the developer's real .env file."""
+    monkeypatch.setattr("vocalize.config._load_dotenv_if_present", lambda: None)
+
+
+class _FakeKeychain(dict):
+    """The stored entries, plus the switches a test needs to break them."""
+
+    deny_delete = False
+
+
+class _FakeKeyring:
+    """An in-memory stand-in for the keyring module's three calls."""
+
+    def __init__(self, store):
+        self._store = store
+
+    def get_password(self, service, username):
+        return self._store.get((service, username))
+
+    def set_password(self, service, username, password):
+        self._store[(service, username)] = password
+
+    def delete_password(self, service, username):
+        from keyring.errors import PasswordDeleteError
+
+        if self._store.deny_delete:
+            # The macOS backend's worst habit: a denied or locked keychain
+            # raises the very same error a missing entry does, while the
+            # entry is still sitting there.
+            raise PasswordDeleteError("failed to delete password")
+        if self._store.pop((service, username), None) is None:
+            raise PasswordDeleteError("no such password")
+
+
+@pytest.fixture(autouse=True)
+def fake_keychain(monkeypatch):
+    """Keep every test off the real OS keychain.
+
+    Autouse because the damage of missing one is silent: a stored key on
+    the developer's machine would otherwise satisfy resolve_api_key and
+    quietly turn the "no key found" tests green for the wrong reason.
+    Request it by name to seed, inspect, or break the store.
+    """
+    store = _FakeKeychain()
+    monkeypatch.setattr("vocalize.auth._backend", lambda: _FakeKeyring(store))
+    return store