Metadata-Version: 2.4
Name: deepctl
Version: 0.2.2
Summary: Official Deepgram CLI for speech recognition and audio intelligence
Author-email: Deepgram <devrel@deepgram.com>
Maintainer-email: Deepgram <devrel@deepgram.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/deepgram/cli
Project-URL: Documentation, https://developers.deepgram.com/docs/cli
Project-URL: Repository, https://github.com/deepgram/cli
Project-URL: Bug Tracker, https://github.com/deepgram/cli/issues
Project-URL: Community, https://discord.gg/deepgram
Keywords: deepgram,speech,recognition,transcription,audio,cli
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: click>=8.0.0
Requires-Dist: deepgram-sdk>=6.0.0rc2
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-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-shared-utils>=0.1.10
Requires-Dist: pydantic>=2.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: httpx>=0.24.0
Requires-Dist: requests<3.0,>=2.31
Requires-Dist: pyjwt>=2.8.0
Requires-Dist: keyring>=24.0.0
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: typer>=0.9.0
Requires-Dist: platformdirs>=3.0.0
Provides-Extra: dev
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: responses>=0.23.0; extra == "dev"
Requires-Dist: ruff>=0.8.0; extra == "dev"
Requires-Dist: mypy>=1.0.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: build>=0.10.0; extra == "dev"

# deepctl

> [!WARNING]  
> **Alpha Software**: This CLI is experimental and under active development.

Official Deepgram CLI. Modular Python package with plugin system.

## Development

### Setup

```bash
git clone https://github.com/deepgram/cli && cd cli
uv sync
```

### Run CLI

```bash
uv run deepctl --help
uv run deepctl login
uv run deepctl transcribe audio.wav
```

### Development Commands

```bash
make dev                   # Format, lint, test
make check                 # Format, lint, typecheck (no tests)
make test                  # Run tests
```

### Requirements

- Python 3.10+
- uv package manager
- Cross-platform: Linux, Windows, macOS

### 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 -->

### Plugin Development

```python
from deepctl_core.base_command import BaseCommand

class MyCommand(BaseCommand):
    name = "mycommand"
    help = "My custom command"

    def handle(self, config, auth_manager, client, **kwargs):
        pass
```

Register your command in `pyproject.toml` under the `deepctl.plugins` entry point group:

```toml
[project.entry-points."deepctl.plugins"]
mycommand = "my_plugin.command:MyCommand"
```

See [`packages/deepctl-plugin-example`](packages/deepctl-plugin-example).

### Testing

- `tests/` - Integration tests
- `packages/*/tests/unit/` - Unit tests
- Runs on Python 3.10-3.14, Linux/Windows/macOS

## Release

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.

## Installation

### Quick Install

**macOS / Linux:**

```bash
curl -fsSL https://deepgram.com/install.sh | sh
```

**Windows (PowerShell):**

```powershell
iwr https://deepgram.com/install.ps1 -useb | iex
```

### Install Options

```bash
# Install a specific version
curl -fsSL https://deepgram.com/install.sh | sh -s -- v0.2.1

# Force reinstall over existing installation
curl -fsSL https://deepgram.com/install.sh | sh -s -- --force

# Both
curl -fsSL https://deepgram.com/install.sh | sh -s -- --force v0.2.1
```

**Windows (PowerShell):**

```powershell
# Install a specific version
$env:DEEPCTL_VERSION='0.2.1'; iwr https://deepgram.com/install.ps1 -useb | iex

# Force reinstall
$env:DEEPCTL_FORCE='1'; iwr https://deepgram.com/install.ps1 -useb | iex
```

### Other Methods

```bash
uv tool install deepctl
pip install deepctl
pipx install deepctl
```

### Try Without Installing

```bash
uv run deepctl --help
pipx run deepctl --help
```

## Usage

### Commands

