General Use Personal Program Interface
A plugin framework for composing deterministic tools through a unified CLI.
This project is built for my personal use and assistance. You are welcome to fork it for your own purposes, but please note that it is unsupported and provided as-is. Use at your own risk.
This is the minimal viable version that proves the plugin architecture works.
For Users:
# Install as a global CLI tool
uv tool install guppi-cli --from git+https://github.com/samdengler/guppi-cliFor Development:
# Install in editable mode for local development
uv pip install -e .
# Or with pip
pip install -e .# Route commands to tools
guppi <tool> <command> [args...]
# Example with dummy tool
guppi dummy hello world
# Update the guppi CLI itself
guppi update
# Manage skill sources
guppi skills source add guppi-skills https://github.com/samdengler/guppi-skills
guppi skills source add guppi-skills https://github.com/samdengler/guppi-skills/tree/dev # Specific branch
guppi skills source list
guppi skills source init <directory> # Initialize a new skill source
guppi skills source update # Update all sources
guppi skills source update guppi-skills # Update specific source
# Create new tools
guppi tool init <source-dir> <tool-name> # Create a new tool
guppi tool init <source-dir> <tool-name> --template example # Create with example template
# Discover and install tools from sources
guppi tool search # List all available tools
guppi tool install <name> # Install a tool
guppi tool list # List installed tools
guppi tool update # Update all installed tools
guppi tool update <name> # Update specific tool
guppi tool uninstall <name> # Uninstall a toolGUPPI routes commands to tools by:
- Taking the first argument as the tool name
- Looking for an executable named
guppi-<tool> - Passing remaining arguments to that tool
Tools are separate executables that follow the naming convention guppi-<toolname>.
See the guppi-tools repository for available tools.
GUPPI makes it easy to create new tools with the guppi tool init command.
# 1. Initialize a tool source (if you don't have one)
guppi tool source init ~/my-guppi-tools --name my-tools
# 2. Create a new tool
guppi tool init ~/my-guppi-tools my-awesome-tool
# 3. Implement your tool
cd ~/my-guppi-tools/my-awesome-tool
# Edit src/guppi_my_awesome_tool/cli.py
# 4. Install and test
guppi tool install my-awesome-tool --from ~/my-guppi-tools/my-awesome-tool
guppi my-awesome-tool --helpMinimal template (default): Basic structure with a simple hello command
guppi tool init ~/my-tools simple-toolExample template: Extended template with multiple commands and best practices
guppi tool init ~/my-tools feature-tool --template exampleThe guppi tool init command creates a complete Python package:
my-tool/
├── pyproject.toml # Package metadata with [tool.guppi] configuration
├── README.md # Tool documentation
├── .gitignore # Python .gitignore
└── src/
└── guppi_my_tool/
├── __init__.py # Package init with version
└── cli.py # Typer CLI entry point
- Tool names are automatically sanitized (lowercase, hyphens)
- Example: "My Cool Tool" becomes "my-cool-tool"
- Package names use underscores:
guppi_my_cool_tool - Entry points use hyphens:
guppi-my-cool-tool
This is an ultra-lean MVP. Future iterations will add:
- Tool installation management
- Tool registry and discovery
- Configuration system
- Better error handling
- Tool versioning
# Clone the repository
git clone https://github.com/samdengler/guppi-cli.git
cd guppi-cli
# Install in editable mode
uv pip install -e .# Test the CLI
guppi dummy testThis project is inspired by GUPPI from the Bobiverse series.