### Project Setup and Initial Checks

Source: https://github.com/deepgram/cli/blob/main/CONTRIBUTING.md

Instructions for forking, cloning, installing dependencies, and running initial checks for development.

```bash
# Fork and clone
git clone https://github.com/YOUR_USERNAME/cli.git
cd cli

# Install dependencies
uv sync --group dev

# Run all checks
make dev          # format + lint + test
make check        # format + lint + typecheck (no tests)
```

--------------------------------

### Deepgram CLI Raw API and MCP Examples

Source: https://github.com/deepgram/cli/blob/main/README.md

Demonstrates how to interact with any Deepgram API endpoint directly and how to start an MCP (Machine Conversation Processing) server for AI editor integrations.

```bash
# Hit any endpoint directly
dg api /v1/projects --jq '.projects[0].name'
```

```bash
# MCP server for AI editors (Claude Code, Cursor, etc.)
dg mcp --transport sse --port 8000
```

--------------------------------

### Manage Deepgram AI Tool Integration

Source: https://github.com/deepgram/cli/blob/main/README.md

Check the status of AI tool detection, run the interactive setup wizard, or install Deepgram skills for all detected tools.

```bash
dg skills status                          # Detect AI tools
dg skills setup                           # Interactive setup wizard
dg skills install --all                   # Install for all detected tools
```

--------------------------------

### Install deepctl using uv

Source: https://github.com/deepgram/cli/blob/main/packages/deepctl-cmd-debug-audio/README.md

Use this command to install the deepctl package with uv.

```bash
uv tool install deepctl
```

--------------------------------

### Install deepctl using uv

Source: https://github.com/deepgram/cli/blob/main/packages/deepctl-cmd-billing/README.md

Install the deepctl package using the uv tool. uv is a fast Python package installer and resolver.

```bash
# Or install with uv
uv tool install deepctl
```

--------------------------------

### Start MCP Server (Stdio Transport)

Source: https://context7.com/deepgram/cli/llms.txt

Starts the MCP server using standard input/output transport, which is the default for editor integration.

```bash
# Start MCP server (stdio transport — default for editor integration)
dg mcp
```

--------------------------------

### Install Deepgram CLI with curl

Source: https://github.com/deepgram/cli/blob/main/README.md

Installs the Deepgram CLI by downloading and executing an installation script using curl.

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

--------------------------------

### Install deepctl using pipx

Source: https://github.com/deepgram/cli/blob/main/packages/deepctl-cmd-debug-audio/README.md

Use this command to install the deepctl package with pipx.

```bash
pipx install deepctl
```

--------------------------------

### Create Astro Project with Minimal Template

Source: https://github.com/deepgram/cli/blob/main/web/README.md

Use this command to initialize a new Astro project using the minimal template. Ensure you have Node.js installed.

```sh
npm create astro@latest -- --template minimal
```

--------------------------------

### Install deepctl using pip

Source: https://github.com/deepgram/cli/blob/main/packages/deepctl-cmd-billing/README.md

Install the deepctl package using pip. This is the standard method for installing Python packages.

```bash
# Install with pip
pip install deepctl
```

--------------------------------

### Start MCP Server for AI Editor Integration

Source: https://github.com/deepgram/cli/blob/main/web/public/llms-full.txt

Start the MCP server for integration with AI editors. Supports different transport protocols like SSE and HTTP.

```bash
dg mcp                               # Start MCP server (stdio transport)
```

```bash
dg mcp --transport sse               # SSE transport
```

```bash
dg mcp --transport streamable-http   # HTTP transport
```

--------------------------------

### Install Deepgram CLI on Windows

Source: https://github.com/deepgram/cli/blob/main/web/public/llms.txt

Installs the Deepgram CLI using PowerShell. Ensure you have PowerShell installed.

```powershell
iwr deepgram.com/install.ps1 | iex
```

--------------------------------

### Configure Shell Completion

Source: https://github.com/deepgram/cli/blob/main/web/public/llms-full.txt

Generate and install shell completion scripts for various shells (bash, zsh, fish). Use `--install` to append to shell profile files.

```bash
dg completion                        # Auto-detect shell
```

```bash
dg completion bash                   # Output bash eval line
```

```bash
dg completion zsh                    # Output zsh eval line
```

```bash
dg completion fish                   # Output fish eval line
```

```bash
dg completion bash --install         # Append to ~/.bashrc
```

```bash
dg completion zsh --install          # Append to ~/.zshrc
```

--------------------------------

### Install Deepgram CLI Plugins

Source: https://github.com/deepgram/cli/blob/main/web/public/llms.txt

Installs community extensions as plugins in an isolated virtual environment.

```bash
dg plugin install <package>
```

--------------------------------

### Initialize Deepgram Starter Apps

Source: https://context7.com/deepgram/cli/llms.txt

Clone and set up Deepgram starter apps from the templates gallery. This command runs prerequisite checks and setup, and can optionally inject your API key.

```bash
# Interactive picker — browse and select templates
dg init

# Search templates by keyword
dg init --search python

# Clone directly by template slug
dg init node-live-transcription

# Clone to a specific directory
dg init node-live-transcription --dir ./my-app

# Clone and run setup automatically
dg init node-live-transcription --install

# Clone without running setup
dg init node-live-transcription --no-install

# List all available templates
dg init --list
dg init --list --search flask

# Agent-mode usage (non-interactive)
dg init node-live-transcription --install --start
```

--------------------------------

### Install deepctl using pip

Source: https://github.com/deepgram/cli/blob/main/packages/deepctl-cmd-debug-audio/README.md

Use this command to install the deepctl package with pip.

```bash
pip install deepctl
```

--------------------------------

### Start MCP Server (SSE Transport)

Source: https://context7.com/deepgram/cli/llms.txt

Starts the MCP server using Server-Sent Events (SSE) transport, suitable for browser or network clients, on a specified port.

```bash
# SSE transport (for browser/network clients)
dg mcp --transport sse --port 8000
```

--------------------------------

