deepctl 0.2.2__tar.gz → 0.2.4__tar.gz

deepctl-0.2.4/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-present Deepgram, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

{deepctl-0.2.2 → deepctl-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deepctl
-Version: 0.2.2
+Version: 0.2.4
 Summary: Official Deepgram CLI for speech recognition and audio intelligence
 Author-email: Deepgram <devrel@deepgram.com>
 Maintainer-email: Deepgram <devrel@deepgram.com>
@@ -24,6 +24,7 @@ Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
+License-File: LICENSE
 Requires-Dist: click>=8.0.0
 Requires-Dist: deepgram-sdk>=6.0.0rc2
 Requires-Dist: deepctl-core>=0.1.10
@@ -74,171 +75,298 @@ 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: build>=0.10.0; extra == "dev"
+Dynamic: license-file
+
+# Deepgram CLI
+
+[![Test](https://github.com/deepgram/cli/actions/workflows/test.yml/badge.svg)](https://github.com/deepgram/cli/actions/workflows/test.yml)
+[![Version](https://img.shields.io/pypi/v/deepctl)](https://pypi.org/project/deepctl/)
+[![Python](https://img.shields.io/pypi/pyversions/deepctl)](https://pypi.org/project/deepctl/)
+[![License](https://img.shields.io/github/license/deepgram/cli)](https://github.com/deepgram/cli/blob/main/LICENSE)
+```sh
+Usage: dg [OPTIONS] COMMAND [ARGS]...
+
+████████████████
+██████████████████
+████████████████████
+█████████████████████
+███████      ████████
+███████       ███████
+             ████████
+      ███████████████
+    ████████████████
+  ████████████████
+████████████████
+
+deepctl — Official Deepgram CLI STT · TTS · Audio Intelligence
+```
 
-# deepctl
-
-> [!WARNING]  
-> **Alpha Software**: This CLI is experimental and under active development.
+The official Deepgram CLI brings speech-to-text, text-to-speech, audio
+intelligence, and project management directly into your terminal. Aliases:
+`deepctl`, `deepgram`, `dg`.
 
-Official Deepgram CLI. Modular Python package with plugin system.
+## Installation
 
-## Development
+### Quick Install
 
-### Setup
+**macOS / Linux:**
 
 ```bash
-git clone https://github.com/deepgram/cli && cd cli
-uv sync
+curl -fsSL https://deepgram.com/install.sh | sh
+```
+
+**Windows (PowerShell):**
+
+```powershell
+iwr https://deepgram.com/install.ps1 -useb | iex
 ```
 
-### Run CLI
+### Package Managers
 
 ```bash
-uv run deepctl --help
-uv run deepctl login
-uv run deepctl transcribe audio.wav
+pip install deepctl          # pip
+uv tool install deepctl      # uv
+pipx install deepctl         # pipx
 ```
 
-### Development Commands
+### Try Without Installing
 
 ```bash
-make dev                   # Format, lint, test
-make check                 # Format, lint, typecheck (no tests)
-make test                  # Run tests
+uvx deepctl --help
+pipx run deepctl --help
 ```
 
-### Requirements
+## Getting Started
 
-- Python 3.10+
-- uv package manager
-- Cross-platform: Linux, Windows, macOS
+```bash
+# Authenticate with Deepgram
+dg login
 
-### Architecture
+# Transcribe an audio file
+dg transcribe recording.wav
 
-<!-- BEGIN:architecture -->
+# Text-to-speech
+dg speak "Hello from Deepgram" -o hello.mp3
+
+# Live microphone transcription
+dg listen --mic
+
+# Analyze text for sentiment and topics
+dg read "The product is amazing" --sentiment --topics
 ```
-cli/
-├── src/deepctl/                      # Main CLI entry point
-├── packages/
-│   ├── deepctl-cmd-api/              # API command for deepctl
-│   ├── deepctl-cmd-billing/          # Billing command for deepctl
-│   ├── deepctl-cmd-debug/            # Debug command group for deepctl
-│   ├── deepctl-cmd-debug-audio/      # Audio debug subcommand for deepctl
-│   ├── deepctl-cmd-debug-browser/    # Browser debug subcommand for deepctl
-│   ├── deepctl-cmd-debug-network/    # Network debug subcommand for deepctl
-│   ├── deepctl-cmd-debug-probe/      # Debug probe subcommand for deepctl — live ffprobe analysis during streaming
-│   ├── deepctl-cmd-ffprobe/          # FFprobe configuration command for deepctl
-│   ├── deepctl-cmd-init/             # Init command for deepctl — scaffold Deepgram starter apps
-│   ├── deepctl-cmd-keys/             # API keys management command for deepctl
-│   ├── deepctl-cmd-listen/           # Listen (live speech-to-text) command for deepctl
-│   ├── deepctl-cmd-login/            # Login command for deepctl
-│   ├── deepctl-cmd-mcp/              # MCP proxy command for deepctl — connects to Deepgram's developer API
-│   ├── deepctl-cmd-members/          # Members management command for deepctl
-│   ├── deepctl-cmd-models/           # Models command for deepctl
-│   ├── deepctl-cmd-plugin/           # Plugin management command for deepctl
-│   ├── deepctl-cmd-projects/         # Projects command for deepctl
-│   ├── deepctl-cmd-read/             # Read (text intelligence) command for deepctl
-│   ├── deepctl-cmd-requests/         # Requests history command for deepctl
-│   ├── deepctl-cmd-skills/           # AI coding assistant skill management for deepctl
-│   ├── deepctl-cmd-speak/            # Speak (text-to-speech) command for deepctl
-│   ├── deepctl-cmd-transcribe/       # Transcribe command for deepctl
-│   ├── deepctl-cmd-update/           # Update command for deepctl
-│   ├── deepctl-cmd-usage/            # Usage command for deepctl
-│   ├── deepctl-core/                 # Core components for deepctl
-│   ├── deepctl-plugin-example/       # Example plugin for deepctl
-│   └── deepctl-shared-utils/         # Shared utilities for deepctl
-├── tests/                            # Integration tests
-└── Makefile                          # Development tasks
+
+## Features
+
+### Speech-to-Text
+
+Transcribe audio files, URLs, or live microphone input.
+
+```bash
+dg transcribe meeting.wav --diarize --smart-format
+dg transcribe https://example.com/audio.mp3 --model nova-3
+dg listen --mic --model nova-3 --language en-US
+cat audio.raw | dg listen --encoding linear16 --sample-rate 16000
 ```
-<!-- END:architecture -->
 
-### Plugin Development
+### Text-to-Speech
+
+Convert text to natural speech. Supports file output and piping.
+
+```bash
+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
+```
 
-```python
-from deepctl_core.base_command import BaseCommand
+### Text Intelligence
 
-class MyCommand(BaseCommand):
-    name = "mycommand"
-    help = "My custom command"
+Analyze text for sentiment, summaries, topics, and intents.
 
-    def handle(self, config, auth_manager, client, **kwargs):
-        pass
+```bash
+dg read "Customer called about billing" --sentiment --summarize
+dg read --file article.txt --topics --intents
+cat feedback.txt | dg read --sentiment
 ```
 
-Register your command in `pyproject.toml` under the `deepctl.plugins` entry point group:
+### Project Management
+
+Manage your Deepgram account from the terminal.
 
-```toml
-[project.entry-points."deepctl.plugins"]
-mycommand = "my_plugin.command:MyCommand"
+```bash
+dg projects --list                        # List projects
+dg keys --list                            # List API keys
+dg keys --create --comment "staging"      # Create API key
+dg members                                # List team members
+dg members --invite user@co.com           # Invite member
+dg usage --last-month                     # View usage stats
+dg billing                                # Check balances
+dg requests --limit 20 --status failed    # Request history
+dg models --type tts                      # List available models
 ```
 
-See [`packages/deepctl-plugin-example`](packages/deepctl-plugin-example).
+### Direct API Access
 
-### Testing
+Make authenticated requests to any Deepgram endpoint.
 
-- `tests/` - Integration tests
-- `packages/*/tests/unit/` - Unit tests
-- Runs on Python 3.10-3.14, Linux/Windows/macOS
+```bash
+dg api /v1/projects
+dg api /v1/projects -X POST -f name="New Project"
+dg api /v1/listen -X POST --input audio.wav --jq '.results'
+```
 
-## Release
+### Debugging Tools
 
-Merging conventional commits to `main` triggers [release-please](https://github.com/googleapis/release-please) to open a release PR. Merging that PR creates a `v*` tag, which triggers the PyPI publish workflow. All packages are version-locked.
+Diagnose audio, network, and browser issues.
 
-## Installation
+```bash
+dg debug audio --file recording.wav       # Analyze audio compatibility
+dg debug network --verbose                # Test connectivity to Deepgram
+dg debug probe --port 3100                # Live stream audio analysis
+```
 
-### Quick Install
+### MCP Server
 
-**macOS / Linux:**
+Connect Deepgram tools to AI coding assistants (Claude Code, Cursor, etc.).
 
 ```bash
-curl -fsSL https://deepgram.com/install.sh | sh
+dg mcp                                    # Start MCP server (stdio)
+dg mcp --transport sse --port 8000        # SSE transport
 ```
 
-**Windows (PowerShell):**
+Add to your editor's MCP config:
 
-```powershell
-iwr https://deepgram.com/install.ps1 -useb | iex
+```json
+{
+  "mcpServers": {
+    "deepgram": {
+      "type": "stdio",
+      "command": "dg",
+      "args": ["mcp"]
+    }
+  }
+}
 ```
 
-### Install Options
+### AI Tool Integration
+
+Automatically detect and configure AI coding assistants with Deepgram skills.
 
 ```bash
-# Install a specific version
-curl -fsSL https://deepgram.com/install.sh | sh -s -- v0.2.1
+dg skills status                          # Detect AI tools
+dg skills setup                           # Interactive setup wizard
+dg skills install --all                   # Install for all detected tools
+```
+
+### Starter Apps
 
-# Force reinstall over existing installation
-curl -fsSL https://deepgram.com/install.sh | sh -s -- --force
+Scaffold a new project from Deepgram templates.
 
-# Both
-curl -fsSL https://deepgram.com/install.sh | sh -s -- --force v0.2.1
+```bash
+dg init --list                            # Browse templates
+dg init node-live-transcription           # Clone and set up
 ```
 
-**Windows (PowerShell):**
+## CI / Automation
 
-```powershell
-# Install a specific version
-$env:DEEPCTL_VERSION='0.2.1'; iwr https://deepgram.com/install.ps1 -useb | iex
+Every command is CI-friendly. Authentication works via environment variables,
+all interactive prompts have flag-based alternatives, and destructive operations
+require explicit `--yes`.
 
-# Force reinstall
-$env:DEEPCTL_FORCE='1'; iwr https://deepgram.com/install.ps1 -useb | iex
+```bash
+# CI authentication
+export DEEPGRAM_API_KEY="your-key"
+export DEEPGRAM_PROJECT_ID="your-project-id"
+
+# Non-interactive usage
+dg transcribe recording.wav
+dg speak "Deploy complete" -o notification.mp3
+dg keys --create --comment "ci-key" --scopes member
+dg keys --delete KEY_ID --yes
+dg read --file report.txt --summarize
+
+# Output formats for scripting
+dg projects --list -o json
+dg keys --list -o csv
+dg usage --last-week -o yaml
 ```
 
-### Other Methods
+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.
+
+## Plugins
+
+Extend the CLI with custom commands.
 
 ```bash
-uv tool install deepctl
-pip install deepctl
-pipx install deepctl
+dg plugin search deepctl-               # Find plugins
+dg plugin install <package>              # Install
+dg plugin list                           # List installed
+dg plugin remove <package>              # Remove
 ```
 
-### Try Without Installing
+Create your own — see the [plugin example](packages/deepctl-plugin-example).
+
+## Configuration
+
+**Priority:** CLI flags > environment variables > profile config > project config
 
 ```bash
-uv run deepctl --help
-pipx run deepctl --help
+dg login                                 # Interactive or --api-key
+dg login --profile staging --api-key SK  # Named profiles
+dg profiles --list                       # List profiles
+dg profiles --switch staging             # Switch profile
+```
+
+Output format on any command: `--output json|yaml|table|csv`
+
+## Development
+
+```bash
+git clone https://github.com/deepgram/cli && cd cli
+uv sync --group dev
+make dev                                 # Format + lint + test
+make check                               # Format + lint + typecheck (no tests)
 ```
 
-## Usage
+### Architecture
+
+<!-- BEGIN:architecture -->
+```
+cli/
+├── src/deepctl/                      # Main CLI entry point
+├── packages/
+│   ├── deepctl-cmd-api/              # API command for deepctl
+│   ├── deepctl-cmd-billing/          # Billing command for deepctl
+│   ├── deepctl-cmd-debug/            # Debug command group for deepctl
+│   ├── deepctl-cmd-debug-audio/      # Audio debug subcommand for deepctl
+│   ├── deepctl-cmd-debug-browser/    # Browser debug subcommand for deepctl
+│   ├── deepctl-cmd-debug-network/    # Network debug subcommand for deepctl
+│   ├── deepctl-cmd-debug-probe/      # Debug probe subcommand for deepctl — live ffprobe analysis during streaming
+│   ├── deepctl-cmd-ffprobe/          # FFprobe configuration command for deepctl
+│   ├── deepctl-cmd-init/             # Init command for deepctl — scaffold Deepgram starter apps
+│   ├── deepctl-cmd-keys/             # API keys management command for deepctl
+│   ├── deepctl-cmd-listen/           # Listen (live speech-to-text) command for deepctl
+│   ├── deepctl-cmd-login/            # Login command for deepctl
+│   ├── deepctl-cmd-mcp/              # MCP proxy command for deepctl — connects to Deepgram's developer API
+│   ├── deepctl-cmd-members/          # Members management command for deepctl
+│   ├── deepctl-cmd-models/           # Models command for deepctl
+│   ├── deepctl-cmd-plugin/           # Plugin management command for deepctl
+│   ├── deepctl-cmd-projects/         # Projects command for deepctl
+│   ├── deepctl-cmd-read/             # Read (text intelligence) command for deepctl
+│   ├── deepctl-cmd-requests/         # Requests history command for deepctl
+│   ├── deepctl-cmd-skills/           # AI coding assistant skill management for deepctl
+│   ├── deepctl-cmd-speak/            # Speak (text-to-speech) command for deepctl
+│   ├── deepctl-cmd-transcribe/       # Transcribe command for deepctl
+│   ├── deepctl-cmd-update/           # Update command for deepctl
+│   ├── deepctl-cmd-usage/            # Usage command for deepctl
+│   ├── deepctl-core/                 # Core components for deepctl
+│   ├── deepctl-plugin-example/       # Example plugin for deepctl
+│   └── deepctl-shared-utils/         # Shared utilities for deepctl
+├── tests/                            # Integration tests
+└── Makefile                          # Development tasks
+```
+<!-- END:architecture -->
 
 ### Commands
 
@@ -273,71 +401,7 @@ pipx run deepctl --help
 | `deepctl usage` | Usage command for deepctl |
 <!-- END:commands -->
 
-### Aliases
-
-- `deepctl` (primary)
-- `deepgram`
-- `dg`
-
-### Plugins
-
-```bash
-deepctl plugin search                    # Browse available plugins
-deepctl plugin install <package>         # Install a plugin
-deepctl plugin list -v                   # List installed plugins (verbose)
-deepctl plugin remove <package>          # Remove a plugin
-deepctl plugin update <package>          # Update a plugin
-```
-
-Plugin installation adapts to how deepctl was installed:
-
-| Install method | Plugin strategy |
-|---|---|
-| `pip` / `uv` (venv) | Installs into current environment |
-| `pipx` | `pipx inject deepctl <plugin>` |
-| `uv tool` | `uv tool install deepctl --with <plugin>` |
-| Homebrew / system / binary | Isolated venv at `~/.deepctl/plugins/venv/` |
-| Development (editable) | Installs into current environment |
-| `uvx` / `pipx run` | Not supported (ephemeral) |
-
-Plugins installed into the isolated venv are automatically discovered and loaded on every CLI invocation.
-
-### Configuration
-
-Priority: CLI args > env vars > user config (`~/.config/deepctl/config.yaml` on Linux, `~/Library/Application Support/deepctl/config.yaml` on macOS) > `./deepgram.yaml`
-
-### Output Formats
-
-```bash
-deepctl transcribe audio.wav --output json|yaml|table|csv
-```
-
-### MCP Server
-
-Use `deepctl mcp` to connect Deepgram's developer tools to your AI code editor.
-
-```bash
-# Login first
-deepctl login
-```
-
-Add to your editor's MCP config (Claude Code `.mcp.json`, Cursor `.cursor/mcp.json`, etc.):
-
-```json
-{
-  "mcpServers": {
-    "deepgram": {
-      "type": "stdio",
-      "command": "uvx",
-      "args": ["deepctl", "mcp"]
-    }
-  }
-}
-```
-
-See [`deepctl-cmd-mcp`](packages/deepctl-cmd-mcp) for full setup instructions including Cursor, Windsurf, pipx, and local development.
-
-## Packages
+### Packages
 
 <!-- BEGIN:packages -->
 | Package | Description |
@@ -371,16 +435,31 @@ See [`deepctl-cmd-mcp`](packages/deepctl-cmd-mcp) for full setup instructions in
 | [`deepctl-shared-utils`](packages/deepctl-shared-utils) | Shared utilities for deepctl |
 <!-- END:packages -->
 
+## Release
+
+Merging [conventional commits](https://www.conventionalcommits.org/) to `main`
+triggers [release-please](https://github.com/googleapis/release-please) to open
+a release PR. Merging that PR creates tags and publishes all changed packages to
+PyPI. Each package is versioned independently.
+
+## Requirements
+
+- Python 3.10+
+- Cross-platform: Linux, Windows, macOS
+
 ## Contributing
 
-1. Fork repository
-2. Run `make dev` (formats, lints, tests)
-3. Add tests for changes
-4. Submit pull request
+1. Fork the repository
+2. `uv sync --group dev`
+3. `make dev` (formats, lints, tests)
+4. Submit a pull request
+
+See [AGENTS.md](AGENTS.md) for detailed architecture and conventions.
 
 ## Links
 
 - [Documentation](https://developers.deepgram.com/docs/cli)
+- [API Reference](https://developers.deepgram.com/reference)
 - [Discord](https://discord.gg/deepgram)
 - [Issues](https://github.com/deepgram/cli/issues)