<!-- BEGIN:commands -->
| Command | Description |
|---------|-------------|
| `deepctl api` | API command for deepctl |
| `deepctl billing` | Billing command for deepctl |
| `deepctl debug audio` | Audio debug subcommand for deepctl |
| `deepctl debug browser` | Browser debug subcommand for deepctl |
| `deepctl debug network` | Network debug subcommand for deepctl |
| `deepctl debug probe` | Debug probe subcommand for deepctl — live ffprobe analysis during streaming |
| `deepctl debug` | Debug command group for deepctl |
| `deepctl ffprobe` | FFprobe configuration command for deepctl |
| `deepctl init` | Init command for deepctl — scaffold Deepgram starter apps |
| `deepctl keys` | API keys management command for deepctl |
| `deepctl listen` | Listen (live speech-to-text) command for deepctl |
| `deepctl login` | Login command for deepctl |
| `deepctl logout` | Login command for deepctl |
| `deepctl mcp` | MCP proxy command for deepctl — connects to Deepgram's developer API |
| `deepctl members` | Members management command for deepctl |
| `deepctl models` | Models command for deepctl |
| `deepctl plugin` | Plugin management command for deepctl |
| `deepctl profiles` | Login command for deepctl |
| `deepctl projects` | Projects command for deepctl |
| `deepctl read` | Read (text intelligence) command for deepctl |
| `deepctl requests` | Requests history command for deepctl |
| `deepctl skills` | AI coding assistant skill management for deepctl |
| `deepctl speak` | Speak (text-to-speech) command for deepctl |
| `deepctl transcribe` | Transcribe command for deepctl |
| `deepctl update` | Update command for deepctl |
| `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

<!-- BEGIN:packages -->
| Package | Description |
|---------|-------------|
| [`deepctl-cmd-api`](packages/deepctl-cmd-api) | API command for deepctl |
| [`deepctl-cmd-billing`](packages/deepctl-cmd-billing) | Billing command for deepctl |
| [`deepctl-cmd-debug`](packages/deepctl-cmd-debug) | Debug command group for deepctl |
| [`deepctl-cmd-debug-audio`](packages/deepctl-cmd-debug-audio) | Audio debug subcommand for deepctl |
| [`deepctl-cmd-debug-browser`](packages/deepctl-cmd-debug-browser) | Browser debug subcommand for deepctl |
| [`deepctl-cmd-debug-network`](packages/deepctl-cmd-debug-network) | Network debug subcommand for deepctl |
| [`deepctl-cmd-debug-probe`](packages/deepctl-cmd-debug-probe) | Debug probe subcommand for deepctl — live ffprobe analysis during streaming |
| [`deepctl-cmd-ffprobe`](packages/deepctl-cmd-ffprobe) | FFprobe configuration command for deepctl |
| [`deepctl-cmd-init`](packages/deepctl-cmd-init) | Init command for deepctl — scaffold Deepgram starter apps |
| [`deepctl-cmd-keys`](packages/deepctl-cmd-keys) | API keys management command for deepctl |
| [`deepctl-cmd-listen`](packages/deepctl-cmd-listen) | Listen (live speech-to-text) command for deepctl |
| [`deepctl-cmd-login`](packages/deepctl-cmd-login) | Login command for deepctl |
| [`deepctl-cmd-mcp`](packages/deepctl-cmd-mcp) | MCP proxy command for deepctl — connects to Deepgram's developer API |
| [`deepctl-cmd-members`](packages/deepctl-cmd-members) | Members management command for deepctl |
| [`deepctl-cmd-models`](packages/deepctl-cmd-models) | Models command for deepctl |
| [`deepctl-cmd-plugin`](packages/deepctl-cmd-plugin) | Plugin management command for deepctl |
| [`deepctl-cmd-projects`](packages/deepctl-cmd-projects) | Projects command for deepctl |
| [`deepctl-cmd-read`](packages/deepctl-cmd-read) | Read (text intelligence) command for deepctl |
| [`deepctl-cmd-requests`](packages/deepctl-cmd-requests) | Requests history command for deepctl |
| [`deepctl-cmd-skills`](packages/deepctl-cmd-skills) | AI coding assistant skill management for deepctl |
| [`deepctl-cmd-speak`](packages/deepctl-cmd-speak) | Speak (text-to-speech) command for deepctl |
| [`deepctl-cmd-transcribe`](packages/deepctl-cmd-transcribe) | Transcribe command for deepctl |
| [`deepctl-cmd-update`](packages/deepctl-cmd-update) | Update command for deepctl |
| [`deepctl-cmd-usage`](packages/deepctl-cmd-usage) | Usage command for deepctl |
| [`deepctl-core`](packages/deepctl-core) | Core components for deepctl |
| [`deepctl-plugin-example`](packages/deepctl-plugin-example) | Example plugin for deepctl |
| [`deepctl-shared-utils`](packages/deepctl-shared-utils) | Shared utilities for deepctl |
<!-- END:packages -->

## Contributing

1. Fork repository
2. Run `make dev` (formats, lints, tests)
3. Add tests for changes
4. Submit pull request

## Links

- [Documentation](https://developers.deepgram.com/docs/cli)
- [Discord](https://discord.gg/deepgram)
- [Issues](https://github.com/deepgram/cli/issues)

## License

MIT