### Deepgram CLI Basic Usage Examples

Source: https://github.com/deepgram/cli/blob/main/README.md

Demonstrates fundamental Deepgram CLI commands for authentication, file transcription, text-to-speech, live microphone transcription, and text analysis.

```bash
# Authenticate with Deepgram
dg login
```

```bash
# Transcribe an audio file
dg listen recording.wav
```

```bash
# Text-to-speech
dg speak "Hello from Deepgram" -o hello.mp3
```

```bash
# Live microphone transcription
dg listen --mic
```

```bash
# Analyze text for sentiment and topics
dg read "The product is amazing" --sentiment --topics
```

--------------------------------

### Install deepctl

Source: https://github.com/deepgram/cli/blob/main/packages/deepctl-cmd-init/README.md

Install the deepctl package using various package managers like pip, uv, or pipx. You can also run deepctl commands without a full installation.

```bash
# Install with pip
pip install deepctl
```

```bash
# Or install with uv
uv tool install deepctl
```

```bash
# Or install with pipx
pipx install deepctl
```

```bash
# Or run without installing
uvx deepctl --help
pipx run deepctl --help
```

--------------------------------

### Install Deepgram CLI

Source: https://context7.com/deepgram/cli/llms.txt

Choose an installation method based on your operating system and package manager. Homebrew and curl installers are available for macOS/Linux, while Windows users can use PowerShell. Pip and uv are options for Python environments.

```bash
# Homebrew (macOS/Linux) — also installs ffmpeg and portaudio
brew tap deepgram/tap && brew install deepgram
```

```bash
# curl installer (macOS/Linux)
curl -fsSL https://deepgram.com/install.sh | sh
```

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

```bash
# PyPI
pip install deepctl          # pip
uv tool install deepctl      # uv
pipx install deepctl         # pipx (recommended for plugin support)
```

```bash
# Try without installing
uvx deepctl --help
pipx run deepctl --help
```

--------------------------------

### Manage AI Assistant Skills

Source: https://context7.com/deepgram/cli/llms.txt

Generate and install skill files for AI coding assistants to use Deepgram's CLI and APIs. This includes checking status, setup, installation, updating, listing, and removing skills.

```bash
# Detect installed AI tools and show skill status
dg skills status
# ┌──────────────────────┬──────────┬─────────────────┐
# │ CLI                  │ Detected │ Skills Installed │
# ├──────────────────────┼──────────┼─────────────────┤
# │ Claude Code          │ Yes      │ Yes             │
# │ GitHub Copilot (CLI) │ No       │ No              │
# └──────────────────────┴──────────┴─────────────────┘

# Interactive setup wizard
dg skills setup

# Install for all detected tools without prompting
dg skills install --all

# Install for a specific tool
dg skills install --cli claude-code

# Regenerate after adding plugins or updating the CLI
dg skills update

# List installed skill files and paths
dg skills list

# Remove all skill files
dg skills remove --all

# Remove skills for one tool
dg skills remove --cli claude-code
```

--------------------------------

### Clone and Set Up Deepgram CLI for Development

Source: https://github.com/deepgram/cli/blob/main/README.md

Commands to clone the repository, install development dependencies, and run development tasks like formatting, linting, and testing.

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

```bash
uv sync --group dev
```

```bash
make dev
```

```bash
make check
```

--------------------------------

### Install deepctl using pipx

Source: https://github.com/deepgram/cli/blob/main/packages/deepctl-cmd-billing/README.md

Install the deepctl package using pipx. pipx allows you to install and run Python applications in isolated environments.

```bash
# Or install with pipx
pipx install deepctl
```

--------------------------------

### Conventional Commit Message Examples

Source: https://github.com/deepgram/cli/blob/main/CONTRIBUTING.md

Examples of commit messages following the Conventional Commits specification.

```text
feat(speak): add --speed flag for playback rate
fix(keys): handle expired key gracefully
docs(readme): update installation section
test(models): add filter edge case tests
chore: update dependencies
```

--------------------------------

### Basic Plugin Command Structure

Source: https://github.com/deepgram/cli/blob/main/CONTRIBUTING.md

Example of a basic plugin command class extending `BaseCommand` for Deepgram CLI.

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

--------------------------------

### Run Deepctl Without Installing

Source: https://github.com/deepgram/cli/blob/main/packages/deepctl-cmd-debug-browser/README.md

Execute deepctl commands without a prior installation using uvx or pipx run.

```bash
uvx deepctl --help
pipx run deepctl --help
```

--------------------------------

### Install Deepgram CLI with Homebrew

Source: https://github.com/deepgram/cli/blob/main/README.md

Installs the Deepgram CLI using Homebrew on macOS or Linux. Homebrew automatically installs necessary dependencies like ffmpeg and portaudio.

```bash
brew tap deepgram/tap
brew install deepgram
```

--------------------------------

### Run deepctl without installing using uvx

Source: https://github.com/deepgram/cli/blob/main/packages/deepctl-cmd-debug-audio/README.md

Execute deepctl commands without a prior installation using uvx.

```bash
uvx deepctl --help
```

--------------------------------

### Install Deepgram CLI on macOS/Linux

Source: https://github.com/deepgram/cli/blob/main/web/public/llms.txt

Installs the Deepgram CLI using a curl command. Ensure you have curl installed.

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

--------------------------------

### Start MCP Server with Custom Host and Base URL

Source: https://context7.com/deepgram/cli/llms.txt

Configures the MCP server to listen on a custom host and use a specific base URL for the Deepgram API.

```bash
# Custom host and base URL
dg mcp --transport sse --host 0.0.0.0 --port 9000 \
  --base-url https://api.dx.deepgram.com
```

--------------------------------

### Start MCP Server for AI Coding Assistants

Source: https://github.com/deepgram/cli/blob/main/README.md

Launch the MCP server for connecting Deepgram tools to AI coding assistants. Supports stdio and SSE transports.

```bash
dg mcp                                    # Start MCP server (stdio)
dg mcp --transport sse --port 8000        # SSE transport
```

