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

vocalize_cli-0.3.0/CHANGELOG.md

@@ -0,0 +1,83 @@
+# Changelog
+
+All notable changes to this project are documented here. Format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## 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.0 → vocalize_cli-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: vocalize-cli
-Version: 0.2.0
+Version: 0.3.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
@@ -133,7 +169,8 @@ the highlighted one), model, and speed — shows you a summary, and writes the
 config file below. Unrecognised top-level keys already in that file are
 carried through; comments and layout are not preserved. A file containing a
 TOML table or array is left alone entirely, with a message saying to edit it
-by hand.
+by hand. The wizard paints on the controlling terminal rather than on stdout,
+so it still works under output-capturing wrappers like `op run`.
 
 ```bash
 vocalize config
@@ -145,6 +182,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 |
@@ -166,8 +204,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
 
@@ -292,8 +333,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.0 → vocalize_cli-0.3.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
@@ -100,7 +135,8 @@ the highlighted one), model, and speed — shows you a summary, and writes the
 config file below. Unrecognised top-level keys already in that file are
 carried through; comments and layout are not preserved. A file containing a
 TOML table or array is left alone entirely, with a message saying to edit it
-by hand.
+by hand. The wizard paints on the controlling terminal rather than on stdout,
+so it still works under output-capturing wrappers like `op run`.
 
 ```bash
 vocalize config
@@ -112,6 +148,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 |
@@ -133,8 +170,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
 
@@ -259,8 +299,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.0 → vocalize_cli-0.3.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.3.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

vocalize_cli-0.3.0/tests/test_auth.py

