deepctl 0.2.26__tar.gz → 0.3.1__tar.gz

{deepctl-0.2.26/src/deepctl.egg-info → deepctl-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deepctl
-Version: 0.2.26
+Version: 0.3.1
 Summary: Official Deepgram CLI for speech recognition and audio intelligence
 Author-email: Deepgram <devrel@deepgram.com>
 Maintainer-email: Deepgram <devrel@deepgram.com>
@@ -26,36 +26,36 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: click>=8.0.0
-Requires-Dist: deepgram-sdk>=7.5.0
-Requires-Dist: deepctl-core>=0.1.10
-Requires-Dist: deepctl-cmd-login>=0.1.10
-Requires-Dist: deepctl-cmd-projects>=0.1.10
-Requires-Dist: deepctl-cmd-transcribe>=0.1.10
-Requires-Dist: deepctl-cmd-usage>=0.1.10
-Requires-Dist: deepctl-cmd-mcp>=0.1.10
-Requires-Dist: deepctl-cmd-api>=0.0.1
-Requires-Dist: deepctl-cmd-debug>=0.1.10
-Requires-Dist: deepctl-cmd-debug-browser>=0.1.10
-Requires-Dist: deepctl-cmd-debug-network>=0.1.10
-Requires-Dist: deepctl-cmd-debug-audio>=0.1.10
-Requires-Dist: deepctl-cmd-debug-probe>=0.0.1
-Requires-Dist: deepctl-cmd-debug-toolkit>=0.0.1
-Requires-Dist: deepctl-cmd-ffprobe>=0.0.1
-Requires-Dist: deepctl-cmd-update>=0.1.10
-Requires-Dist: deepctl-cmd-plugin>=0.1.10
-Requires-Dist: deepctl-cmd-skills>=0.0.1
-Requires-Dist: deepctl-cmd-init>=0.0.1
-Requires-Dist: deepctl-cmd-models>=0.0.1
-Requires-Dist: deepctl-cmd-speak>=0.0.1
-Requires-Dist: deepctl-cmd-keys>=0.0.1
-Requires-Dist: deepctl-cmd-read>=0.0.1
-Requires-Dist: deepctl-cmd-listen>=0.0.1
-Requires-Dist: deepctl-cmd-requests>=0.0.1
-Requires-Dist: deepctl-cmd-billing>=0.0.1
-Requires-Dist: deepctl-cmd-members>=0.0.1
-Requires-Dist: deepctl-cmd-completion>=0.0.1
-Requires-Dist: deepctl-shared-utils>=0.1.10
-Requires-Dist: deepctl-telemetry>=0.0.1
+Requires-Dist: deepgram-sdk<8,>=7.7.0
+Requires-Dist: deepctl-core>=0.2.17
+Requires-Dist: deepctl-cmd-login>=0.1.18
+Requires-Dist: deepctl-cmd-projects>=0.2.0
+Requires-Dist: deepctl-cmd-transcribe>=0.1.12
+Requires-Dist: deepctl-cmd-usage>=0.2.0
+Requires-Dist: deepctl-cmd-mcp>=0.1.15
+Requires-Dist: deepctl-cmd-api>=0.0.2
+Requires-Dist: deepctl-cmd-debug>=0.1.12
+Requires-Dist: deepctl-cmd-debug-browser>=0.1.12
+Requires-Dist: deepctl-cmd-debug-network>=0.1.12
+Requires-Dist: deepctl-cmd-debug-audio>=0.1.13
+Requires-Dist: deepctl-cmd-debug-probe>=0.0.2
+Requires-Dist: deepctl-cmd-debug-toolkit>=0.1.0
+Requires-Dist: deepctl-cmd-ffprobe>=0.0.2
+Requires-Dist: deepctl-cmd-update>=0.2.7
+Requires-Dist: deepctl-cmd-plugin>=0.1.13
+Requires-Dist: deepctl-cmd-skills>=0.0.8
+Requires-Dist: deepctl-cmd-init>=0.0.4
+Requires-Dist: deepctl-cmd-models>=0.1.1
+Requires-Dist: deepctl-cmd-speak>=0.0.4
+Requires-Dist: deepctl-cmd-keys>=0.1.0
+Requires-Dist: deepctl-cmd-read>=0.1.0
+Requires-Dist: deepctl-cmd-listen>=0.0.14
+Requires-Dist: deepctl-cmd-requests>=0.1.0
+Requires-Dist: deepctl-cmd-billing>=0.1.0
+Requires-Dist: deepctl-cmd-members>=0.1.0
+Requires-Dist: deepctl-cmd-completion>=0.0.3
+Requires-Dist: deepctl-shared-utils>=0.1.12
+Requires-Dist: deepctl-telemetry>=0.0.6
 Requires-Dist: pydantic>=2.0.0
 Requires-Dist: rich>=13.0.0
 Requires-Dist: httpx>=0.24.0
@@ -70,13 +70,15 @@ Requires-Dist: pytest>=7.0.0; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
 Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
 Requires-Dist: pytest-mock>=3.10.0; extra == "dev"
+Requires-Dist: pytest-timeout<3,>=2.3.1; extra == "dev"
 Requires-Dist: responses>=0.23.0; extra == "dev"
 Requires-Dist: ruff>=0.8.0; extra == "dev"
 Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: packaging>=23.0; extra == "dev"
 Requires-Dist: types-PyYAML>=6.0.0; extra == "dev"
 Requires-Dist: types-requests>=2.31.0; extra == "dev"
 Requires-Dist: pre-commit>=3.0.0; extra == "dev"
-Requires-Dist: twine>=4.0.0; extra == "dev"
+Requires-Dist: twine>=7.0.0; extra == "dev"
 Requires-Dist: build>=0.10.0; extra == "dev"
 Dynamic: license-file
 
@@ -115,8 +117,8 @@ intelligence, and project management directly into your terminal. Aliases:
 **macOS / Linux (Homebrew):**
 
 ```bash
-brew tap deepgram/tap
-brew install deepgram
+# Install and trust only the Deepgram formula.
+brew install deepgram/tap/deepgram
 ```
 
 Homebrew brings in `ffmpeg` and `portaudio` automatically — `dg listen --mic`, `dg debug probe`, and raw audio piping all work without further setup. To upgrade later: `brew upgrade deepgram`.
@@ -157,8 +159,8 @@ dg login
 # Transcribe an audio file
 dg listen recording.wav
 
-# Text-to-speech
-dg speak "Hello from Deepgram" -o hello.mp3
+# Text-to-speech (Flux TTS by default)
+dg speak "Hello from Deepgram" -o hello.wav
 
 # Live microphone transcription
 dg listen --mic
@@ -183,6 +185,10 @@ dg -o json listen standup.mp3 \
 # Live microphone with interim (partial) results
 dg listen --mic --model nova-3 --interim
 
+# Redact sensitive numbers and spell numbers as digits (files or live)
+# Flux STT (v2) accepts --redact numbers|aggressive_numbers; v1 also pci, ssn, …
+dg listen call.wav --redact numbers --numerals
+
 # Raw audio stream from ffmpeg
 ffmpeg -i video.mp4 -f s16le -ar 16000 -ac 1 - \
   | dg listen --encoding linear16
@@ -214,8 +220,9 @@ dg read earnings.txt --sentiment --summarize --topics
 ### Text-to-speech
 
 ```bash
-# Stream directly to a player
-dg speak "Hello from Deepgram" | ffplay -nodisp -autoexit -
+# Stream directly to a player (Flux TTS streams a WAV; -loglevel error hides
+# ffmpeg's cosmetic end-of-stream notice)
+dg speak "Hello from Deepgram" | ffplay -loglevel error -nodisp -autoexit -
 ```
 
 ### Account & project management
@@ -255,22 +262,30 @@ cat audio.raw | dg listen --encoding linear16 --sample-rate 16000
 
 Convert text to natural speech. Supports file output and piping.
 
-`aura-*` models use the Speak v1 batch REST API. `flux-*` (Flux TTS) models use
-the Speak v2 WebSocket API and stream by default; their raw `linear16` output is
-wrapped in a WAV container so it is directly playable.
+By default `dg speak` uses Flux TTS (`flux-alexis-en`) — the Speak v2 WebSocket
+API, which streams and emits raw audio; its `linear16` output is wrapped in a WAV
+container so it is directly playable. Pass an `aura-*` model to use the Speak v1
+batch REST API instead, which supports containerized formats like MP3.
 
 ```bash
-# Aura (v1, batch REST)
-dg speak "Welcome to Deepgram" -o welcome.mp3
-dg speak --file script.txt -o output.mp3 -m aura-2-luna-en
-echo "Hello" | dg speak -o greeting.mp3
-dg speak "Stream me" | ffplay -nodisp -            # pipe to audio player
-
-# Flux TTS (v2, WebSocket streaming)
-dg speak "Hello from Flux" -m flux-alexis-en -o hello.wav
+# Flux TTS (v2, WebSocket streaming) — the default
+dg speak "Hello from Flux" -o hello.wav
 # Piped audio is a streaming WAV; -loglevel error hides ffmpeg's cosmetic
 # end-of-stream notice (the audio is complete).
-dg speak "Hello from Flux" -m flux-alexis-en | ffplay -loglevel error -nodisp -autoexit -
+dg speak "Hello from Flux" | ffplay -loglevel error -nodisp -autoexit -
+
+# Flux TTS streaming controls (flux-* only): --speed 0.85–1.15 (0.05 steps).
+# --expressivity -2..2 is beta; its default 0 is nominal delivery.
+dg speak "A little slower" --speed 0.9 --expressivity 1 -o slow.wav
+
+# Aura (v1, batch REST) — opt in with -m aura-*; needed for MP3 output
+dg speak "Welcome to Deepgram" -o welcome.mp3 -m aura-2-asteria-en
+dg speak --file script.txt -o output.mp3 -m aura-2-luna-en
+echo "Hello" | dg speak -o greeting.mp3 -m aura-2-asteria-en
+
+# Aura-2 also has Spanish voices (e.g. aura-2-selena-es); run `dg models`
+# for the full, current list.
+dg speak "Hola, bienvenido a Deepgram" -o hola.mp3 -m aura-2-selena-es
 ```
 
 ### Text Intelligence
@@ -374,7 +389,7 @@ export DEEPGRAM_PROJECT_ID="your-project-id"
 
 # Non-interactive usage
 dg listen recording.wav
-dg speak "Deploy complete" -o notification.mp3
+dg speak "Deploy complete" -o notification.mp3 -m aura-2-asteria-en
 dg keys --create --comment "ci-key" --scopes member
 dg keys --delete KEY_ID --yes
 dg read --file report.txt --summarize
@@ -388,6 +403,24 @@ dg usage --last-week -o yaml
 When running in a non-TTY environment (pipes, CI, or AI coding tools), the CLI
 automatically switches to structured JSON output with plain-text status messages.
 
+### Exit codes
+
+Since 0.3.0, `dg` exits non-zero when a command fails — branch on the exit
+code, not on parsing output:
+
+| Code | Meaning |
+| --- | --- |
+| `0` | Success |
+| `1` | Error — a failed command, a crash, or a usage error (bad flag, unknown command) |
+| `2` | Cancelled by the user (Ctrl-C, or declining a confirmation prompt) |
+
+Note that `dg` reports `2` for an interrupt rather than the shell's
+conventional `130`, so the code is the same whether the cancellation came from
+Ctrl-C or from declining a prompt.
+
+If a CI step relied on `dg` always exiting `0` (every command did, before
+0.3.0), it will now fail where it previously passed silently.
+
 ### Forcing non-interactive mode
 
 Three explicit ways to skip every prompt and run with defaults — useful from a
@@ -431,7 +464,10 @@ dg profiles --list                       # List profiles
 dg profiles --switch staging             # Switch profile
 ```
 
-Output format on any command: `--output json|yaml|table|csv`
+For structured output, use `--output json|yaml|table|csv` after leaf commands
+that do not define their own output option, or before any command as a global
+flag: `dg --output json <command>`. `dg speak --output FILE` writes audio to
+`FILE`, so use `dg --output json speak ...` for Speak's structured output.
 
 ## Telemetry
 

{deepctl-0.2.26 → deepctl-0.3.1}/README.md

@@ -33,8 +33,8 @@ intelligence, and project management directly into your terminal. Aliases:
 **macOS / Linux (Homebrew):**
 
 ```bash
-brew tap deepgram/tap
-brew install deepgram
+# Install and trust only the Deepgram formula.
+brew install deepgram/tap/deepgram
 ```
 
 Homebrew brings in `ffmpeg` and `portaudio` automatically — `dg listen --mic`, `dg debug probe`, and raw audio piping all work without further setup. To upgrade later: `brew upgrade deepgram`.
@@ -75,8 +75,8 @@ dg login
 # Transcribe an audio file
 dg listen recording.wav
 
-# Text-to-speech
-dg speak "Hello from Deepgram" -o hello.mp3
+# Text-to-speech (Flux TTS by default)
+dg speak "Hello from Deepgram" -o hello.wav
 
 # Live microphone transcription
 dg listen --mic
@@ -101,6 +101,10 @@ dg -o json listen standup.mp3 \
 # Live microphone with interim (partial) results
 dg listen --mic --model nova-3 --interim
 
+# Redact sensitive numbers and spell numbers as digits (files or live)
+# Flux STT (v2) accepts --redact numbers|aggressive_numbers; v1 also pci, ssn, …
+dg listen call.wav --redact numbers --numerals
+
 # Raw audio stream from ffmpeg
 ffmpeg -i video.mp4 -f s16le -ar 16000 -ac 1 - \
   | dg listen --encoding linear16
@@ -132,8 +136,9 @@ dg read earnings.txt --sentiment --summarize --topics
 ### Text-to-speech
 
 ```bash
-# Stream directly to a player
-dg speak "Hello from Deepgram" | ffplay -nodisp -autoexit -
+# Stream directly to a player (Flux TTS streams a WAV; -loglevel error hides
+# ffmpeg's cosmetic end-of-stream notice)
+dg speak "Hello from Deepgram" | ffplay -loglevel error -nodisp -autoexit -
 ```
 
 ### Account & project management
@@ -173,22 +178,30 @@ cat audio.raw | dg listen --encoding linear16 --sample-rate 16000
 
 Convert text to natural speech. Supports file output and piping.
 
-`aura-*` models use the Speak v1 batch REST API. `flux-*` (Flux TTS) models use
-the Speak v2 WebSocket API and stream by default; their raw `linear16` output is
-wrapped in a WAV container so it is directly playable.
+By default `dg speak` uses Flux TTS (`flux-alexis-en`) — the Speak v2 WebSocket
+API, which streams and emits raw audio; its `linear16` output is wrapped in a WAV
+container so it is directly playable. Pass an `aura-*` model to use the Speak v1
+batch REST API instead, which supports containerized formats like MP3.
 
 ```bash
-# Aura (v1, batch REST)
-dg speak "Welcome to Deepgram" -o welcome.mp3
-dg speak --file script.txt -o output.mp3 -m aura-2-luna-en
-echo "Hello" | dg speak -o greeting.mp3
-dg speak "Stream me" | ffplay -nodisp -            # pipe to audio player
-
-# Flux TTS (v2, WebSocket streaming)
-dg speak "Hello from Flux" -m flux-alexis-en -o hello.wav
+# Flux TTS (v2, WebSocket streaming) — the default
+dg speak "Hello from Flux" -o hello.wav
 # Piped audio is a streaming WAV; -loglevel error hides ffmpeg's cosmetic
 # end-of-stream notice (the audio is complete).
-dg speak "Hello from Flux" -m flux-alexis-en | ffplay -loglevel error -nodisp -autoexit -
+dg speak "Hello from Flux" | ffplay -loglevel error -nodisp -autoexit -
+
+# Flux TTS streaming controls (flux-* only): --speed 0.85–1.15 (0.05 steps).
+# --expressivity -2..2 is beta; its default 0 is nominal delivery.
+dg speak "A little slower" --speed 0.9 --expressivity 1 -o slow.wav
+
+# Aura (v1, batch REST) — opt in with -m aura-*; needed for MP3 output
+dg speak "Welcome to Deepgram" -o welcome.mp3 -m aura-2-asteria-en
+dg speak --file script.txt -o output.mp3 -m aura-2-luna-en
+echo "Hello" | dg speak -o greeting.mp3 -m aura-2-asteria-en
+
+# Aura-2 also has Spanish voices (e.g. aura-2-selena-es); run `dg models`
+# for the full, current list.
+dg speak "Hola, bienvenido a Deepgram" -o hola.mp3 -m aura-2-selena-es
 ```
 
 ### Text Intelligence
@@ -292,7 +305,7 @@ export DEEPGRAM_PROJECT_ID="your-project-id"
 
 # Non-interactive usage
 dg listen recording.wav
-dg speak "Deploy complete" -o notification.mp3
+dg speak "Deploy complete" -o notification.mp3 -m aura-2-asteria-en
 dg keys --create --comment "ci-key" --scopes member
 dg keys --delete KEY_ID --yes
 dg read --file report.txt --summarize
@@ -306,6 +319,24 @@ dg usage --last-week -o yaml
 When running in a non-TTY environment (pipes, CI, or AI coding tools), the CLI
 automatically switches to structured JSON output with plain-text status messages.
 
+### Exit codes
+
+Since 0.3.0, `dg` exits non-zero when a command fails — branch on the exit
+code, not on parsing output:
+
+| Code | Meaning |
+| --- | --- |
+| `0` | Success |
+| `1` | Error — a failed command, a crash, or a usage error (bad flag, unknown command) |
+| `2` | Cancelled by the user (Ctrl-C, or declining a confirmation prompt) |
+
+Note that `dg` reports `2` for an interrupt rather than the shell's
+conventional `130`, so the code is the same whether the cancellation came from
+Ctrl-C or from declining a prompt.
+
+If a CI step relied on `dg` always exiting `0` (every command did, before
+0.3.0), it will now fail where it previously passed silently.
+
 ### Forcing non-interactive mode
 
 Three explicit ways to skip every prompt and run with defaults — useful from a
@@ -349,7 +380,10 @@ dg profiles --list                       # List profiles
 dg profiles --switch staging             # Switch profile
 ```
 
-Output format on any command: `--output json|yaml|table|csv`
+For structured output, use `--output json|yaml|table|csv` after leaf commands
+that do not define their own output option, or before any command as a global
+flag: `dg --output json <command>`. `dg speak --output FILE` writes audio to
+`FILE`, so use `dg --output json speak ...` for Speak's structured output.
 
 ## Telemetry
 

{deepctl-0.2.26 → deepctl-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "deepctl"
-version = "0.2.26" # x-release-please-version
+version = "0.3.1" # x-release-please-version
 description = "Official Deepgram CLI for speech recognition and audio intelligence"
 readme = "README.md"
 license = "MIT"
@@ -34,36 +34,36 @@ keywords = [
 requires-python = ">=3.10"
 dependencies = [
     "click>=8.0.0",
-    "deepgram-sdk>=7.5.0",
-    "deepctl-core>=0.1.10",
-    "deepctl-cmd-login>=0.1.10",
-    "deepctl-cmd-projects>=0.1.10",
-    "deepctl-cmd-transcribe>=0.1.10",
-    "deepctl-cmd-usage>=0.1.10",
-    "deepctl-cmd-mcp>=0.1.10",
-    "deepctl-cmd-api>=0.0.1",
-    "deepctl-cmd-debug>=0.1.10",
-    "deepctl-cmd-debug-browser>=0.1.10",
-    "deepctl-cmd-debug-network>=0.1.10",
-    "deepctl-cmd-debug-audio>=0.1.10",
-    "deepctl-cmd-debug-probe>=0.0.1",
-    "deepctl-cmd-debug-toolkit>=0.0.1",
-    "deepctl-cmd-ffprobe>=0.0.1",
-    "deepctl-cmd-update>=0.1.10",
-    "deepctl-cmd-plugin>=0.1.10",
-    "deepctl-cmd-skills>=0.0.1",
-    "deepctl-cmd-init>=0.0.1",
-    "deepctl-cmd-models>=0.0.1",
-    "deepctl-cmd-speak>=0.0.1",
-    "deepctl-cmd-keys>=0.0.1",
-    "deepctl-cmd-read>=0.0.1",
-    "deepctl-cmd-listen>=0.0.1",
-    "deepctl-cmd-requests>=0.0.1",
-    "deepctl-cmd-billing>=0.0.1",
-    "deepctl-cmd-members>=0.0.1",
-    "deepctl-cmd-completion>=0.0.1",
-    "deepctl-shared-utils>=0.1.10",
-    "deepctl-telemetry>=0.0.1",
+    "deepgram-sdk>=7.7.0,<8",
+    "deepctl-core>=0.2.17",
+    "deepctl-cmd-login>=0.1.18",
+    "deepctl-cmd-projects>=0.2.0",
+    "deepctl-cmd-transcribe>=0.1.12",
+    "deepctl-cmd-usage>=0.2.0",
+    "deepctl-cmd-mcp>=0.1.15",
+    "deepctl-cmd-api>=0.0.2",
+    "deepctl-cmd-debug>=0.1.12",
+    "deepctl-cmd-debug-browser>=0.1.12",
+    "deepctl-cmd-debug-network>=0.1.12",
+    "deepctl-cmd-debug-audio>=0.1.13",
+    "deepctl-cmd-debug-probe>=0.0.2",
+    "deepctl-cmd-debug-toolkit>=0.1.0",
+    "deepctl-cmd-ffprobe>=0.0.2",
+    "deepctl-cmd-update>=0.2.7",
+    "deepctl-cmd-plugin>=0.1.13",
+    "deepctl-cmd-skills>=0.0.8",
+    "deepctl-cmd-init>=0.0.4",
+    "deepctl-cmd-models>=0.1.1",
+    "deepctl-cmd-speak>=0.0.4",
+    "deepctl-cmd-keys>=0.1.0",
+    "deepctl-cmd-read>=0.1.0",
+    "deepctl-cmd-listen>=0.0.14",
+    "deepctl-cmd-requests>=0.1.0",
+    "deepctl-cmd-billing>=0.1.0",
+    "deepctl-cmd-members>=0.1.0",
+    "deepctl-cmd-completion>=0.0.3",
+    "deepctl-shared-utils>=0.1.12",
+    "deepctl-telemetry>=0.0.6",
     "pydantic>=2.0.0",
     "rich>=13.0.0",
     "httpx>=0.24.0",
@@ -82,17 +82,21 @@ dev = [
     "pytest-asyncio>=0.21.0",
     "pytest-cov>=4.0.0",
     "pytest-mock>=3.10.0",
+    "pytest-timeout>=2.3.1,<3",
     "responses>=0.23.0",
     # Code Quality
     "ruff>=0.8.0",
     "mypy>=1.0.0",
+    "packaging>=23.0",
     # Type Stubs
     "types-PyYAML>=6.0.0",
     "types-requests>=2.31.0",
     # Development Tools
     "pre-commit>=3.0.0",
     # Publishing
-    "twine>=4.0.0",
+    # twine <7 rejects Metadata-Version 2.5 (emitted by hatchling), which
+    # silently broke the 0.2.27 publish. Keep local verify == what publishes.
+    "twine>=7.0.0",
     "build>=0.10.0",
 ]
 
@@ -125,7 +129,13 @@ include = ["deepctl*"]
 [tool.mypy]
 python_version = "3.10"
 strict = true
-files = "src/,packages/*/src"
+files = "src/,packages/*/src,scripts/"
+
+[[tool.mypy.overrides]]
+module = ["tomli"]
+# The pre-3.11 fallback for tomllib in scripts/. It is not installed, and
+# mypy checks that branch because python_version is pinned to 3.10.
+ignore_missing_imports = true
 
 [[tool.mypy.overrides]]
 module = "deepctl_cmd_mcp.*"
@@ -229,9 +239,14 @@ members = ["packages/*"]
 [dependency-groups]
 testing = [
     "pytest>=7.0.0",
+    # scripts/check_dependency_floors.py reads pyproject files; on 3.10 it
+    # falls back to tomli, and tests/unit/test_dependency_floors.py drives
+    # the real script on every version in the CI matrix.
+    "tomli>=2.0; python_version < '3.11'",
     "pytest-asyncio>=0.21.0",
     "pytest-cov>=4.0.0",
     "pytest-mock>=3.10.0",
+    "pytest-timeout>=2.3.1,<3",
     "responses>=0.23.0",
     "deepctl-plugin-example",
 ]
@@ -240,13 +255,18 @@ dev = [
     # Code Quality
     "ruff>=0.8.0",
     "mypy>=1.0.0",
+    # PEP 440 comparisons in scripts/check_dependency_floors.py. Declared
+    # rather than leaned on as a transitive of build/twine.
+    "packaging>=23.0",
     # Type Stubs
     "types-pyyaml>=6.0.12.20250516",
     "types-requests>=2.32.4.20250611",
     # Development Tools
     "pre-commit>=3.0.0",
     # Publishing
-    "twine>=4.0.0",
+    # twine <7 rejects Metadata-Version 2.5 (emitted by hatchling), which
+    # silently broke the 0.2.27 publish. Keep local verify == what publishes.
+    "twine>=7.0.0",
     "build>=0.10.0",
 ]
 

{deepctl-0.2.26 → deepctl-0.3.1}/src/deepctl/__init__.py

@@ -1,7 +1,7 @@
 """deepctl - Official command-line interface for Deepgram's speech
 recognition API."""
 
-__version__ = "0.2.26"  # x-release-please-version
+__version__ = "0.3.1"  # x-release-please-version
 __author__ = "Deepgram"
 __email__ = "devrel@deepgram.com"
 __license__ = "MIT"

{deepctl-0.2.26 → deepctl-0.3.1}/src/deepctl/main.py

@@ -19,12 +19,18 @@ from deepctl_core import (
     print_timing_summary,
     setup_output,
 )
-from rich.console import Console
+from deepctl_core.output import stderr_console
 from rich.traceback import install
 
 # Install rich traceback for better error messages
 install(show_locals=True)
-console = Console()
+
+# Diagnostics go to stderr so stdout carries only the requested payload -- a
+# crash or usage error must not corrupt `dg -o json ...` for a script piping
+# stdout into jq. Same console the command layer uses via print_error(), so
+# root-level and command-level diagnostics format identically (including the
+# no-color handling for agentic/CI callers).
+console = stderr_console
 
 
 def _record_install_method_cb(
@@ -281,6 +287,52 @@ def _telemetry_transaction() -> Iterator[None]:
         yield
 
 
+def _global_option_hint(message: str) -> str | None:
+    """Build a placement hint when a 'No such option' names a global option.
+
+    Global options belong before the subcommand (``dg -o json models``).
+    When one is placed after the subcommand instead (``dg models --profile
+    staging``), Click reports "No such option" with no explanation, which
+    reads as if the option does not exist at all. This looks the failing
+    option up on the root group and, when it is a global one, returns a
+    hint showing the working placement.
+    """
+    import re
+
+    match = re.search(r"[Nn]o such option:?\s*'?(--?[A-Za-z][\w-]*)'?", message)
+    if not match:
+        return None
+    token = match.group(1)
+
+    for param in cli.params:
+        opts = list(getattr(param, "opts", [])) + list(
+            getattr(param, "secondary_opts", [])
+        )
+        if token in opts:
+            takes_value = not getattr(param, "is_flag", False)
+            usage = f"{token} <value>" if takes_value else token
+            return (
+                f"[yellow]Hint: '{token}' is a global option and must come "
+                f"before the subcommand, for example: "
+                f"dg {usage} <command> ...[/yellow]"
+            )
+    return None
+
+
+def _safe_console_print(message: str) -> None:
+    """Print a diagnostic to stderr, tolerating a closed/broken stream.
+
+    When `dg` runs as an MCP server, the host can close stdio before the
+    process finishes. A write to the closed stream raises ``BrokenPipeError``
+    (or rich's ``ValueError: I/O operation on closed file``); there is nowhere
+    left to report the message, so swallow it rather than crash on exit.
+    """
+    try:
+        console.print(message)
+    except (BrokenPipeError, OSError, ValueError):
+        pass
+
+
 def main() -> None:
     """Main entry point for the CLI."""
     try:
@@ -347,12 +399,18 @@ def main() -> None:
                 # Preprocess arguments to handle hyphenated commands
                 processed_args = preprocess_hyphenated_commands(args)
 
+            exit_code = 0
             with TimingContext("cli_execution"), _telemetry_transaction():
                 try:
                     cli(args=processed_args, standalone_mode=False)
-                except SystemExit:
-                    # Click calls sys.exit() even in non-standalone mode
-                    pass
+                except SystemExit as exc:
+                    # Click calls sys.exit() even in non-standalone mode, so we
+                    # cannot let this propagate — the notifications and timing
+                    # summary below still need to run. But swallowing the code
+                    # outright made every failure exit 0, which is what broke
+                    # `if dg -o json keys; then ...` in scripts and CI. Carry it
+                    # and re-raise at the end instead.
+                    exit_code = exc.code if isinstance(exc.code, int) else 0
 
         # Print update notifications if available (before timing summary)
         if print_pending_notification is not None:
@@ -366,12 +424,29 @@ def main() -> None:
         if timing_requested:
             print_timing_summary(detailed_timing)
 
-    except KeyboardInterrupt:
-        console.print("\n[yellow]Operation cancelled by user[/yellow]")
+        if exit_code:
+            sys.exit(exit_code)
+
+    except (KeyboardInterrupt, click.exceptions.Abort):
+        # Click wraps a Ctrl-C/Ctrl-D raised inside cli() in Abort when
+        # standalone_mode=False, so a mid-command interrupt arrives here as
+        # Abort, not KeyboardInterrupt. Both are user cancellation: exit 2.
+        _safe_console_print("\n[yellow]Operation cancelled by user[/yellow]")
         sys.exit(2)
+    except click.UsageError as e:
+        # Keep the published exit-code contract (1 = error), but explain the
+        # one failure mode that reads as a lie: a *global* option placed
+        # after the subcommand, where Click says "No such option" about an
+        # option that very much exists.
+        message = e.format_message()
+        _safe_console_print(f"[red]Error: {message}[/red]")
+        hint = _global_option_hint(message)
+        if hint:
+            _safe_console_print(hint)
+        sys.exit(1)
     except Exception as e:
-        console.print(f"[red]Error: {e}[/red]")
-        sys.exit(2)
+        _safe_console_print(f"[red]Error: {e}[/red]")
+        sys.exit(1)  # 1 = error; 2 is reserved for user interrupt
 
 
 if __name__ == "__main__":

{deepctl-0.2.26 → deepctl-0.3.1/src/deepctl.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deepctl
-Version: 0.2.26
+Version: 0.3.1
 Summary: Official Deepgram CLI for speech recognition and audio intelligence
 Author-email: Deepgram <devrel@deepgram.com>
 Maintainer-email: Deepgram <devrel@deepgram.com>
@@ -26,36 +26,36 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: click>=8.0.0
-Requires-Dist: deepgram-sdk>=7.5.0
-Requires-Dist: deepctl-core>=0.1.10
-Requires-Dist: deepctl-cmd-login>=0.1.10
-Requires-Dist: deepctl-cmd-projects>=0.1.10
-Requires-Dist: deepctl-cmd-transcribe>=0.1.10
-Requires-Dist: deepctl-cmd-usage>=0.1.10
-Requires-Dist: deepctl-cmd-mcp>=0.1.10
-Requires-Dist: deepctl-cmd-api>=0.0.1
-Requires-Dist: deepctl-cmd-debug>=0.1.10
-Requires-Dist: deepctl-cmd-debug-browser>=0.1.10
-Requires-Dist: deepctl-cmd-debug-network>=0.1.10
-Requires-Dist: deepctl-cmd-debug-audio>=0.1.10
-Requires-Dist: deepctl-cmd-debug-probe>=0.0.1
-Requires-Dist: deepctl-cmd-debug-toolkit>=0.0.1
-Requires-Dist: deepctl-cmd-ffprobe>=0.0.1
-Requires-Dist: deepctl-cmd-update>=0.1.10
-Requires-Dist: deepctl-cmd-plugin>=0.1.10
-Requires-Dist: deepctl-cmd-skills>=0.0.1
-Requires-Dist: deepctl-cmd-init>=0.0.1
-Requires-Dist: deepctl-cmd-models>=0.0.1
-Requires-Dist: deepctl-cmd-speak>=0.0.1
-Requires-Dist: deepctl-cmd-keys>=0.0.1
-Requires-Dist: deepctl-cmd-read>=0.0.1
-Requires-Dist: deepctl-cmd-listen>=0.0.1
-Requires-Dist: deepctl-cmd-requests>=0.0.1
-Requires-Dist: deepctl-cmd-billing>=0.0.1
-Requires-Dist: deepctl-cmd-members>=0.0.1
-Requires-Dist: deepctl-cmd-completion>=0.0.1
-Requires-Dist: deepctl-shared-utils>=0.1.10
-Requires-Dist: deepctl-telemetry>=0.0.1
+Requires-Dist: deepgram-sdk<8,>=7.7.0
+Requires-Dist: deepctl-core>=0.2.17
+Requires-Dist: deepctl-cmd-login>=0.1.18
+Requires-Dist: deepctl-cmd-projects>=0.2.0
+Requires-Dist: deepctl-cmd-transcribe>=0.1.12
+Requires-Dist: deepctl-cmd-usage>=0.2.0
+Requires-Dist: deepctl-cmd-mcp>=0.1.15
+Requires-Dist: deepctl-cmd-api>=0.0.2
+Requires-Dist: deepctl-cmd-debug>=0.1.12
+Requires-Dist: deepctl-cmd-debug-browser>=0.1.12
+Requires-Dist: deepctl-cmd-debug-network>=0.1.12
+Requires-Dist: deepctl-cmd-debug-audio>=0.1.13
+Requires-Dist: deepctl-cmd-debug-probe>=0.0.2
+Requires-Dist: deepctl-cmd-debug-toolkit>=0.1.0
+Requires-Dist: deepctl-cmd-ffprobe>=0.0.2
+Requires-Dist: deepctl-cmd-update>=0.2.7
+Requires-Dist: deepctl-cmd-plugin>=0.1.13
+Requires-Dist: deepctl-cmd-skills>=0.0.8
+Requires-Dist: deepctl-cmd-init>=0.0.4
+Requires-Dist: deepctl-cmd-models>=0.1.1
+Requires-Dist: deepctl-cmd-speak>=0.0.4
+Requires-Dist: deepctl-cmd-keys>=0.1.0
+Requires-Dist: deepctl-cmd-read>=0.1.0
+Requires-Dist: deepctl-cmd-listen>=0.0.14
+Requires-Dist: deepctl-cmd-requests>=0.1.0
+Requires-Dist: deepctl-cmd-billing>=0.1.0
+Requires-Dist: deepctl-cmd-members>=0.1.0
+Requires-Dist: deepctl-cmd-completion>=0.0.3
+Requires-Dist: deepctl-shared-utils>=0.1.12
+Requires-Dist: deepctl-telemetry>=0.0.6
 Requires-Dist: pydantic>=2.0.0
 Requires-Dist: rich>=13.0.0
 Requires-Dist: httpx>=0.24.0
@@ -70,13 +70,15 @@ Requires-Dist: pytest>=7.0.0; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
 Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
 Requires-Dist: pytest-mock>=3.10.0; extra == "dev"
+Requires-Dist: pytest-timeout<3,>=2.3.1; extra == "dev"
 Requires-Dist: responses>=0.23.0; extra == "dev"
 Requires-Dist: ruff>=0.8.0; extra == "dev"
 Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: packaging>=23.0; extra == "dev"
 Requires-Dist: types-PyYAML>=6.0.0; extra == "dev"
 Requires-Dist: types-requests>=2.31.0; extra == "dev"
 Requires-Dist: pre-commit>=3.0.0; extra == "dev"
-Requires-Dist: twine>=4.0.0; extra == "dev"
+Requires-Dist: twine>=7.0.0; extra == "dev"
 Requires-Dist: build>=0.10.0; extra == "dev"
 Dynamic: license-file
 
@@ -115,8 +117,8 @@ intelligence, and project management directly into your terminal. Aliases:
 **macOS / Linux (Homebrew):**
 
 ```bash
-brew tap deepgram/tap
-brew install deepgram
+# Install and trust only the Deepgram formula.
+brew install deepgram/tap/deepgram
 ```
 
 Homebrew brings in `ffmpeg` and `portaudio` automatically — `dg listen --mic`, `dg debug probe`, and raw audio piping all work without further setup. To upgrade later: `brew upgrade deepgram`.
@@ -157,8 +159,8 @@ dg login
 # Transcribe an audio file
 dg listen recording.wav
 
-# Text-to-speech
-dg speak "Hello from Deepgram" -o hello.mp3
+# Text-to-speech (Flux TTS by default)
+dg speak "Hello from Deepgram" -o hello.wav
 
 # Live microphone transcription
 dg listen --mic
@@ -183,6 +185,10 @@ dg -o json listen standup.mp3 \
 # Live microphone with interim (partial) results
 dg listen --mic --model nova-3 --interim
 
+# Redact sensitive numbers and spell numbers as digits (files or live)
+# Flux STT (v2) accepts --redact numbers|aggressive_numbers; v1 also pci, ssn, …
+dg listen call.wav --redact numbers --numerals
+
 # Raw audio stream from ffmpeg
 ffmpeg -i video.mp4 -f s16le -ar 16000 -ac 1 - \
   | dg listen --encoding linear16
@@ -214,8 +220,9 @@ dg read earnings.txt --sentiment --summarize --topics
 ### Text-to-speech
 
 ```bash
-# Stream directly to a player
-dg speak "Hello from Deepgram" | ffplay -nodisp -autoexit -
+# Stream directly to a player (Flux TTS streams a WAV; -loglevel error hides
+# ffmpeg's cosmetic end-of-stream notice)
+dg speak "Hello from Deepgram" | ffplay -loglevel error -nodisp -autoexit -
 ```
 
 ### Account & project management
@@ -255,22 +262,30 @@ cat audio.raw | dg listen --encoding linear16 --sample-rate 16000
 
 Convert text to natural speech. Supports file output and piping.
 
-`aura-*` models use the Speak v1 batch REST API. `flux-*` (Flux TTS) models use
-the Speak v2 WebSocket API and stream by default; their raw `linear16` output is
-wrapped in a WAV container so it is directly playable.
+By default `dg speak` uses Flux TTS (`flux-alexis-en`) — the Speak v2 WebSocket
+API, which streams and emits raw audio; its `linear16` output is wrapped in a WAV
+container so it is directly playable. Pass an `aura-*` model to use the Speak v1
+batch REST API instead, which supports containerized formats like MP3.
 
 ```bash
-# Aura (v1, batch REST)
-dg speak "Welcome to Deepgram" -o welcome.mp3
-dg speak --file script.txt -o output.mp3 -m aura-2-luna-en
-echo "Hello" | dg speak -o greeting.mp3
-dg speak "Stream me" | ffplay -nodisp -            # pipe to audio player
-
-# Flux TTS (v2, WebSocket streaming)
-dg speak "Hello from Flux" -m flux-alexis-en -o hello.wav
+# Flux TTS (v2, WebSocket streaming) — the default
+dg speak "Hello from Flux" -o hello.wav
 # Piped audio is a streaming WAV; -loglevel error hides ffmpeg's cosmetic
 # end-of-stream notice (the audio is complete).
-dg speak "Hello from Flux" -m flux-alexis-en | ffplay -loglevel error -nodisp -autoexit -
+dg speak "Hello from Flux" | ffplay -loglevel error -nodisp -autoexit -
+
+# Flux TTS streaming controls (flux-* only): --speed 0.85–1.15 (0.05 steps).
+# --expressivity -2..2 is beta; its default 0 is nominal delivery.
+dg speak "A little slower" --speed 0.9 --expressivity 1 -o slow.wav
+
+# Aura (v1, batch REST) — opt in with -m aura-*; needed for MP3 output
+dg speak "Welcome to Deepgram" -o welcome.mp3 -m aura-2-asteria-en
+dg speak --file script.txt -o output.mp3 -m aura-2-luna-en
+echo "Hello" | dg speak -o greeting.mp3 -m aura-2-asteria-en
+
+# Aura-2 also has Spanish voices (e.g. aura-2-selena-es); run `dg models`
+# for the full, current list.
+dg speak "Hola, bienvenido a Deepgram" -o hola.mp3 -m aura-2-selena-es
 ```
 
 ### Text Intelligence
@@ -374,7 +389,7 @@ export DEEPGRAM_PROJECT_ID="your-project-id"
 
 # Non-interactive usage
 dg listen recording.wav
-dg speak "Deploy complete" -o notification.mp3
+dg speak "Deploy complete" -o notification.mp3 -m aura-2-asteria-en
 dg keys --create --comment "ci-key" --scopes member
 dg keys --delete KEY_ID --yes
 dg read --file report.txt --summarize
@@ -388,6 +403,24 @@ dg usage --last-week -o yaml
 When running in a non-TTY environment (pipes, CI, or AI coding tools), the CLI
 automatically switches to structured JSON output with plain-text status messages.
 
+### Exit codes
+
+Since 0.3.0, `dg` exits non-zero when a command fails — branch on the exit
+code, not on parsing output:
+
+| Code | Meaning |
+| --- | --- |
+| `0` | Success |
+| `1` | Error — a failed command, a crash, or a usage error (bad flag, unknown command) |
+| `2` | Cancelled by the user (Ctrl-C, or declining a confirmation prompt) |
+
+Note that `dg` reports `2` for an interrupt rather than the shell's
+conventional `130`, so the code is the same whether the cancellation came from
+Ctrl-C or from declining a prompt.
+
+If a CI step relied on `dg` always exiting `0` (every command did, before
+0.3.0), it will now fail where it previously passed silently.
+
 ### Forcing non-interactive mode
 
 Three explicit ways to skip every prompt and run with defaults — useful from a
@@ -431,7 +464,10 @@ dg profiles --list                       # List profiles
 dg profiles --switch staging             # Switch profile
 ```
 
-Output format on any command: `--output json|yaml|table|csv`
+For structured output, use `--output json|yaml|table|csv` after leaf commands
+that do not define their own output option, or before any command as a global
+flag: `dg --output json <command>`. `dg speak --output FILE` writes audio to
+`FILE`, so use `dg --output json speak ...` for Speak's structured output.
 
 ## Telemetry
 

deepctl-0.3.1/src/deepctl.egg-info/requires.txt

@@ -0,0 +1,56 @@
+click>=8.0.0
+deepgram-sdk<8,>=7.7.0
+deepctl-core>=0.2.17
+deepctl-cmd-login>=0.1.18
+deepctl-cmd-projects>=0.2.0
+deepctl-cmd-transcribe>=0.1.12
+deepctl-cmd-usage>=0.2.0
+deepctl-cmd-mcp>=0.1.15
+deepctl-cmd-api>=0.0.2
+deepctl-cmd-debug>=0.1.12
+deepctl-cmd-debug-browser>=0.1.12
+deepctl-cmd-debug-network>=0.1.12
+deepctl-cmd-debug-audio>=0.1.13
+deepctl-cmd-debug-probe>=0.0.2
+deepctl-cmd-debug-toolkit>=0.1.0
+deepctl-cmd-ffprobe>=0.0.2
+deepctl-cmd-update>=0.2.7
+deepctl-cmd-plugin>=0.1.13
+deepctl-cmd-skills>=0.0.8
+deepctl-cmd-init>=0.0.4
+deepctl-cmd-models>=0.1.1
+deepctl-cmd-speak>=0.0.4
+deepctl-cmd-keys>=0.1.0
+deepctl-cmd-read>=0.1.0
+deepctl-cmd-listen>=0.0.14
+deepctl-cmd-requests>=0.1.0
+deepctl-cmd-billing>=0.1.0
+deepctl-cmd-members>=0.1.0
+deepctl-cmd-completion>=0.0.3
+deepctl-shared-utils>=0.1.12
+deepctl-telemetry>=0.0.6
+pydantic>=2.0.0
+rich>=13.0.0
+httpx>=0.24.0
+requests<3.0,>=2.31
+pyjwt>=2.8.0
+keyring>=24.0.0
+pyyaml>=6.0.0
+typer>=0.9.0
+platformdirs>=3.0.0
+
+[dev]
+pytest>=7.0.0
+pytest-asyncio>=0.21.0
+pytest-cov>=4.0.0
+pytest-mock>=3.10.0
+pytest-timeout<3,>=2.3.1
+responses>=0.23.0
+ruff>=0.8.0
+mypy>=1.0.0
+packaging>=23.0
+types-PyYAML>=6.0.0
+types-requests>=2.31.0
+pre-commit>=3.0.0
+twine>=7.0.0
+build>=0.10.0

deepctl-0.2.26/src/deepctl.egg-info/requires.txt

@@ -1,54 +0,0 @@
-click>=8.0.0
-deepgram-sdk>=7.5.0
-deepctl-core>=0.1.10
-deepctl-cmd-login>=0.1.10
-deepctl-cmd-projects>=0.1.10
-deepctl-cmd-transcribe>=0.1.10
-deepctl-cmd-usage>=0.1.10
-deepctl-cmd-mcp>=0.1.10
-deepctl-cmd-api>=0.0.1
-deepctl-cmd-debug>=0.1.10
-deepctl-cmd-debug-browser>=0.1.10
-deepctl-cmd-debug-network>=0.1.10
-deepctl-cmd-debug-audio>=0.1.10
-deepctl-cmd-debug-probe>=0.0.1
-deepctl-cmd-debug-toolkit>=0.0.1
-deepctl-cmd-ffprobe>=0.0.1
-deepctl-cmd-update>=0.1.10
-deepctl-cmd-plugin>=0.1.10
-deepctl-cmd-skills>=0.0.1
-deepctl-cmd-init>=0.0.1
-deepctl-cmd-models>=0.0.1
-deepctl-cmd-speak>=0.0.1
-deepctl-cmd-keys>=0.0.1
-deepctl-cmd-read>=0.0.1
-deepctl-cmd-listen>=0.0.1
-deepctl-cmd-requests>=0.0.1
-deepctl-cmd-billing>=0.0.1
-deepctl-cmd-members>=0.0.1
-deepctl-cmd-completion>=0.0.1
-deepctl-shared-utils>=0.1.10
-deepctl-telemetry>=0.0.1
-pydantic>=2.0.0
-rich>=13.0.0
-httpx>=0.24.0
-requests<3.0,>=2.31
-pyjwt>=2.8.0
-keyring>=24.0.0
-pyyaml>=6.0.0
-typer>=0.9.0
-platformdirs>=3.0.0
-
-[dev]
-pytest>=7.0.0
-pytest-asyncio>=0.21.0
-pytest-cov>=4.0.0
-pytest-mock>=3.10.0
-responses>=0.23.0
-ruff>=0.8.0
-mypy>=1.0.0
-types-PyYAML>=6.0.0
-types-requests>=2.31.0
-pre-commit>=3.0.0
-twine>=4.0.0
-build>=0.10.0