--------------------------------

### Run deepctl without installing using Uvx

Source: https://github.com/deepgram/cli/blob/main/packages/deepctl-cmd-api/README.md

Execute deepctl commands without a formal installation using uvx.

```bash
# Or run without installing
uvx deepctl --help
```

--------------------------------

### Deepgram CLI Captions Generation

Source: https://github.com/deepgram/cli/blob/main/README.md

Examples for generating WebVTT and SRT caption files from audio or live microphone input, including options for speaker diarization and streaming.

```bash
# Generate a WebVTT file
dg listen keynote.mp3 --webvtt --save-to keynote.vtt
```

```bash
# SRT with speaker labels
dg listen interview.mp3 --srt --diarize --save-to interview.srt
```

```bash
# Stream live captions from the microphone
dg listen --mic --webvtt
```

```bash
# Captions from a video via ffmpeg
ffmpeg -i video.mp4 -f s16le -ar 16000 -ac 1 - \
  | dg listen --encoding linear16 --srt
```

--------------------------------

### Deepgram Login or API Key Setup

Source: https://github.com/deepgram/cli/blob/main/packages/deepctl-cmd-mcp/README.md

Log in to Deepgram to store credentials or set the DEEPGRAM_API_KEY environment variable for authentication.

```bash
deepctl login
```

```bash
export DEEPGRAM_API_KEY="your-api-key"
```

--------------------------------

### Run MCP Server with SSE Transport

Source: https://github.com/deepgram/cli/blob/main/packages/deepctl-cmd-mcp/README.md

Start the deepctl mcp server using the SSE transport mode on a specified port.

```bash
deepctl mcp --transport sse --port 8000
```

--------------------------------

### Install Deepgram CLI via Package Managers

Source: https://github.com/deepgram/cli/blob/main/web/public/llms-full.txt

Alternative installation methods for the Deepgram CLI using pip, pipx, uvx, or Homebrew.

```bash
pip install deepctl
```

```bash
pipx install deepctl
```

```bash
uvx deepctl --help
```

```bash
brew install deepgram/tap/deepctl
```

--------------------------------

### List Deepgram Projects and API Keys

Source: https://github.com/deepgram/cli/blob/main/README.md

Use these commands to list your Deepgram projects and API keys. Ensure the 'dg' CLI is installed and configured.

```bash
dg projects --list                        # List projects
dg keys --list                            # List API keys
```

--------------------------------

### Deepgram CLI Account Management Commands

Source: https://github.com/deepgram/cli/blob/main/README.md

Provides examples for common account and project management tasks, including checking authentication status, listing projects, creating API keys, viewing usage, and debugging requests.

```bash
dg whoami                                        # Auth status
```

```bash
dg projects --list                               # List projects
```

```bash
dg keys --create --comment 'ci-pipeline' --dry-run  # Dry-run key creation
```

```bash
dg usage --last-month                            # Usage stats
```

```bash
dg requests --status failed --endpoint listen   # Debug failed requests
```

--------------------------------

### Deepgram CLI Speech-to-Text Examples

Source: https://github.com/deepgram/cli/blob/main/README.md

Covers various speech-to-text transcription scenarios including local files, URLs, piping to jq, live microphone input with interim results, and raw audio streams.

```bash
# File or URL — auto-detected
dg listen keynote.mp3 --diarize --model nova-3
```

```bash
dg listen https://cdn.example.com/podcast.mp3
```

```bash
# Pipe to jq for scripting
dg -o json listen standup.mp3 \
  | jq '.results.channels[0].alternatives[0].transcript'
```

```bash
# Live microphone with interim (partial) results
dg listen --mic --model nova-3 --interim
```

```bash
# Raw audio stream from ffmpeg
ffmpeg -i video.mp4 -f s16le -ar 16000 -ac 1 - \
  | dg listen --encoding linear16
```

--------------------------------

### Run deepctl without installing

Source: https://github.com/deepgram/cli/blob/main/packages/deepctl-cmd-billing/README.md

Execute deepctl commands directly without a formal installation using uvx or pipx run. This is useful for trying out commands or for CI/CD environments.

```bash
# Or run without installing
uvx deepctl --help
pipx run deepctl --help
```

--------------------------------

### Run deepctl without installing using pipx

Source: https://github.com/deepgram/cli/blob/main/packages/deepctl-cmd-debug-audio/README.md

Execute deepctl commands without a prior installation using pipx run.

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

--------------------------------

### Manage Deepgram Plugins

Source: https://github.com/deepgram/cli/blob/main/web/public/llms-full.txt

Commands for installing, listing, updating, removing, and searching for Deepgram plugins. Plugins are installed into an isolated virtual environment.

```bash
dg plugin install deepctl-plugin-example  # Install from PyPI
```

```bash
dg plugin list                            # List installed plugins
```

```bash
dg plugin update deepctl-plugin-example   # Update plugin
```

```bash
dg plugin remove deepctl-plugin-example   # Uninstall
```

```bash
dg plugin search <term>                   # Search registry
```

--------------------------------

### Manage Deepgram CLI Plugins

Source: https://github.com/deepgram/cli/blob/main/README.md

Search for, install, list, and remove plugins to extend the Deepgram CLI's functionality.

```bash
dg plugin search deepctl-               # Find plugins
dg plugin install <package>              # Install
dg plugin list                           # List installed
dg plugin remove <package>              # Remove
```

--------------------------------

### GET Request with jq Filter

Source: https://context7.com/deepgram/cli/llms.txt

Executes a GET request and filters the JSON response using `jq` for specific data extraction.

```bash
# GET with jq filter
dg api /v1/projects --jq '.projects[0].name'
```

--------------------------------

### Configure Deepgram MCP Server in Editor

Source: https://github.com/deepgram/cli/blob/main/README.md

Add the Deepgram MCP server configuration to your editor's settings. This example uses 'stdio' transport.

```json
{
  "mcpServers": {
    "deepgram": {
      "type": "stdio",
      "command": "dg",
      "args": ["mcp"]
    }
  }
}
```

