Plugin system
A plugin adds commands to dg. It is a Python package published to PyPI under the deepctl- prefix; dg plugin install fetches it and dg picks up its commands on the next run.
Install a plugin
Homebrew and system installations keep plugins in an isolated environment at ~/.deepctl/plugins/venv; other installations may add them to the CLI environment. For a plugin not yet on PyPI, pass a git URL such as git+https://github.com/<user>/deepctl-plugin-<name>.git.
List installed plugins
Update plugins
Remove a plugin
dg plugin install, update, and remove also refresh installed skills; a skills failure prints a warning on stderr and leaves the command’s exit code unchanged. See Skills.
Find plugins
Plugins are PyPI packages named deepctl-plugin-<name>; search PyPI for the prefix. The reference plugin is deepctl-plugin-example. Install it with dg plugin install deepctl-plugin-example to get dg example. Its source is at packages/deepctl-plugin-example in the CLI repository.
Plugin development
A plugin exposes a BaseCommand class through the deepctl.plugins entry-point group. Copy the example plugin; it shows get_arguments() for options and flags, the requires_auth, requires_project, and ci_friendly attributes, and a handle() method that returns structured data for the output formatter.
Register a plugin
Name the package with the deepctl- prefix, depend on deepctl-core, and add the command to your package’s pyproject.toml:
The entry-point key (mycommand) is the command name dg registers; the value is the import path of your BaseCommand subclass. The example plugin’s pyproject.toml is a complete reference.
Publish to PyPI
- Build the distribution:
python -m buildproduces a wheel and an sdist indist/. - Upload it:
python -m twine upload dist/*. The Python Packaging User Guide covers creating a PyPI account and API token. - Test the install path end to end:
dg plugin install deepctl-plugin-mycommand, thendg mycommand.
Anyone can then install the package by name. Share it in the Developer Spotlight on GitHub Discussions.
Security
- Plugins run with your user permissions
- Plugins have access to your API key
- Only install plugins from trusted sources
- Review plugin code before installing