deepctl 0.3.0__tar.gz → 0.3.2__tar.gz

{deepctl-0.3.0/src/deepctl.egg-info → deepctl-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deepctl
-Version: 0.3.0
+Version: 0.3.2
 Summary: Official Deepgram CLI for speech recognition and audio intelligence
 Author-email: Deepgram <devrel@deepgram.com>
 Maintainer-email: Deepgram <devrel@deepgram.com>
@@ -27,25 +27,25 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: click>=8.0.0
 Requires-Dist: deepgram-sdk<8,>=7.7.0
-Requires-Dist: deepctl-core>=0.2.16
-Requires-Dist: deepctl-cmd-login>=0.1.17
+Requires-Dist: deepctl-core>=0.2.18
+Requires-Dist: deepctl-cmd-login>=0.1.19
 Requires-Dist: deepctl-cmd-projects>=0.2.0
-Requires-Dist: deepctl-cmd-transcribe>=0.1.10
-Requires-Dist: deepctl-cmd-usage>=0.2.0
+Requires-Dist: deepctl-cmd-transcribe>=0.1.12
+Requires-Dist: deepctl-cmd-usage>=0.2.1
 Requires-Dist: deepctl-cmd-mcp>=0.1.15
-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.2.6
-Requires-Dist: deepctl-cmd-plugin>=0.1.10
-Requires-Dist: deepctl-cmd-skills>=0.0.7
-Requires-Dist: deepctl-cmd-init>=0.0.1
-Requires-Dist: deepctl-cmd-models>=0.1.0
+Requires-Dist: deepctl-cmd-api>=0.0.2
+Requires-Dist: deepctl-cmd-debug>=0.1.13
+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.14
+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.3
+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
@@ -53,9 +53,9 @@ 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.1
-Requires-Dist: deepctl-shared-utils>=0.1.10
-Requires-Dist: deepctl-telemetry>=0.0.6
+Requires-Dist: deepctl-cmd-completion>=0.0.3
+Requires-Dist: deepctl-shared-utils>=0.1.13
+Requires-Dist: deepctl-telemetry>=0.0.7
 Requires-Dist: pydantic>=2.0.0
 Requires-Dist: rich>=13.0.0
 Requires-Dist: httpx>=0.24.0
@@ -74,6 +74,7 @@ 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"
@@ -116,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`.
@@ -399,8 +400,36 @@ dg keys --list -o csv
 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.
+In CI, in AI coding tools, and in any fully non-interactive environment with
+no terminal attached (cron, systemd, `docker run` without `-t`), the CLI
+detects the context and automatically switches to structured JSON output with
+plain-text status messages. A plain pipe on its own does not trigger this —
+`dg projects | jq` from an interactive shell still gets the human-readable
+table, so pass `-o json` explicitly when you are piping by hand.
+
+### 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.
+
+Human-readable status and error messages go to stderr, and stdout carries the
+result. With an explicit structured-output mode, authentication-guard failures
+and commands that return an error result write a payload with `"status":
+"error"` to stdout — authentication failures, `dg ffprobe`, and `dg debug
+audio` included. Usage errors and handler-raised exceptions report on stderr
+and can leave stdout empty. Branch on the exit code rather than on whether
+stdout parsed. 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
 
@@ -408,7 +437,7 @@ Three explicit ways to skip every prompt and run with defaults — useful from a
 real terminal where auto-detection wouldn't otherwise trigger:
 
 ```bash
-# Global flag (works at any position)
+# Global flag (before any command, or after a leaf command)
 dg --non-interactive listen recording.wav
 dg listen --non-interactive recording.wav
 
@@ -445,7 +474,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
 
@@ -457,10 +489,14 @@ The CLI phones home anonymous error reports to help us catch crashes and regress
 
 ### Opt out
 
-Persistent (recommended):
+Persistent (recommended) — add this to your `config.yaml`
+(`~/.config/deepctl/config.yaml` on Linux,
+`~/Library/Application Support/deepctl/config.yaml` on macOS,
+`%LOCALAPPDATA%\deepgram\deepctl\config.yaml` on Windows):
 
-```bash
-dg config set telemetry.enabled false
+```yaml
+telemetry:
+  enabled: false
 ```
 
 One-shot (CI, scripts, single command):

{deepctl-0.3.0 → deepctl-0.3.2}/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`.
@@ -316,8 +316,36 @@ dg keys --list -o csv
 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.
+In CI, in AI coding tools, and in any fully non-interactive environment with
+no terminal attached (cron, systemd, `docker run` without `-t`), the CLI
+detects the context and automatically switches to structured JSON output with
+plain-text status messages. A plain pipe on its own does not trigger this —
+`dg projects | jq` from an interactive shell still gets the human-readable
+table, so pass `-o json` explicitly when you are piping by hand.
+
+### 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.
+
+Human-readable status and error messages go to stderr, and stdout carries the
+result. With an explicit structured-output mode, authentication-guard failures
+and commands that return an error result write a payload with `"status":
+"error"` to stdout — authentication failures, `dg ffprobe`, and `dg debug
+audio` included. Usage errors and handler-raised exceptions report on stderr
+and can leave stdout empty. Branch on the exit code rather than on whether
+stdout parsed. 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
 
@@ -325,7 +353,7 @@ Three explicit ways to skip every prompt and run with defaults — useful from a
 real terminal where auto-detection wouldn't otherwise trigger:
 
 ```bash
-# Global flag (works at any position)
+# Global flag (before any command, or after a leaf command)
 dg --non-interactive listen recording.wav
 dg listen --non-interactive recording.wav
 
@@ -362,7 +390,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
 
@@ -374,10 +405,14 @@ The CLI phones home anonymous error reports to help us catch crashes and regress
 
 ### Opt out
 
-Persistent (recommended):
+Persistent (recommended) — add this to your `config.yaml`
+(`~/.config/deepctl/config.yaml` on Linux,
+`~/Library/Application Support/deepctl/config.yaml` on macOS,
+`%LOCALAPPDATA%\deepgram\deepctl\config.yaml` on Windows):
 
-```bash
-dg config set telemetry.enabled false
+```yaml
+telemetry:
+  enabled: false
 ```
 
 One-shot (CI, scripts, single command):

{deepctl-0.3.0 → deepctl-0.3.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "deepctl"
-version = "0.3.0" # x-release-please-version
+version = "0.3.2" # x-release-please-version
 description = "Official Deepgram CLI for speech recognition and audio intelligence"
 readme = "README.md"
 license = "MIT"
@@ -35,25 +35,25 @@ requires-python = ">=3.10"
 dependencies = [
     "click>=8.0.0",
     "deepgram-sdk>=7.7.0,<8",
-    "deepctl-core>=0.2.16",
-    "deepctl-cmd-login>=0.1.17",
+    "deepctl-core>=0.2.18",
+    "deepctl-cmd-login>=0.1.19",
     "deepctl-cmd-projects>=0.2.0",
-    "deepctl-cmd-transcribe>=0.1.10",
-    "deepctl-cmd-usage>=0.2.0",
+    "deepctl-cmd-transcribe>=0.1.12",
+    "deepctl-cmd-usage>=0.2.1",
     "deepctl-cmd-mcp>=0.1.15",
-    "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.2.6",
-    "deepctl-cmd-plugin>=0.1.10",
-    "deepctl-cmd-skills>=0.0.7",
-    "deepctl-cmd-init>=0.0.1",
-    "deepctl-cmd-models>=0.1.0",
+    "deepctl-cmd-api>=0.0.2",
+    "deepctl-cmd-debug>=0.1.13",
+    "deepctl-cmd-debug-browser>=0.1.12",
+    "deepctl-cmd-debug-network>=0.1.12",
+    "deepctl-cmd-debug-audio>=0.1.14",
+    "deepctl-cmd-debug-probe>=0.0.2",
+    "deepctl-cmd-debug-toolkit>=0.1.0",
+    "deepctl-cmd-ffprobe>=0.0.3",
+    "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",
@@ -61,9 +61,9 @@ dependencies = [
     "deepctl-cmd-requests>=0.1.0",
     "deepctl-cmd-billing>=0.1.0",
     "deepctl-cmd-members>=0.1.0",
-    "deepctl-cmd-completion>=0.0.1",
-    "deepctl-shared-utils>=0.1.10",
-    "deepctl-telemetry>=0.0.6",
+    "deepctl-cmd-completion>=0.0.3",
+    "deepctl-shared-utils>=0.1.13",
+    "deepctl-telemetry>=0.0.7",
     "pydantic>=2.0.0",
     "rich>=13.0.0",
     "httpx>=0.24.0",
@@ -87,6 +87,7 @@ dev = [
     # 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",
@@ -128,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.*"
@@ -232,6 +239,10 @@ 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",
@@ -244,6 +255,9 @@ 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",

{deepctl-0.3.0 → deepctl-0.3.2}/src/deepctl/__init__.py

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

{deepctl-0.3.0 → deepctl-0.3.2}/src/deepctl/main.py

@@ -287,6 +287,38 @@ 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.
 
@@ -401,6 +433,17 @@ def main() -> None:
         # 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:
         _safe_console_print(f"[red]Error: {e}[/red]")
         sys.exit(1)  # 1 = error; 2 is reserved for user interrupt

{deepctl-0.3.0 → deepctl-0.3.2/src/deepctl.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deepctl
-Version: 0.3.0
+Version: 0.3.2
 Summary: Official Deepgram CLI for speech recognition and audio intelligence
 Author-email: Deepgram <devrel@deepgram.com>
 Maintainer-email: Deepgram <devrel@deepgram.com>
@@ -27,25 +27,25 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: click>=8.0.0
 Requires-Dist: deepgram-sdk<8,>=7.7.0
-Requires-Dist: deepctl-core>=0.2.16
-Requires-Dist: deepctl-cmd-login>=0.1.17
+Requires-Dist: deepctl-core>=0.2.18
+Requires-Dist: deepctl-cmd-login>=0.1.19
 Requires-Dist: deepctl-cmd-projects>=0.2.0
-Requires-Dist: deepctl-cmd-transcribe>=0.1.10
-Requires-Dist: deepctl-cmd-usage>=0.2.0
+Requires-Dist: deepctl-cmd-transcribe>=0.1.12
+Requires-Dist: deepctl-cmd-usage>=0.2.1
 Requires-Dist: deepctl-cmd-mcp>=0.1.15
-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.2.6
-Requires-Dist: deepctl-cmd-plugin>=0.1.10
-Requires-Dist: deepctl-cmd-skills>=0.0.7
-Requires-Dist: deepctl-cmd-init>=0.0.1
-Requires-Dist: deepctl-cmd-models>=0.1.0
+Requires-Dist: deepctl-cmd-api>=0.0.2
+Requires-Dist: deepctl-cmd-debug>=0.1.13
+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.14
+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.3
+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
@@ -53,9 +53,9 @@ 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.1
-Requires-Dist: deepctl-shared-utils>=0.1.10
-Requires-Dist: deepctl-telemetry>=0.0.6
+Requires-Dist: deepctl-cmd-completion>=0.0.3
+Requires-Dist: deepctl-shared-utils>=0.1.13
+Requires-Dist: deepctl-telemetry>=0.0.7
 Requires-Dist: pydantic>=2.0.0
 Requires-Dist: rich>=13.0.0
 Requires-Dist: httpx>=0.24.0
@@ -74,6 +74,7 @@ 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"
@@ -116,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`.
@@ -399,8 +400,36 @@ dg keys --list -o csv
 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.
+In CI, in AI coding tools, and in any fully non-interactive environment with
+no terminal attached (cron, systemd, `docker run` without `-t`), the CLI
+detects the context and automatically switches to structured JSON output with
+plain-text status messages. A plain pipe on its own does not trigger this —
+`dg projects | jq` from an interactive shell still gets the human-readable
+table, so pass `-o json` explicitly when you are piping by hand.
+
+### 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.
+
+Human-readable status and error messages go to stderr, and stdout carries the
+result. With an explicit structured-output mode, authentication-guard failures
+and commands that return an error result write a payload with `"status":
+"error"` to stdout — authentication failures, `dg ffprobe`, and `dg debug
+audio` included. Usage errors and handler-raised exceptions report on stderr
+and can leave stdout empty. Branch on the exit code rather than on whether
+stdout parsed. 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
 
@@ -408,7 +437,7 @@ Three explicit ways to skip every prompt and run with defaults — useful from a
 real terminal where auto-detection wouldn't otherwise trigger:
 
 ```bash
-# Global flag (works at any position)
+# Global flag (before any command, or after a leaf command)
 dg --non-interactive listen recording.wav
 dg listen --non-interactive recording.wav
 
@@ -445,7 +474,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
 
@@ -457,10 +489,14 @@ The CLI phones home anonymous error reports to help us catch crashes and regress
 
 ### Opt out
 
-Persistent (recommended):
+Persistent (recommended) — add this to your `config.yaml`
+(`~/.config/deepctl/config.yaml` on Linux,
+`~/Library/Application Support/deepctl/config.yaml` on macOS,
+`%LOCALAPPDATA%\deepgram\deepctl\config.yaml` on Windows):
 
-```bash
-dg config set telemetry.enabled false
+```yaml
+telemetry:
+  enabled: false
 ```
 
 One-shot (CI, scripts, single command):

{deepctl-0.3.0 → deepctl-0.3.2}/src/deepctl.egg-info/requires.txt

@@ -1,24 +1,24 @@
 click>=8.0.0
 deepgram-sdk<8,>=7.7.0
-deepctl-core>=0.2.16
-deepctl-cmd-login>=0.1.17
+deepctl-core>=0.2.18
+deepctl-cmd-login>=0.1.19
 deepctl-cmd-projects>=0.2.0
-deepctl-cmd-transcribe>=0.1.10
-deepctl-cmd-usage>=0.2.0
+deepctl-cmd-transcribe>=0.1.12
+deepctl-cmd-usage>=0.2.1
 deepctl-cmd-mcp>=0.1.15
-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.2.6
-deepctl-cmd-plugin>=0.1.10
-deepctl-cmd-skills>=0.0.7
-deepctl-cmd-init>=0.0.1
-deepctl-cmd-models>=0.1.0
+deepctl-cmd-api>=0.0.2
+deepctl-cmd-debug>=0.1.13
+deepctl-cmd-debug-browser>=0.1.12
+deepctl-cmd-debug-network>=0.1.12
+deepctl-cmd-debug-audio>=0.1.14
+deepctl-cmd-debug-probe>=0.0.2
+deepctl-cmd-debug-toolkit>=0.1.0
+deepctl-cmd-ffprobe>=0.0.3
+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
@@ -26,9 +26,9 @@ 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.1
-deepctl-shared-utils>=0.1.10
-deepctl-telemetry>=0.0.6
+deepctl-cmd-completion>=0.0.3
+deepctl-shared-utils>=0.1.13
+deepctl-telemetry>=0.0.7
 pydantic>=2.0.0
 rich>=13.0.0
 httpx>=0.24.0
@@ -48,6 +48,7 @@ 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