--------------------------------

### Install Deepgram CLI with Package Managers

Source: https://github.com/deepgram/cli/blob/main/README.md

Installs the Deepgram CLI using various Python package managers like pip, uv, and pipx.

```bash
pip install deepctl
```

```bash
uv tool install deepctl
```

```bash
pipx install deepctl
```

--------------------------------

### Manage Deepgram Projects

Source: https://context7.com/deepgram/cli/llms.txt

List projects and retrieve project IDs. The output can be formatted as JSON for further processing, for example, with `jq`.

```bash
# --- Projects ---
dg projects --list
dg -o json projects --list | jq '.[].project_id'
```

--------------------------------

### Deepgram CLI Text Intelligence Example

Source: https://github.com/deepgram/cli/blob/main/README.md

Analyzes a text file for sentiment, summarization, and topics using the 'dg read' command.

```bash
dg read earnings.txt --sentiment --summarize --topics
```

--------------------------------

### Manage CLI Plugins

Source: https://context7.com/deepgram/cli/llms.txt

Extend the Deepgram CLI with additional commands using PyPI packages. This includes searching, installing, listing, updating, and removing plugins. Plugins use an isolated virtual environment.

```bash
# Search available plugins
dg plugin search
dg plugin search transcribe

# Install a plugin from PyPI
dg plugin install deepctl-plugin-example

# Install specific version
dg plugin install deepctl-plugin-example --version 0.1.8

# Install from git
dg plugin install git+https://github.com/user/deepctl-plugin-foo.git

# List installed plugins
dg plugin list
dg plugin list --verbose    # shows type, commands, environment

# Update a plugin
dg plugin update deepctl-plugin-example

# Remove a plugin
dg plugin remove deepctl-plugin-example
dg plugin remove deepctl-plugin-example --yes   # skip confirmation
```

--------------------------------

### Get Speaker Segments from Audio

Source: https://github.com/deepgram/cli/blob/main/web/public/llms-full.txt

Transcribe an audio file with speaker diarization enabled and use `jq` to filter and format speaker segments.

```bash
# Get all speaker segments
dg listen interview.mp3 --diarize -o json | jq '.results.channels[0].alternatives[0].words[] | select(.speaker) | {speaker, word}'
```

--------------------------------

### Initialize WebSocket and Logging

Source: https://github.com/deepgram/cli/blob/main/packages/deepctl-cmd-debug-browser/src/deepctl_cmd_debug_browser/static/debug.html

Sets up WebSocket URL, initializes variables, and defines a logging function that also sends messages to the WebSocket server.

```javascript
const WS_PORT = window.location.port; const WS_URL = `ws://localhost:${WS_PORT}/ws`; let ws = null; let checkResults = {}; let totalChecks = 0; let completedChecks = 0;
// Log function
function log(message, type = 'info') {
    const logEl = document.getElementById('log');
    const entry = document.createElement('div');
    entry.className = 'log-entry';
    const timestamp = new Date().toLocaleTimeString();
    entry.innerHTML = `<span class="timestamp">[${timestamp}]</span> ${message}`;
    logEl.appendChild(entry);
    logEl.scrollTop = logEl.scrollHeight; // Send to WebSocket
    if (ws && ws.readyState === WebSocket.OPEN) {
        ws.send(JSON.stringify({ type: type, message: message, data: {} }));
    }
}
```

--------------------------------

### View Deepgram Usage and Billing

Source: https://github.com/deepgram/cli/blob/main/web/public/llms-full.txt

Commands to retrieve usage summaries and account billing information. Specify a date range for usage with `--start` and `--end`.

```bash
dg usage                             # Usage summary
```

```bash
dg usage --start 2024-01-01 --end 2024-01-31
```

```bash
dg billing                           # Account balance
```

```bash
dg requests                          # Recent API requests
```

--------------------------------

### List All API Keys

Source: https://context7.com/deepgram/cli/llms.txt

Lists all available API keys for the current project. The --list flag is optional as it's the default behavior.

```bash
# List all keys
dg keys
dg keys --list
```

--------------------------------

### Alternative MCP Server Configuration for Local Development

Source: https://github.com/deepgram/cli/blob/main/packages/deepctl-cmd-mcp/README.md

Configure the MCP server for local development using uv run.

```json
{
  "command": "uv",
  "args": ["run", "dg", "mcp"]
}
```

--------------------------------

### Scaffold New Projects with Deepgram Templates

Source: https://github.com/deepgram/cli/blob/main/README.md

Browse available project templates and clone/set up a new project using a specified template.

```bash
dg init --list                            # Browse templates
dg init node-live-transcription           # Clone and set up
```

--------------------------------

### Live ffprobe Analysis During Streaming

Source: https://context7.com/deepgram/cli/llms.txt

Perform live ffprobe analysis during streaming for debugging purposes by specifying a port.

```bash
# Live ffprobe analysis during streaming (debug probe)
dg debug probe --port 3100
```

--------------------------------

### Dry-Run API Key Creation

Source: https://context7.com/deepgram/cli/llms.txt

Simulates the creation of an API key without actually making changes, useful for verification.

```bash
# Dry-run: show what would happen without making changes
dg keys --create --comment "staging" --dry-run
```

--------------------------------

### Plugin Registration in pyproject.toml

Source: https://github.com/deepgram/cli/blob/main/CONTRIBUTING.md

Configuration snippet for registering a custom plugin via entry points in `pyproject.toml`.

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

--------------------------------

### Alternative MCP Server Configuration using pipx

Source: https://github.com/deepgram/cli/blob/main/packages/deepctl-cmd-mcp/README.md

Use pipx run instead of uvx for MCP server configuration in editor settings.

```json
{
  "command": "pipx",
  "args": ["run", "deepctl", "mcp"]
}
```

--------------------------------

### POST Request with Binary File Body

Source: https://context7.com/deepgram/cli/llms.txt

Sends a POST request with a binary file (e.g., audio) as the request body using the --input flag.

```bash
# Send binary file as request body
dg api /v1/listen -X POST --input audio.wav
```

--------------------------------

### GET Request with Deepgram API

Source: https://context7.com/deepgram/cli/llms.txt

Performs a GET request to a specified Deepgram REST API endpoint. Credentials are automatically included.

```bash
# GET request
dg api /v1/projects
```

--------------------------------

### Manage Deepgram API Keys

Source: https://github.com/deepgram/cli/blob/main/web/public/llms-full.txt

Commands for listing, creating, showing, and deleting API keys. Use `--create` with `--comment` or `--ttl` for specific key configurations. Deletion can be confirmed or skipped with `--yes`, and previewed with `--dry-run`.

```bash
dg keys                              # List all API keys
```

```bash
dg keys --create --comment "CI key" --scopes member
```

```bash
dg keys --create --ttl 86400         # 24-hour key
```

```bash
dg keys --show KEY_ID                # Show key details
```

```bash
dg keys --delete KEY_ID              # Delete a key (prompts for confirmation)
```

```bash
dg keys --delete KEY_ID --yes        # Skip confirmation
```

```bash
dg keys --delete KEY_ID --dry-run    # Preview without deleting
```

--------------------------------

### Stream Microphone Input and Log Transcripts

Source: https://github.com/deepgram/cli/blob/main/web/public/llms-full.txt

Stream audio from your microphone in real-time, log all transcripts to a file using `tee`, and view them in JSON format.

```bash
# Stream mic and log all transcripts
dg listen --mic -o json | tee transcripts.jsonl
```

--------------------------------

### Generate Captions with `dg listen`

Source: https://context7.com/deepgram/cli/llms.txt

Generate WebVTT or SRT caption files from audio or live microphone input. Supports speaker labels when diarization is enabled.

```bash
# Generate a WebVTT file
dg listen keynote.mp3 --webvtt --save-to keynote.vtt
```

```bash
# SRT with speaker labels
dg listen interview.mp3 --srt --diarize --save-to interview.srt
```

```bash
# Stream live captions from microphone
dg listen --mic --webvtt
```

```bash
# Captions from a video file via ffmpeg
ffmpeg -i video.mp4 -f s16le -ar 16000 -ac 1 - \
  | dg listen --encoding linear16 --srt
