# Freyja ⚡
**No-dependency, zero-configuration CLI tool to build command-line interfaces purely from your code.**
## CHECK OUT https://pypi.org/project/freyja/
Transform your Python classes into powerful command-line applications in seconds! Freyja uses introspection and type annotations to automatically generate professional CLIs with zero configuration required.
**⚠️ Important:** All constructor parameters MUST have default values for CLI generation to work. Parameters without defaults will cause CLI creation to fail.
## Table of Contents
* [🚀 Why Freyja?](#-why-freyja)
* [⚡ Quick Start](#-quick-start)
* [🏗️ Class-based CLI](#️-class-based-cli)
* [Direct Methods Pattern](#direct-methods-pattern)
* [Inner Classes Pattern](#inner-classes-pattern)
* [✨ Key Features](#-key-features)
* [📚 Documentation](#-documentation)
* [🛠️ Development](#️-development)
* [⚙️ Requirements](#️-requirements)
## 🚀 Why Freyja?
**Build CLIs in under 5 minutes!** No configuration files, no complex setup, no learning curve. Just add type annotations to your class methods and Freyja does the rest.
```bash
pip install freyja
# That's it! No dependencies, no configuration needed.
```
**Before Freyja:**
```bash
python script.py --config-file /path/to/config --database-host localhost --database-port 5432 --username admin --password secret --table-name users --action create --data '{"name": "Alice", "email": "alice@example.com"}'
```
**After Freyja:**
```bash
python script.py database create-user --name Alice --email alice@example.com
# Global config handled automatically, clean syntax, built-in help
```
## ⚡ Quick Start
**Step 1:** Install Freyja
```bash
pip install freyja
```
**Step 2:** Create a class with typed methods
```python
from freyja import FreyjaCLI
class Greeter:
"""Simple greeting application."""
def __init__(self, default_name: str = "World"):
"""Initialize greeter with default name."""
self.default_name = default_name
def greet(self, name: str = None, excited: bool = False) -> None:
"""Greet someone by name."""
actual_name = name or self.default_name
greeting = f"Hello, {actual_name}!"
if excited:
greeting += " 🎉"
print(greeting)
```
**Step 3:** Add 3 lines of Freyja code
```python
if __name__ == '__main__':
cli = FreyjaCLI(Greeter, title="My CLI")
cli.run()
```
**Step 4:** Use your new CLI!
```bash
python script.py greet --name Alice --excited
# Output: Hello, Alice! 🎉
python script.py --help
# Automatic help generation with beautiful formatting
```
## 🏗️ Class-based CLI
Freyja transforms your Python classes into powerful CLI applications. Supports two flexible patterns:
### Direct Methods Pattern
Simple and clean - each method becomes a command:
```python
# calculator.py
from freyja import FreyjaCLI
class Calculator:
"""Advanced calculator with memory and history."""
def __init__(self, precision: int = 2, memory_enabled: bool = True):
"""Initialize calculator with global settings."""
self.precision = precision
self.memory = 0 if memory_enabled else None
def add(self, a: float, b: float, store_result: bool = False) -> None:
"""Add two numbers together."""
result = round(a + b, self.precision)
print(f"{a} + {b} = {result}")
if store_result and self.memory is not None:
self.memory = result
print(f"Result stored in memory: {result}")
def multiply(self, a: float, b: float) -> None:
"""Multiply two numbers."""
result = round(a * b, self.precision)
print(f"{a} × {b} = {result}")
if __name__ == '__main__':
cli = FreyjaCLI(Calculator, title="Advanced Calculator")
cli.run()
```
**Usage:**
```bash
python calculator.py --precision 4 add --a 3.14159 --b 2.71828 --store-result
# Output: 3.14159 + 2.71828 = 5.8599
# Result stored in memory: 5.8599
```
### Inner Classes Pattern
Organize complex applications with flat double-dash commands (e.g., `inner-class--method`):
```python
# project_manager.py
from freyja import FreyjaCLI
from pathlib import Path
class ProjectManager:
"""Complete project management suite with organized command structure."""
def __init__(self, config_file: str = "config.json", debug: bool = False):
"""Initialize with global settings."""
self.config_file = config_file
self.debug = debug
class Database:
"""Database operations and management."""
def __init__(self, connection_string: str = "sqlite:///projects.db", timeout: int = 30):
"""Initialize database connection."""
self.connection_string = connection_string
self.timeout = timeout
def migrate(self, version: str = "latest", dry_run: bool = False) -> None:
"""Run database migrations."""
action = "Would run" if dry_run else "Running"
print(f"{action} migration to version: {version}")
print(f"Connection: {self.connection_string}")
def backup(self, output_path: Path, compress: bool = True) -> None:
"""Create database backup."""
compression = "compressed" if compress else "uncompressed"
print(f"Creating {compression} backup at: {output_path}")
class Projects:
"""Project creation and management operations."""
def __init__(self, workspace: str = "./projects", auto_save: bool = True):
"""Initialize project operations."""
self.workspace = workspace
self.auto_save = auto_save
def create(self, name: str, template: str = "basic", description: str = "") -> None:
"""Create a new project from template."""
print(f"Creating project '{name}' using '{template}' template")
print(f"Workspace: {self.workspace}")
print(f"Description: {description}")
print(f"Auto-save: {'enabled' if self.auto_save else 'disabled'}")
def deploy(self, project_name: str, environment: str = "staging", force: bool = False) -> None:
"""Deploy project to specified environment."""
action = "Force deploying" if force else "Deploying"
print(f"{action} {project_name} to {environment}")
if __name__ == '__main__':
cli = FreyjaCLI(ProjectManager, title="Project Management Suite")
cli.run()
```
**Usage:**
```bash
# Global + Sub-global + Command arguments (flat double-dash notation)
python project_manager.py --config-file prod.json --debug \
database--migrate --connection-string postgres://prod --version 2.1.0 --dry-run
# Create new project with custom workspace
python project_manager.py projects--create --workspace /prod/projects --auto-save \
--name "web-app" --template "react" --description "Production web application"
# Deploy with force flag
python project_manager.py projects--deploy --project-name web-app --environment production --force
# Beautiful help shows all commands organized by group
python project_manager.py --help
```
## ✨ Key Features
🚀 **Zero Configuration** - Works out of the box with just type annotations
⚡ **Lightning Fast** - No runtime dependencies, minimal overhead
🎯 **Type Safe** - Automatic validation from your type hints
📚 **Auto Documentation** - Help text generated from your docstrings
🎨 **Beautiful Output** - Professional themes and formatting
🔧 **Flexible Architecture** - Direct methods or inner class patterns
📦 **No Dependencies** - Uses only Python standard library
🌈 **Shell Completion** - Bash, Zsh, Fish, and PowerShell support
✅ **Production Ready** - Battle-tested in enterprise applications
## 📚 Documentation
**[📖 Complete Documentation Hub](docs/README.md)** - Everything you need to master Freyja
### Quick Links
* **[🚀 Getting Started](docs/getting-started/README.md)** - Installation and first steps
* **[👤 User Guide](docs/user-guide/README.md)** - Comprehensive guides for class-based CLI patterns
* **[⚙️ Features](docs/features/README.md)** - Type annotations, themes, completion, and more
* **[📋 Examples & Best Practices](docs/guides/README.md)** - Real-world examples and patterns
* **[❓ FAQ](docs/faq.md)** - Frequently asked questions
* **[🔧 API Reference](docs/reference/README.md)** - Complete API documentation
## 🛠️ Development
**[📖 Development Guide](CLAUDE.md)** - Comprehensive guide for contributors
### Quick Setup
```bash
# Clone and setup
git clone https://github.com/terracoil/freyja.git
cd freyja
# Install Poetry and setup environment
curl -sSL https://install.python-poetry.org | python3 -
./bin/dev-tools setup env
# Run tests and examples
./bin/dev-tools test run
poetry run python examples/cls_example --help
```
### Development Commands
```bash
poetry install # Install dependencies
./bin/dev-tools test run # Run tests with coverage
./bin/dev-tools build lint # Run all linters and formatters
./bin/dev-tools build compile # Build package
./bin/dev-tools build publish # Publish to PyPI (maintainers)
./bin/dev-tools build tag-version # Create version tags
```
## ⚙️ Requirements
* **Python 3.13.5+** (recommended) or Python 3.8+
* **Zero runtime dependencies** - uses only Python standard library
* **Type annotations required** - for automatic CLI generation
* **Docstrings recommended** - for automatic help text generation
---
**Ready to transform your Python code into powerful CLIs?**
```bash
pip install freyja
# Start building amazing command-line tools in minutes! ⚡
```
**[📚 Get Started Now →](docs/getting-started/README.md)**
Raw data
{
"_id": null,
"home_page": "https://github.com/terracoil/modgud",
"name": "freyja",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0.0,>=3.13.7",
"maintainer_email": null,
"keywords": "cli, auto, introspection, argparse, command-line",
"author": "steven.miers@gmail.com",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/96/fe/7d97fd09d0270f9368bd10d6b9853fe5dda6b2e836ee82343888f18fbb36/freyja-1.1.7.tar.gz",
"platform": null,
"description": "\n\n# Freyja \u26a1\n**No-dependency, zero-configuration CLI tool to build command-line interfaces purely from your code.**\n\n## CHECK OUT https://pypi.org/project/freyja/\n\nTransform your Python classes into powerful command-line applications in seconds! Freyja uses introspection and type annotations to automatically generate professional CLIs with zero configuration required.\n\n**\u26a0\ufe0f Important:** All constructor parameters MUST have default values for CLI generation to work. Parameters without defaults will cause CLI creation to fail.\n\n## Table of Contents\n* [\ud83d\ude80 Why Freyja?](#-why-freyja)\n* [\u26a1 Quick Start](#-quick-start)\n* [\ud83c\udfd7\ufe0f Class-based CLI](#\ufe0f-class-based-cli)\n * [Direct Methods Pattern](#direct-methods-pattern)\n * [Inner Classes Pattern](#inner-classes-pattern)\n* [\u2728 Key Features](#-key-features)\n* [\ud83d\udcda Documentation](#-documentation)\n* [\ud83d\udee0\ufe0f Development](#\ufe0f-development)\n* [\u2699\ufe0f Requirements](#\ufe0f-requirements)\n\n## \ud83d\ude80 Why Freyja?\n\n**Build CLIs in under 5 minutes!** No configuration files, no complex setup, no learning curve. Just add type annotations to your class methods and Freyja does the rest.\n\n```bash\npip install freyja\n# That's it! No dependencies, no configuration needed.\n```\n\n**Before Freyja:**\n```bash\npython script.py --config-file /path/to/config --database-host localhost --database-port 5432 --username admin --password secret --table-name users --action create --data '{\"name\": \"Alice\", \"email\": \"alice@example.com\"}'\n```\n\n**After Freyja:**\n```bash\npython script.py database create-user --name Alice --email alice@example.com\n# Global config handled automatically, clean syntax, built-in help\n```\n\n## \u26a1 Quick Start\n\n**Step 1:** Install Freyja\n```bash\npip install freyja\n```\n\n**Step 2:** Create a class with typed methods\n```python\nfrom freyja import FreyjaCLI\n\n\nclass Greeter:\n \"\"\"Simple greeting application.\"\"\"\n\n def __init__(self, default_name: str = \"World\"):\n \"\"\"Initialize greeter with default name.\"\"\"\n self.default_name = default_name\n\n def greet(self, name: str = None, excited: bool = False) -> None:\n \"\"\"Greet someone by name.\"\"\"\n actual_name = name or self.default_name\n greeting = f\"Hello, {actual_name}!\"\n if excited:\n greeting += \" \ud83c\udf89\"\n print(greeting)\n```\n\n**Step 3:** Add 3 lines of Freyja code\n```python\nif __name__ == '__main__':\n cli = FreyjaCLI(Greeter, title=\"My CLI\")\n cli.run()\n```\n\n**Step 4:** Use your new CLI!\n```bash\npython script.py greet --name Alice --excited\n# Output: Hello, Alice! \ud83c\udf89\n\npython script.py --help\n# Automatic help generation with beautiful formatting\n```\n\n\n## \ud83c\udfd7\ufe0f Class-based CLI\n\nFreyja transforms your Python classes into powerful CLI applications. Supports two flexible patterns:\n\n### Direct Methods Pattern\n\nSimple and clean - each method becomes a command:\n\n```python\n# calculator.py\nfrom freyja import FreyjaCLI\n\n\nclass Calculator:\n \"\"\"Advanced calculator with memory and history.\"\"\"\n\n def __init__(self, precision: int = 2, memory_enabled: bool = True):\n \"\"\"Initialize calculator with global settings.\"\"\"\n self.precision = precision\n self.memory = 0 if memory_enabled else None\n\n def add(self, a: float, b: float, store_result: bool = False) -> None:\n \"\"\"Add two numbers together.\"\"\"\n result = round(a + b, self.precision)\n print(f\"{a} + {b} = {result}\")\n \n if store_result and self.memory is not None:\n self.memory = result\n print(f\"Result stored in memory: {result}\")\n\n def multiply(self, a: float, b: float) -> None:\n \"\"\"Multiply two numbers.\"\"\"\n result = round(a * b, self.precision)\n print(f\"{a} \u00d7 {b} = {result}\")\n\n\nif __name__ == '__main__':\n cli = FreyjaCLI(Calculator, title=\"Advanced Calculator\")\n cli.run()\n```\n\n**Usage:**\n```bash\npython calculator.py --precision 4 add --a 3.14159 --b 2.71828 --store-result\n# Output: 3.14159 + 2.71828 = 5.8599\n# Result stored in memory: 5.8599\n```\n\n### Inner Classes Pattern\n\nOrganize complex applications with flat double-dash commands (e.g., `inner-class--method`):\n\n```python\n# project_manager.py\nfrom freyja import FreyjaCLI\nfrom pathlib import Path\n\n\nclass ProjectManager:\n \"\"\"Complete project management suite with organized command structure.\"\"\"\n\n def __init__(self, config_file: str = \"config.json\", debug: bool = False):\n \"\"\"Initialize with global settings.\"\"\"\n self.config_file = config_file\n self.debug = debug\n\n class Database:\n \"\"\"Database operations and management.\"\"\"\n\n def __init__(self, connection_string: str = \"sqlite:///projects.db\", timeout: int = 30):\n \"\"\"Initialize database connection.\"\"\"\n self.connection_string = connection_string\n self.timeout = timeout\n\n def migrate(self, version: str = \"latest\", dry_run: bool = False) -> None:\n \"\"\"Run database migrations.\"\"\"\n action = \"Would run\" if dry_run else \"Running\"\n print(f\"{action} migration to version: {version}\")\n print(f\"Connection: {self.connection_string}\")\n\n def backup(self, output_path: Path, compress: bool = True) -> None:\n \"\"\"Create database backup.\"\"\"\n compression = \"compressed\" if compress else \"uncompressed\"\n print(f\"Creating {compression} backup at: {output_path}\")\n\n class Projects:\n \"\"\"Project creation and management operations.\"\"\"\n\n def __init__(self, workspace: str = \"./projects\", auto_save: bool = True):\n \"\"\"Initialize project operations.\"\"\"\n self.workspace = workspace\n self.auto_save = auto_save\n\n def create(self, name: str, template: str = \"basic\", description: str = \"\") -> None:\n \"\"\"Create a new project from template.\"\"\"\n print(f\"Creating project '{name}' using '{template}' template\")\n print(f\"Workspace: {self.workspace}\")\n print(f\"Description: {description}\")\n print(f\"Auto-save: {'enabled' if self.auto_save else 'disabled'}\")\n\n def deploy(self, project_name: str, environment: str = \"staging\", force: bool = False) -> None:\n \"\"\"Deploy project to specified environment.\"\"\"\n action = \"Force deploying\" if force else \"Deploying\"\n print(f\"{action} {project_name} to {environment}\")\n\n\nif __name__ == '__main__':\n cli = FreyjaCLI(ProjectManager, title=\"Project Management Suite\")\n cli.run()\n```\n\n**Usage:**\n```bash\n# Global + Sub-global + Command arguments (flat double-dash notation)\npython project_manager.py --config-file prod.json --debug \\\n database--migrate --connection-string postgres://prod --version 2.1.0 --dry-run\n\n# Create new project with custom workspace\npython project_manager.py projects--create --workspace /prod/projects --auto-save \\\n --name \"web-app\" --template \"react\" --description \"Production web application\"\n\n# Deploy with force flag\npython project_manager.py projects--deploy --project-name web-app --environment production --force\n\n# Beautiful help shows all commands organized by group\npython project_manager.py --help\n```\n\n## \u2728 Key Features\n\n\ud83d\ude80 **Zero Configuration** - Works out of the box with just type annotations \n\u26a1 **Lightning Fast** - No runtime dependencies, minimal overhead \n\ud83c\udfaf **Type Safe** - Automatic validation from your type hints \n\ud83d\udcda **Auto Documentation** - Help text generated from your docstrings \n\ud83c\udfa8 **Beautiful Output** - Professional themes and formatting \n\ud83d\udd27 **Flexible Architecture** - Direct methods or inner class patterns \n\ud83d\udce6 **No Dependencies** - Uses only Python standard library \n\ud83c\udf08 **Shell Completion** - Bash, Zsh, Fish, and PowerShell support \n\u2705 **Production Ready** - Battle-tested in enterprise applications \n\n## \ud83d\udcda Documentation\n\n**[\ud83d\udcd6 Complete Documentation Hub](docs/README.md)** - Everything you need to master Freyja\n\n### Quick Links\n* **[\ud83d\ude80 Getting Started](docs/getting-started/README.md)** - Installation and first steps\n* **[\ud83d\udc64 User Guide](docs/user-guide/README.md)** - Comprehensive guides for class-based CLI patterns \n* **[\u2699\ufe0f Features](docs/features/README.md)** - Type annotations, themes, completion, and more\n* **[\ud83d\udccb Examples & Best Practices](docs/guides/README.md)** - Real-world examples and patterns\n* **[\u2753 FAQ](docs/faq.md)** - Frequently asked questions\n* **[\ud83d\udd27 API Reference](docs/reference/README.md)** - Complete API documentation\n\n## \ud83d\udee0\ufe0f Development\n\n**[\ud83d\udcd6 Development Guide](CLAUDE.md)** - Comprehensive guide for contributors\n\n### Quick Setup\n\n```bash\n# Clone and setup\ngit clone https://github.com/terracoil/freyja.git\ncd freyja\n\n# Install Poetry and setup environment \ncurl -sSL https://install.python-poetry.org | python3 -\n./bin/dev-tools setup env\n\n# Run tests and examples\n./bin/dev-tools test run\npoetry run python examples/cls_example --help\n```\n\n### Development Commands\n\n```bash\npoetry install # Install dependencies\n./bin/dev-tools test run # Run tests with coverage\n./bin/dev-tools build lint # Run all linters and formatters\n./bin/dev-tools build compile # Build package\n./bin/dev-tools build publish # Publish to PyPI (maintainers)\n./bin/dev-tools build tag-version # Create version tags\n```\n\n## \u2699\ufe0f Requirements\n\n* **Python 3.13.5+** (recommended) or Python 3.8+\n* **Zero runtime dependencies** - uses only Python standard library\n* **Type annotations required** - for automatic CLI generation\n* **Docstrings recommended** - for automatic help text generation\n\n---\n\n**Ready to transform your Python code into powerful CLIs?**\n\n```bash\npip install freyja\n# Start building amazing command-line tools in minutes! \u26a1\n```\n\n**[\ud83d\udcda Get Started Now \u2192](docs/getting-started/README.md)**\n",
"bugtrack_url": null,
"license": null,
"summary": "Python Library that builds a complete CLI given one or more functions using introspection",
"version": "1.1.7",
"project_urls": {
"Documentation": "https://github.com/terracoil/modgud/tree/main/docs",
"Homepage": "https://github.com/terracoil/modgud",
"Repository": "https://github.com/terracoil/modgud"
},
"split_keywords": [
"cli",
" auto",
" introspection",
" argparse",
" command-line"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "86a118bf25c3c298ba104a11852607d230b318dc39ace292994de5050eb8d01b",
"md5": "1375ec84a74b59e5f44e4f6e0b7ec5de",
"sha256": "9b403e1c40eb5d25bde62c467ed3c532039d5d394045eea202dead6b92b5c5e0"
},
"downloads": -1,
"filename": "freyja-1.1.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1375ec84a74b59e5f44e4f6e0b7ec5de",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0.0,>=3.13.7",
"size": 98190,
"upload_time": "2025-11-01T23:26:28",
"upload_time_iso_8601": "2025-11-01T23:26:28.382005Z",
"url": "https://files.pythonhosted.org/packages/86/a1/18bf25c3c298ba104a11852607d230b318dc39ace292994de5050eb8d01b/freyja-1.1.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "96fe7d97fd09d0270f9368bd10d6b9853fe5dda6b2e836ee82343888f18fbb36",
"md5": "74bd9c267cf43e371222c5171c1f08e5",
"sha256": "d567917a532881a4dafd80775974c15038a346a66adf2775355827f6aa16f4a5"
},
"downloads": -1,
"filename": "freyja-1.1.7.tar.gz",
"has_sig": false,
"md5_digest": "74bd9c267cf43e371222c5171c1f08e5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0.0,>=3.13.7",
"size": 79982,
"upload_time": "2025-11-01T23:26:29",
"upload_time_iso_8601": "2025-11-01T23:26:29.644056Z",
"url": "https://files.pythonhosted.org/packages/96/fe/7d97fd09d0270f9368bd10d6b9853fe5dda6b2e836ee82343888f18fbb36/freyja-1.1.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-11-01 23:26:29",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "terracoil",
"github_project": "modgud",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "freyja"
}
JSON
