# deepctl Plugin Example
An example plugin for deepctl demonstrating how to create and distribute custom commands as separate packages.
## Overview
This plugin shows how to extend deepctl with custom commands that can be:
- Developed independently
- Distributed via PyPI
- Installed alongside the CLI
- Discovered automatically at runtime
**Note:** This plugin is NOT a dependency of deepctl. It must be installed separately to demonstrate how the plugin system works for third-party developers. This example plugin is published to PyPI with each deepctl release to ensure the documentation is always testable.
## Installation
### Development Installation
To install the plugin in development mode:
```bash
# From the plugin directory
pip install -e .
# Or using uv
uv pip install -e .
```
### Production Installation
For users who have deepctl installed globally:
```bash
# Recommended: Using pipx (if deepctl was installed with pipx)
pipx install deepctl # If not already installed
pipx inject deepctl deepctl-plugin-example
# Alternative: Using pip (only works in development environments)
pip install deepctl deepctl-plugin-example
```
**Note:** If you installed deepctl with `uv tool install`, plugin installation requires manual workarounds. We recommend using pipx for the best plugin experience.
## Usage
Once installed, the plugin command becomes available in the CLI:
```bash
# Basic usage
deepctl example
# Custom greeting
deepctl example --greeting "Howdy" --name "Partner"
# Show plugin system information
deepctl example --show-info
```
## How It Works
1. **Entry Point Registration**: The plugin registers itself via the `deepctl.plugins` entry point in `pyproject.toml`
2. **Command Discovery**: The CLI's PluginManager discovers the plugin at runtime using `importlib.metadata`
3. **Command Loading**: The plugin's command class is instantiated and added to the CLI
4. **Execution**: When the user runs the command, the plugin's `handle()` method is called
## Creating Your Own Plugin
To create your own deepctl plugin:
1. **Copy this example package** as a starting point
2. **Rename the package** and update metadata in `pyproject.toml`
3. **Implement your command** by modifying the `command.py` file
4. **Define arguments** in the `get_arguments()` method
5. **Implement logic** in the `handle()` method
6. **Test locally** with `pip install -e .`
7. **Publish to PyPI** when ready
8. **Users install it** with `pipx inject deepctl your-plugin-name`
### Key Requirements
- Must inherit from `deepctl_core.BaseCommand`
- Must implement required properties: `name`, `help`
- Must implement `handle()` method
- Must be registered via entry point
### Example Command Structure
```python
from deepctl_core import BaseCommand
class MyCommand(BaseCommand):
name = "mycommand"
help = "Description of my command"
def handle(self, config, auth_manager, client, **kwargs):
# Your command logic here
pass
```
## Development
### Running Tests
```bash
uv run pytest
```
### Building the Package
```bash
python -m build
```
## Plugin Capabilities
Plugins have access to:
- Configuration management via `Config`
- Authentication via `AuthManager`
- Deepgram API client via `DeepgramClient`
- Rich terminal output via `rich`
- Command-line argument parsing via `click`
## License
MIT
Raw data
{
"_id": null,
"home_page": null,
"name": "deepctl-plugin-example",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "Deepgram <devrel@deepgram.com>",
"keywords": "deepgram, cli, plugin, example",
"author": null,
"author_email": "Deepgram <devrel@deepgram.com>",
"download_url": "https://files.pythonhosted.org/packages/e6/d1/0e564182b9165cfec6ba091d3b4a3db9c68335c1cfaef7f73e07faae8af1/deepctl_plugin_example-0.1.8.tar.gz",
"platform": null,
"description": "# deepctl Plugin Example\n\nAn example plugin for deepctl demonstrating how to create and distribute custom commands as separate packages.\n\n## Overview\n\nThis plugin shows how to extend deepctl with custom commands that can be:\n\n- Developed independently\n- Distributed via PyPI\n- Installed alongside the CLI\n- Discovered automatically at runtime\n\n**Note:** This plugin is NOT a dependency of deepctl. It must be installed separately to demonstrate how the plugin system works for third-party developers. This example plugin is published to PyPI with each deepctl release to ensure the documentation is always testable.\n\n## Installation\n\n### Development Installation\n\nTo install the plugin in development mode:\n\n```bash\n# From the plugin directory\npip install -e .\n\n# Or using uv\nuv pip install -e .\n```\n\n### Production Installation\n\nFor users who have deepctl installed globally:\n\n```bash\n# Recommended: Using pipx (if deepctl was installed with pipx)\npipx install deepctl # If not already installed\npipx inject deepctl deepctl-plugin-example\n\n# Alternative: Using pip (only works in development environments)\npip install deepctl deepctl-plugin-example\n```\n\n**Note:** If you installed deepctl with `uv tool install`, plugin installation requires manual workarounds. We recommend using pipx for the best plugin experience.\n\n## Usage\n\nOnce installed, the plugin command becomes available in the CLI:\n\n```bash\n# Basic usage\ndeepctl example\n\n# Custom greeting\ndeepctl example --greeting \"Howdy\" --name \"Partner\"\n\n# Show plugin system information\ndeepctl example --show-info\n```\n\n## How It Works\n\n1. **Entry Point Registration**: The plugin registers itself via the `deepctl.plugins` entry point in `pyproject.toml`\n2. **Command Discovery**: The CLI's PluginManager discovers the plugin at runtime using `importlib.metadata`\n3. **Command Loading**: The plugin's command class is instantiated and added to the CLI\n4. **Execution**: When the user runs the command, the plugin's `handle()` method is called\n\n## Creating Your Own Plugin\n\nTo create your own deepctl plugin:\n\n1. **Copy this example package** as a starting point\n2. **Rename the package** and update metadata in `pyproject.toml`\n3. **Implement your command** by modifying the `command.py` file\n4. **Define arguments** in the `get_arguments()` method\n5. **Implement logic** in the `handle()` method\n6. **Test locally** with `pip install -e .`\n7. **Publish to PyPI** when ready\n8. **Users install it** with `pipx inject deepctl your-plugin-name`\n\n### Key Requirements\n\n- Must inherit from `deepctl_core.BaseCommand`\n- Must implement required properties: `name`, `help`\n- Must implement `handle()` method\n- Must be registered via entry point\n\n### Example Command Structure\n\n```python\nfrom deepctl_core import BaseCommand\n\nclass MyCommand(BaseCommand):\n name = \"mycommand\"\n help = \"Description of my command\"\n\n def handle(self, config, auth_manager, client, **kwargs):\n # Your command logic here\n pass\n```\n\n## Development\n\n### Running Tests\n\n```bash\nuv run pytest\n```\n\n### Building the Package\n\n```bash\npython -m build\n```\n\n## Plugin Capabilities\n\nPlugins have access to:\n\n- Configuration management via `Config`\n- Authentication via `AuthManager`\n- Deepgram API client via `DeepgramClient`\n- Rich terminal output via `rich`\n- Command-line argument parsing via `click`\n\n## License\n\nMIT\n",
"bugtrack_url": null,
"license": null,
"summary": "Example plugin for deepctl",
"version": "0.1.8",
"project_urls": null,
"split_keywords": [
"deepgram",
" cli",
" plugin",
" example"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "bea4d4edb0e9414be125b04a39958acb1d44386107c43f8f9f16dc4df79bb70c",
"md5": "63d8a63747a952df0f92caa0369c5e63",
"sha256": "cf13df918d8ec75ed2aee9964fc91d43bd05929a75d9f1249f9c0f17fb285bdd"
},
"downloads": -1,
"filename": "deepctl_plugin_example-0.1.8-py3-none-any.whl",
"has_sig": false,
"md5_digest": "63d8a63747a952df0f92caa0369c5e63",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 5554,
"upload_time": "2025-07-28T14:49:12",
"upload_time_iso_8601": "2025-07-28T14:49:12.240544Z",
"url": "https://files.pythonhosted.org/packages/be/a4/d4edb0e9414be125b04a39958acb1d44386107c43f8f9f16dc4df79bb70c/deepctl_plugin_example-0.1.8-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "e6d10e564182b9165cfec6ba091d3b4a3db9c68335c1cfaef7f73e07faae8af1",
"md5": "e1c18dfd18482f40150435368c586d93",
"sha256": "34ced25522b98396fa6adfc09cc25133de6d8aaab6c10e66afd96378a486fca9"
},
"downloads": -1,
"filename": "deepctl_plugin_example-0.1.8.tar.gz",
"has_sig": false,
"md5_digest": "e1c18dfd18482f40150435368c586d93",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 4600,
"upload_time": "2025-07-28T14:49:24",
"upload_time_iso_8601": "2025-07-28T14:49:24.580864Z",
"url": "https://files.pythonhosted.org/packages/e6/d1/0e564182b9165cfec6ba091d3b4a3db9c68335c1cfaef7f73e07faae8af1/deepctl_plugin_example-0.1.8.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-28 14:49:24",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "deepctl-plugin-example"
}
JSON