```

--------------------------------

### Show Specific API Key Details

Source: https://context7.com/deepgram/cli/llms.txt

Displays detailed information for a specific API key using its ID.

```bash
# Show details for a specific key
dg keys --show KEY_ID_XXXX
```

--------------------------------

### Create API Key with Expiration and Tags

Source: https://context7.com/deepgram/cli/llms.txt

Creates a new API key with an expiration date and associated tags for organization.

```bash
# Create with expiration and tags
dg keys --create --comment "temp" \
  --scopes member \
  --expiration-date 2025-12-31 \
  --tags "ci,automation"
```

--------------------------------

### Override Telemetry Destination

Source: https://github.com/deepgram/cli/blob/main/README.md

Set a custom DSN for telemetry, for example, to point to a self-hosted Sentry instance. The `DEEPCTL_TELEMETRY_DISABLED` environment variable will always take precedence.

```bash
export DEEPCTL_TELEMETRY_DSN='https://<key>@<your-sentry>/<project>'
```

--------------------------------

### Astro Project Structure Overview

Source: https://github.com/deepgram/cli/blob/main/web/README.md

This text-based representation shows the typical file and folder structure of an Astro project. Key directories include `public/` for static assets and `src/pages/` for route definitions.

```text
/
├── public/
├── src/
│   └── pages/
│       └── index.astro
└── package.json
```

--------------------------------

### Run Field Support Toolkit Scripts

Source: https://context7.com/deepgram/cli/llms.txt

Execute field support toolkit scripts using the `dg debug toolkit` command.

```bash
# Run field support toolkit scripts
dg debug toolkit
```

--------------------------------

### Specify Project for API Key Management

Source: https://context7.com/deepgram/cli/llms.txt

Manages API keys for a specific project by providing the project ID.

```bash
# Specify project explicitly
dg keys --list --project-id proj_XXXX
```

--------------------------------

### Deepgram CLI MCP Server Mode

Source: https://github.com/deepgram/cli/blob/main/web/public/llms.txt

Starts the Deepgram CLI in MCP (Media Control Protocol) server mode for AI editor integration. Supports stdio, SSE, and HTTP communication.

```bash
dg mcp
```

--------------------------------

### Scaffolding a New Command

Source: https://github.com/deepgram/cli/blob/main/CONTRIBUTING.md

Command to quickly scaffold a new CLI command using the provided tool.

```bash
dg new-command
```

--------------------------------

### Live Microphone Transcription (`dg listen --mic`)

Source: https://context7.com/deepgram/cli/llms.txt

Perform real-time speech-to-text directly from your microphone. Supports interim results for live feedback and speaker diarization.

```bash
# Live transcription with interim (partial) results
dg listen --mic --model nova-3 --interim
```

```bash
# Live microphone with speaker labels
dg listen --mic --diarize
```

```bash
# Save live session to file
dg listen --mic --save-to live-session.txt
```

--------------------------------

### Login to Deepgram CLI (Browser-based)

Source: https://github.com/deepgram/cli/blob/main/web/public/llms-full.txt

Initiates a browser-based OIDC device flow for authentication. Credentials are securely stored in the system keyring.

```bash
dg login
```

--------------------------------

### Live Streaming STT from Microphone

Source: https://github.com/deepgram/cli/blob/main/web/public/llms-full.txt

Perform real-time speech-to-text using microphone input. Options include specifying models, language, and showing interim results.

```bash
dg listen --mic
```

```bash
dg listen --mic --model nova-3 --language en-US
```

```bash
dg listen --mic --interim
```

--------------------------------

### Debug Browser WebSocket Capabilities

Source: https://context7.com/deepgram/cli/llms.txt

Debug browser WebSocket capabilities using the `dg debug browser` command.

```bash
# Debug browser WebSocket capabilities
dg debug browser
```

--------------------------------

### Deepgram CLI Text-to-Speech Features

Source: https://github.com/deepgram/cli/blob/main/README.md

Illustrates text-to-speech conversion, including saving to file, specifying voice models, and piping output to an audio player.

```bash
dg speak "Welcome to Deepgram" -o welcome.mp3
```

```bash
dg speak --file script.txt -o output.mp3 -m aura-2-luna-en
```

```bash
echo "Hello" | dg speak -o greeting.mp3
```

```bash
dg speak "Stream me" | ffplay -nodisp -    # pipe to audio player
```

--------------------------------

### JSON Output for API Key Scripting

Source: https://context7.com/deepgram/cli/llms.txt

Retrieves API key information in JSON format and filters it using `jq` for scripting purposes.

```bash
# JSON output for scripting
dg -o json keys --list | jq '.[].key_id'
```

--------------------------------

### Transcribe Audio Files and URLs (`dg listen`)

Source: https://context7.com/deepgram/cli/llms.txt

Transcribe pre-recorded audio files or URLs using various models and features like diarization, summarization, and topic detection. Output can be saved to a file or piped for further processing.

```bash
# Transcribe a local file (nova-3, smart formatting on by default)
dg listen meeting.wav
```

```bash
# With diarization, summary, topics, and custom model
dg listen interview.mp3 --diarize --summarize --topics --model nova-3
```

```bash
# URL source — auto-detected
dg listen https://cdn.example.com/podcast.mp3 --language es-ES
```

```bash
# Save transcript to file
dg listen keynote.mp3 --save-to keynote.txt
```

```bash
# Run ffprobe analysis before transcribing
dg listen recording.wav --probe
```

```bash
# Machine-readable JSON (full Deepgram API response)
dg -o json listen standup.mp3\
  | jq '.results.channels[0].alternatives[0].transcript'