@@ -0,0 +1,333 @@
+import pytest
+from click.testing import CliRunner
+
+from vocalize import auth
+from vocalize.cli import main
+from vocalize.config import _load_dotenv_if_present
+from vocalize.exceptions import AuthError, TTSRequestError
+
+# Bound at import time on purpose: conftest's autouse fixture replaces the
+# module attribute, so this reference is the only way to reach the real one.
+real_load_dotenv = _load_dotenv_if_present
+
+ENTRY = (auth.SERVICE, auth.USERNAME)
+SECRET = "sk_supersecret1234567890"
+
+
+@pytest.fixture
+def no_env_key(monkeypatch):
+    monkeypatch.delenv("ELEVENLABS_API_KEY", raising=False)
+
+
+def _fake_tts(monkeypatch, *, failure=None):
+    """Swap the real ElevenLabs client out of the validation path."""
+    seen = []
+
+    def build_client(key):
+        seen.append(key)
+        return object()
+
+    def list_voices(client):
+        if failure is not None:
+            raise TTSRequestError(failure)
+        return [{"id": "abc123", "name": "Rachel"}]
+
+    monkeypatch.setattr("vocalize.tts.build_client", build_client)
+    monkeypatch.setattr("vocalize.tts.list_voices", list_voices)
+    return seen
+
+
+class _BrokenKeyring:
+    """A backend that fails the way a locked or absent keychain does."""
+
+    def get_password(self, service, username):
+        raise RuntimeError("no recommended backend")
+
+    def set_password(self, service, username, password):
+        raise RuntimeError("no recommended backend")
+
+    def delete_password(self, service, username):
+        raise RuntimeError("no recommended backend")
+
+
+class _FakeReadFailure:
+    """Delete appears to work; the read-back that would confirm it doesn't."""
+
+    def __init__(self, store):
+        self._store = store
+
+    def get_password(self, service, username):
+        raise RuntimeError("keychain locked")
+
+    def delete_password(self, service, username):
+        from keyring.errors import PasswordDeleteError
+
+        raise PasswordDeleteError("failed to delete password")
+
+
+def _break_backend(monkeypatch):
+    monkeypatch.setattr(auth, "_backend", lambda: _BrokenKeyring())
+
+
+def test_store_read_delete_round_trip(fake_keychain):
+    assert auth.stored_key() is None
+
+    auth.store_key(SECRET)
+
+    assert fake_keychain[ENTRY] == SECRET
+    assert auth.stored_key() == SECRET
+
+    auth.delete_key()
+
+    assert ENTRY not in fake_keychain
+    assert auth.stored_key() is None
+
+
+def test_stored_key_is_none_when_the_backend_raises(monkeypatch):
+    _break_backend(monkeypatch)
+
+    assert auth.stored_key() is None
+
+
+def test_store_key_reports_a_broken_backend(monkeypatch):
+    _break_backend(monkeypatch)
+
+    with pytest.raises(AuthError, match="Could not write"):
+        auth.store_key(SECRET)
+
+
+def test_delete_on_a_missing_entry_is_silent(fake_keychain):
+    auth.delete_key()  # must not raise
+
+    assert fake_keychain == {}
+
+
+def test_delete_key_reports_a_broken_backend(monkeypatch):
+    _break_backend(monkeypatch)
+
+    with pytest.raises(AuthError, match="Could not delete"):
+        auth.delete_key()
+
+
+def test_a_denied_delete_is_not_reported_as_success(fake_keychain):
+    # macOS raises PasswordDeleteError for a denial too, entry intact
+    fake_keychain[ENTRY] = SECRET
+    fake_keychain.deny_delete = True
+
+    with pytest.raises(AuthError, match="STILL stored"):
+        auth.delete_key()
+
+    assert fake_keychain[ENTRY] == SECRET
+
+
+def test_delete_will_not_claim_success_it_cannot_verify(monkeypatch, fake_keychain):
+    fake_keychain[ENTRY] = SECRET
+    keyring = _FakeReadFailure(fake_keychain)
+    monkeypatch.setattr(auth, "_backend", lambda: keyring)
+
+    with pytest.raises(AuthError, match="Could not confirm"):
+        auth.delete_key()
+
+
+@pytest.mark.parametrize(
+    "failure",
+    [ModuleNotFoundError("No module named 'keyrings.nope'"), AttributeError("no such backend")],
+    ids=["module-not-found", "attribute-error"],
+)
+def test_stored_key_survives_a_backend_selection_failure(monkeypatch, failure):
+    # PYTHON_KEYRING_BACKEND naming an uninstalled module fails at import
+    # time, so it never surfaces as a KeyringError.
+    class _Unselectable:
+        def get_password(self, service, username):
+            raise failure
+
+    monkeypatch.setattr(auth, "_backend", lambda: _Unselectable())
+
+    assert auth.stored_key() is None
+
+
+def test_probe_keychain_tells_absent_apart_from_unreadable(monkeypatch, fake_keychain):
+    assert auth.probe_keychain() == ("ok", None)
+
+    fake_keychain[ENTRY] = SECRET
+    assert auth.probe_keychain() == ("ok", SECRET)
+
+    _break_backend(monkeypatch)
+    status, reason = auth.probe_keychain()
+    assert status == "error"
+    assert "no recommended backend" in reason
+
+
+def test_key_source_reports_the_flag(monkeypatch):
+    monkeypatch.setenv("ELEVENLABS_API_KEY", "env-key")
+
+    assert auth.key_source("flag-key") == "flag"
+
+
+def test_key_source_reports_the_environment(monkeypatch, fake_keychain):
+    monkeypatch.setenv("ELEVENLABS_API_KEY", "env-key")
+    fake_keychain[ENTRY] = SECRET
+
+    assert auth.key_source(None) == "environment"
+
+
+def test_key_source_reports_the_dotenv_file(monkeypatch, tmp_path, no_env_key):
+    monkeypatch.chdir(tmp_path)
+    (tmp_path / ".env").write_text("ELEVENLABS_API_KEY=from-cwd-file\n", encoding="utf-8")
+    # setenv before delenv so monkeypatch restores the var whether or not it
+    # was set beforehand — the real loader writes straight to os.environ.
+    monkeypatch.setenv("ELEVENLABS_API_KEY", "placeholder")
+    monkeypatch.delenv("ELEVENLABS_API_KEY")
+    monkeypatch.setattr("vocalize.config._load_dotenv_if_present", real_load_dotenv)
+
+    assert auth.key_source(None) == ".env file"
+
+
+def test_key_source_reports_the_keychain(fake_keychain, no_env_key):
+    fake_keychain[ENTRY] = SECRET
+
+    assert auth.key_source(None) == "keychain"
+
+
+def test_key_source_reports_not_found(no_env_key):
+    assert auth.key_source(None) == "not found"
+
+
+def test_masked_never_shows_more_than_four_characters():
+    assert auth.masked(SECRET) == "sk_s…"
+    assert SECRET not in auth.masked(SECRET)
+
+
+def test_login_validates_before_storing(monkeypatch, fake_keychain):
+    seen = _fake_tts(monkeypatch)
+
+    assert auth.login(SECRET) == f"Stored the API key in {auth.WHERE}."
+    assert seen == [SECRET]
+    assert fake_keychain[ENTRY] == SECRET
+
+
+def test_login_rejects_a_key_with_control_characters(monkeypatch, fake_keychain):
+    reached = []
+    monkeypatch.setattr("vocalize.auth.validate_key", reached.append)
+    utf16_bytes = "s\x00k\x00_\x00a\x00b\x00"
+
+    with pytest.raises(AuthError, match="encoding"):
+        auth.login(utf16_bytes)
+
+    assert reached == []  # never got near a request
+    assert fake_keychain == {}
+
+
+def test_cli_login_never_echoes_a_malformed_key(fake_keychain):
+    utf16_bytes = "s\x00k\x00_\x00secretpart\x00"
+
+    result = CliRunner().invoke(main, ["auth", "login", "--stdin"], input=f"{utf16_bytes}\n")
+
+    assert result.exit_code == 1
+    assert "control characters" in result.output
+    assert "secretpart" not in result.output
+    assert fake_keychain == {}
+
+
+def test_login_scrubs_the_key_out_of_a_wrapped_api_error(monkeypatch, fake_keychain):
+    # What h11 does: the rejected header value is quoted back in full
+    _fake_tts(monkeypatch, failure=f"Illegal header value b'xi-api-key: {SECRET}'")
+
+    result = CliRunner().invoke(main, ["auth", "login"], input=f"{SECRET}\n")
+
+    assert result.exit_code == 1
+    assert SECRET not in result.output
+    assert "[key]" in result.output
+    assert fake_keychain == {}
+
+
+def test_cli_login_stores_a_prompted_key(monkeypatch, fake_keychain):
+    _fake_tts(monkeypatch)
+
+    result = CliRunner().invoke(main, ["auth", "login"], input=f"{SECRET}\n")
+
+    assert result.exit_code == 0, result.output
+    assert fake_keychain[ENTRY] == SECRET
+    assert "keychain" in result.output
+    assert SECRET not in result.output
+
+
+def test_cli_login_stores_nothing_when_the_key_is_rejected(monkeypatch, fake_keychain):
+    _fake_tts(monkeypatch, failure="401 unauthorized")
+
+    result = CliRunner().invoke(main, ["auth", "login"], input="bad-key\n")
+
+    assert result.exit_code == 1
+    assert "401 unauthorized" in result.output
+    assert fake_keychain == {}
+
+
+def test_cli_login_reads_a_piped_key(monkeypatch, fake_keychain):
+    seen = _fake_tts(monkeypatch)
+
+    result = CliRunner().invoke(main, ["auth", "login", "--stdin"], input=f"{SECRET}\n")
+
+    assert result.exit_code == 0, result.output
+    assert seen == [SECRET]  # the trailing newline is not part of the key
+    assert fake_keychain[ENTRY] == SECRET
+
+
+def test_cli_login_refuses_an_empty_key(fake_keychain):
+    result = CliRunner().invoke(main, ["auth", "login", "--stdin"], input="\n")
+
+    assert result.exit_code == 1
+    assert "No API key given" in result.output
+    assert fake_keychain == {}
+
+
+def test_cli_status_masks_the_key(fake_keychain, no_env_key):
+    fake_keychain[ENTRY] = SECRET
+
+    result = CliRunner().invoke(main, ["auth", "status"])
+
+    assert result.exit_code == 0, result.output
+    assert "API key source: keychain" in result.output
+    assert "Key: sk_s…" in result.output
+    assert SECRET not in result.output
+
+
+def test_cli_status_is_informational_when_there_is_no_key(no_env_key):
+    result = CliRunner().invoke(main, ["auth", "status"])
+
+    assert result.exit_code == 0, result.output
+    assert "API key source: not found" in result.output
+    assert "vocalize auth login" in result.output
+
+
+def test_cli_status_admits_the_keychain_is_unreadable(monkeypatch, no_env_key):
+    _break_backend(monkeypatch)
+
+    result = CliRunner().invoke(main, ["auth", "status"])
+
+    assert result.exit_code == 0, result.output
+    assert "keychain unavailable (no recommended backend)" in result.output
+    assert "Unlock your keychain" in result.output
+    assert "not found" not in result.output
+
+
+def test_cli_logout_removes_the_stored_key(fake_keychain):
+    fake_keychain[ENTRY] = SECRET
+
+    result = CliRunner().invoke(main, ["auth", "logout"])
+
+    assert result.exit_code == 0, result.output
+    assert fake_keychain == {}
+    assert "Removed" in result.output
+
+
+def test_cli_logout_does_not_claim_a_denied_removal(fake_keychain):
+    fake_keychain[ENTRY] = SECRET
+    fake_keychain.deny_delete = True
+
+    result = CliRunner().invoke(main, ["auth", "logout"])
+
+    assert result.exit_code == 1
+    assert "Removed" not in result.output
+    assert "STILL stored" in result.output
+    assert "rotate the key" in result.output
+    assert fake_keychain[ENTRY] == SECRET