```

--------------------------------

### Text-to-Speech Piped to Audio Player

Source: https://github.com/deepgram/cli/blob/main/web/public/llms-full.txt

Convert text to speech and pipe the output directly to an audio player like `ffplay` for immediate playback.

```bash
# TTS piped to audio player
dg speak "Hello from Deepgram" | ffplay -nodisp -autoexit -
```

--------------------------------

### Transcribe Audio from URL

Source: https://github.com/deepgram/cli/blob/main/web/public/llms-full.txt

Transcribe audio content directly from a URL. Supports specifying models and diarization.

```bash
dg listen https://example.com/audio.mp3
```

```bash
dg listen https://example.com/call.wav --diarize --model nova-3
```

--------------------------------

### Create New API Key

Source: https://context7.com/deepgram/cli/llms.txt

Creates a new API key with an optional comment and specified scopes. The 'member' scope is commonly used.

```bash
# Create a new key
dg keys --create --comment "ci-pipeline" --scopes member
```

--------------------------------

### Live Streaming STT from Stdin/Pipe

Source: https://github.com/deepgram/cli/blob/main/web/public/llms-full.txt

Process audio data piped into the CLI for real-time speech-to-text. Requires specifying encoding and sample rate for raw audio.

```bash
cat audio.raw | dg listen --encoding linear16 --sample-rate 16000
```

```bash
ffmpeg -i audio.mp3 -f s16le -ar 16000 -ac 1 - | dg listen --encoding linear16 --sample-rate 16000
```

--------------------------------

### Astro CLI Commands

Source: https://github.com/deepgram/cli/blob/main/web/README.md

A table listing common commands for managing an Astro project. These commands are run from the project's root directory using npm.

```sh
npm install
```

```sh
npm run dev
```

```sh
npm run build
```

```sh
npm run preview
```

```sh
npm run astro ...
```

```sh
npm run astro -- --help
```

--------------------------------

### Transcribe Raw Audio from Stdin (`dg listen`)

Source: https://context7.com/deepgram/cli/llms.txt

Process raw audio data piped from other applications (like ffmpeg) or directly from stdin. Requires specifying audio encoding and sample rate.

```bash
# Pipe from ffmpeg (video to audio)
ffmpeg -i video.mp4 -f s16le -ar 16000 -ac 1 - \
  | dg listen --encoding linear16
```

```bash
# Explicit stdin
dg listen - < audio.raw --encoding linear16 --sample-rate 16000
```

--------------------------------

### Running Tests with Pytest

Source: https://github.com/deepgram/cli/blob/main/CONTRIBUTING.md

Commands for running unit and integration tests, including specific package tests.

```bash
uv run pytest
uv run pytest packages/deepctl-cmd-speak/tests/ -v
```

--------------------------------

### POST Request with String Fields

Source: https://context7.com/deepgram/cli/llms.txt

Sends a POST request with form-encoded string fields, such as creating a new project.

```bash
# POST with string fields
dg api /v1/projects -X POST -f name="New Project"
```

--------------------------------

### Execute Capability Checks with Visual Feedback

Source: https://github.com/deepgram/cli/blob/main/packages/deepctl-cmd-debug-browser/src/deepctl_cmd_debug_browser/static/debug.html

Iterates through a list of capability checks, executing them with a staggered delay. Updates the UI with the results of each check and logs the outcome. Sends results to the server via WebSocket if connected.

```javascript
checks.forEach(async (check, index) => {
  setTimeout(async () => {
    try {
      const result = await check.check();
      const loaderEl = document.getElementById(`loader-${check.key}`);
      const statusEl = document.getElementById(`status-${check.key}`);
      checkResults[check.key] = {
        name: check.name,
        supported: result,
        version: null,
        details: result ? 'Supported' : 'Not supported',
        required: true
      };
      if (result) {
        loaderEl.className = 'indicator success';
        statusEl.className = 'check-status success';
        statusEl.textContent = '✓ Supported';
        log(`${check.name}: Supported`, 'info');
      } else {
        loaderEl.className = 'indicator error';
        statusEl.className = 'check-status error';
        statusEl.textContent = '✗ Not Supported';
        log(`${check.name}: Not supported`, 'error');
      }
      completedChecks++;
      updateProgress();

      // Send result to server
      if (ws && ws.readyState === WebSocket.OPEN) {
        ws.send(JSON.stringify({
          type: 'capability_check',
          data: {
            capability: check.key,
            result: checkResults[check.key]
          }
        }));
      }

      // Check if all tests are complete
      if (completedChecks === totalChecks) {
        completeDebug();
      }
    } catch (error) {
      log(`Error checking ${check.name}: ${error.message}`, 'error');
      completedChecks++;
      updateProgress();
    }
  }, index * 200); // Stagger checks for visual effect
});
```

--------------------------------

### POST Request with Request Body from File

Source: https://context7.com/deepgram/cli/llms.txt

Sends a POST request where the request body is read from a specified file using the --input flag.

```bash
# Read request body from file
dg api /v1/listen -X POST --input request.json
```

--------------------------------

### Deepgram CLI `listen` Flags Reference

Source: https://context7.com/deepgram/cli/llms.txt

Reference for common flags used with the `dg listen` command, including model selection, language specification, diarization, smart formatting, and output formats.

```bash
# --model / -m        Deepgram model (default: nova-3)
# --language / -l     Language code (default: en-US)
# --diarize           Speaker labels [Speaker 0], [Speaker 1], …
# --smart-format      Numbers, dates, punctuation (default: on)
```

--------------------------------

### Generate Shell Completion Scripts

Source: https://github.com/deepgram/cli/blob/main/web/public/llms.txt

Generates shell completion scripts for bash, zsh, and fish.

```bash
dg completion bash
```

```bash
dg completion zsh
```

```bash
dg completion fish
```

--------------------------------

### Establish WebSocket Connection

Source: https://github.com/deepgram/cli/blob/main/packages/deepctl-cmd-debug-browser/src/deepctl_cmd_debug_browser/static/debug.html

Connects to the debug server via WebSocket, handling connection events and initiating debug checks upon successful connection.

```javascript
// Connect to WebSocket
function connectWebSocket() {
    log('Connecting to debug server...');
    ws = new WebSocket(WS_URL);
    ws.onopen = () => {
        log('Connected to debug server', 'info');
        document.getElementById('ws-indicator').className = 'indicator success';
        startDebugChecks();
    };
    ws.onerror = (error) => {
        log(`WebSocket error: ${error}`, 'error');
        document.getElementById('ws-indicator').className = 'indicator error';
    };
    ws.onclose = () => {
        log('Disconnected from debug server', 'info');
        document.getElementById('ws-indicator').className = 'indicator error';
    };
}
```

--------------------------------

### CI Authentication with Environment Variables

Source: https://github.com/deepgram/cli/blob/main/README.md

Set environment variables for API key and project ID to authenticate the Deepgram CLI in CI/CD pipelines.

```bash
# CI authentication
export DEEPGRAM_API_KEY="your-key"
export DEEPGRAM_PROJECT_ID="your-project-id"
```

--------------------------------

### Add Shell Completion to Profile

Source: https://github.com/deepgram/cli/blob/main/web/public/llms-full.txt

Manually add shell completion to your shell profile by evaluating the output of `dg completion` with specific environment variables.

```bash
# bash
eval "$(_DG_COMPLETE=bash_source dg)"
```

```bash
# zsh
eval "$(_DG_COMPLETE=zsh_source dg)"
```

```bash
# fish
eval (env _DG_COMPLETE=fish_source dg)
```

--------------------------------

### Manage Deepgram Models

Source: https://github.com/deepgram/cli/blob/main/web/public/llms.txt

Lists the available Deepgram models.

```bash
dg models
```

--------------------------------

### Initialize WebSocket Connection on DOM Load

Source: https://github.com/deepgram/cli/blob/main/packages/deepctl-cmd-debug-browser/src/deepctl_cmd_debug_browser/static/debug.html

Establishes the WebSocket connection when the HTML document is fully loaded and parsed. This ensures that the necessary DOM elements are available before attempting to connect.

```javascript
document.addEventListener('DOMContentLoaded', () => {
  connectWebSocket();
});
```

--------------------------------

### Set Deepgram API Key Environment Variable

Source: https://github.com/deepgram/cli/blob/main/packages/deepctl-cmd-mcp/README.extra.md

Alternatively, set the DEEPGRAM_API_KEY environment variable to authenticate with Deepgram.

```bash
export DEEPGRAM_API_KEY="your-api-key"
```

--------------------------------

### Transcribe Audio and Extract Text with jq

Source: https://github.com/deepgram/cli/blob/main/web/public/llms-full.txt

Use this command to transcribe an audio file and then use `jq` to extract only the transcript text from the JSON output.

```bash
# Transcribe and extract text with jq
dg listen call.mp3 -o json | jq '.results.channels[0].alternatives[0].transcript'
```

--------------------------------

### Transcribe Local Audio Files

Source: https://github.com/deepgram/cli/blob/main/web/public/llms-full.txt

Transcribe audio files from your local system using various models and options like diarization, summarization, and topic detection.

```bash
dg listen recording.wav
```

```bash
dg listen podcast.mp3 --model nova-3
```

```bash
dg listen interview.mp4 --diarize --language en-US
```

```bash
dg listen meeting.wav --summarize --topics
```

```bash
dg listen call.mp3 --output json --save-to transcript.json
```

--------------------------------

### Generate Captions from Audio Files

Source: https://github.com/deepgram/cli/blob/main/web/public/llms-full.txt

Generate captions in WebVTT or SRT format from audio files. Supports diarization and saving to a specified file.

```bash
dg listen recording.wav --webvtt --save-to captions.vtt
```

```bash
dg listen interview.mp3 --srt --diarize --save-to interview.srt
```

--------------------------------

### Full Transcription and Analysis Pipeline

Source: https://context7.com/deepgram/cli/llms.txt

Combine transcription with analysis features like diarization and summarization, then pipe the JSON output to jq for further processing and saving to a file.

```bash
dg -o json listen meeting.mp3 --diarize --summarize \
  | jq '.results' > transcript.json
```

--------------------------------

### Save Text-to-Speech Output to MP3

Source: https://context7.com/deepgram/cli/llms.txt

Converts text to speech and saves the audio to an MP3 file. Specify the output file using the -o flag.

```bash
# Save to MP3
dg speak "Hello from Deepgram" -o hello.mp3
```

--------------------------------

### Claude MCP Server Configuration with Explicit API Key

Source: https://github.com/deepgram/cli/blob/main/packages/deepctl-cmd-mcp/README.md

Configure your project's .mcp.json file to use Deepgram with an explicit API key via stdio transport with uvx.

```json
{
  "mcpServers": {
    "deepgram": {
      "type": "stdio",
      "command": "uvx",
      "args": ["deepctl", "--api-key", "YOUR_KEY", "mcp"]
    }
  }
}
```

--------------------------------

### Cursor MCP Server Configuration

Source: https://github.com/deepgram/cli/blob/main/packages/deepctl-cmd-mcp/README.md

Configure your .cursor/mcp.json file to use Deepgram as an MCP server with uvx.

```json
{
  "mcpServers": {
    "deepgram": {
      "command": "uvx",
      "args": ["deepctl", "mcp"]
    }
  }
}
```

--------------------------------

### Login to Deepgram CLI (API Key)

Source: https://github.com/deepgram/cli/blob/main/web/public/llms-full.txt

Authenticate with the Deepgram CLI using an API key and project ID. Supports specifying different profiles.

```bash
dg login --api-key sk-your-key --project-id your-project-id
```

```bash
dg login --profile staging --api-key sk-staging-key
```

--------------------------------

### Manage Deepgram API Keys

Source: https://github.com/deepgram/cli/blob/main/web/public/llms.txt

Creates, lists, and revokes Deepgram API keys.

```bash
dg keys
```

--------------------------------

### Analyze Audio File Compatibility

Source: https://context7.com/deepgram/cli/llms.txt

Use this command to analyze an audio file's compatibility with Deepgram. It provides details on format, duration, size, bit rate, codec, sample rate, channels, and bit depth.

```bash
# Analyze audio file compatibility with Deepgram
dg debug audio --file recording.wav
```

--------------------------------

### Login to Deepgram CLI

Source: https://github.com/deepgram/cli/blob/main/packages/deepctl-cmd-mcp/README.extra.md

Authenticates with Deepgram using your API key, storing credentials in the system keyring for subsequent commands.

```bash
deepctl login
```

--------------------------------

### Configure Deepgram CLI Profiles

Source: https://github.com/deepgram/cli/blob/main/README.md

Manage Deepgram CLI configurations using named profiles for different environments or API keys. Supports interactive login and explicit profile switching.

```bash
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
```

--------------------------------

### Complete Debug Session and Send Results

Source: https://github.com/deepgram/cli/blob/main/packages/deepctl-cmd-debug-browser/src/deepctl_cmd_debug_browser/static/debug.html

Finalizes the debug session after all capability checks are complete. Determines overall compatibility, sends the final results and user agent to the server via WebSocket, and then closes the connection. Displays a completion message to the user.

```javascript
function completeDebug() {
  log('All capability checks complete!', 'info');
  const overallCompatible = Object.values(checkResults).every(r => r.supported);

  // Send final results
  if (ws && ws.readyState === WebSocket.OPEN) {
    ws.send(JSON.stringify({
      type: 'complete',
      data: {
        capabilities: {
          ...checkResults,
          user_agent: navigator.userAgent,
          overall_compatible: overallCompatible
        }
      }
    }));

    // Close WebSocket after a short delay
    setTimeout(() => {
      ws.close();
    }, 1000);
  }

  // Show completion message
  document.getElementById('complete-message').className = 'complete-message show';
}
```

--------------------------------

### Claude MCP Server Configuration

Source: https://github.com/deepgram/cli/blob/main/packages/deepctl-cmd-mcp/README.md

Configure your project's .mcp.json file to use Deepgram as an MCP server via stdio transport with uvx.

```json
{
  "mcpServers": {
    "deepgram": {
      "type": "stdio",
      "command": "uvx",
      "args": ["deepctl", "mcp"]
    }
  }
}
```

--------------------------------

### WAV Output with Explicit Encoding for TTS

Source: https://context7.com/deepgram/cli/llms.txt

Generates WAV audio output with explicit encoding (linear16) and container format for text-to-speech.

```bash
# WAV output with explicit encoding
dg speak "Hello" -m aura-2-luna-en \
  --encoding linear16 --container wav -o hello.wav
```

--------------------------------

### Text-to-Speech Synthesis with Deepgram CLI

Source: https://github.com/deepgram/cli/blob/main/web/public/llms.txt

Synthesizes speech from text using Deepgram's Aura voices.

```bash
dg speak "<text>"
```

--------------------------------

### Manage Deepgram CLI Profiles

Source: https://github.com/deepgram/cli/blob/main/web/public/llms-full.txt

Commands to list, switch, and view details of Deepgram CLI profiles.

```bash
dg profiles --list
```

```bash
dg profiles --switch staging
```

```bash
dg profiles --current
```

--------------------------------

### Deepgram CLI Project Structure

Source: https://github.com/deepgram/cli/blob/main/README.md

An overview of the directory structure for the Deepgram CLI project, detailing the purpose of key directories and packages.

```tree
cli/
├── src/deepctl/                      # Main CLI entry point
├── packages/
│   ├── deepctl-cmd-api/              # API command for deepctl
│   ├── deepctl-cmd-billing/          # Billing command for deepctl
│   ├── deepctl-cmd-completion/       # Shell completion 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-debug-toolkit/    # Toolkit subcommand for dg debug — runs field support scripts from deepgram/support-toolkit
│   ├── 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
│   └── deepctl-telemetry/            # Opt-out phone-home telemetry for deepctl
├── tests/                            # Integration tests
└── Makefile                          # Development tasks

```