robyn-config

robyn-config is a comprehensive CLI tool designed to bootstrap and manage Robyn applications. It streamlines your development workflow by generating production-ready project structures and automating repetitive tasks, allowing you to focus on building your business logic.

Think of it as the essential companion for your Robyn projects-handling everything from initial setup with best practices to injecting new feature components as your application grows.

📦 Installation

You can simply use Pip for installation.

pip install robyn-config

🤖 AI Agent Skills

robyn-config also supports AI agent skills, which let agents apply reusable project-specific workflows and guidance.

To add the Robyn Config skills pack, run:

npx skills add Lehsqa/robyn-config-skills

🤔 Usage

🚀 Create a Project

To bootstrap a new project with your preferred architecture and ORM, run:

# Create a DDD project with SQLAlchemy (uses uv by default)
robyn-config create my-service --orm sqlalchemy --design ddd ./my-service

# Create an MVC project with Tortoise ORM, locking with poetry
robyn-config create newsletter --orm tortoise --design mvc --package-manager poetry ~/projects/newsletter

# Launch the interactive create UI
robyn-config create -i

Interactive mode defaults destination to . and lets you edit all fields before confirmation. If you pass flags (for example --orm tortoise), those values are prefilled in the form and still editable.

➕ Add Business Logic

Once inside a project, you can easily add new entities (models, routes, repositories, etc.) using the add command. This automatically generates all necessary files and wiring based on your project's architecture.

# Add a 'product' entity to your project
cd my-service
robyn-config add product

This will:

• Generate models/tables.
• Create repositories.
• Setup routes and controllers.
• Register everything in the app configuration.
• Respect your configured paths: add reads injection targets from [tool.robyn-config.add] in pyproject.toml (e.g., domain/operational/presentation paths for DDD or views/repository/urls for MVC). You can customize those paths before running add to steer where new code is written.

🛡️ Add Admin Panel

Add admin panel scaffolding to an existing project:

cd my-service
robyn-config adminpanel

This generates a default superadmin with credentials admin/admin.

You can override the default superadmin credentials when scaffolding:

robyn-config adminpanel -u superadmin -p super-secret-password ./my-service

This will:

• Add an adminpanel module to your project and register it in the application.
• Provide a modern admin UI with Dark/Light themes.
• Auto-discover available project models and show them in the admin navigation.
• Enable CRUD operations for discovered model tables.
• Bootstrap admin authentication with a default superadmin user (configurable via -u/--username and -p/--password).

📊 Add Monitoring

Set up a full observability stack for an existing project:

cd my-service
robyn-config monitoring

This will:

• Add a /metrics endpoint to your Robyn app exposing Prometheus metrics.
• Install prometheus-client into your project dependencies.
• Generate a docker-compose.monitoring.yml that starts Grafana Alloy, Loki, Prometheus, and Grafana.
• Configure Alloy to collect container logs from the app service and scrape the /metrics endpoint every 15 seconds.
• Provision two Grafana dashboards out of the box:
  • Logs — live log stream with search bar and stdout/stderr filter.
  • Metrics — CPU, memory, open file descriptors, GC activity, and process info.

Start the monitoring stack alongside your app:

docker compose up -d
docker compose -f docker-compose.monitoring.yml up -d

Grafana is available at http://localhost:3000 (anonymous admin access enabled by default).

🏃 CLI Options

Usage: robyn-config [OPTIONS] COMMAND [ARGS]...

Options:
  --help  Show this message and exit.

Commands:
  add         Add new business logic to an existing robyn-config project.
  adminpanel  Add admin panel scaffolding to an existing robyn-config project.
  create      Copy the template into destination with specific configurations.
  monitoring  Add observability stack to an existing robyn-config project.

create command options:

• name: Sets the project name used in templated files like pyproject.toml and README.md. Required unless -i is used.
• -i, --interactive: Launch a Textual terminal UI to fill create options interactively.
• --orm: Selects the database layer. Options: sqlalchemy (default), tortoise.
• --design: Toggles between the architecture templates. Options: ddd (default), mvc.
• --package-manager: Choose how dependencies are locked/installed. Options: uv (default), poetry.
• destination: The target directory. Defaults to . (including in interactive mode).

add command options:

• name: The name of the entity/feature to add (e.g., user, order-item).
• project_path: Path to the project root. Defaults to current directory.

adminpanel command options:

• -u, --username: Default superadmin username injected into generated bootstrap code. Defaults to admin.
• -p, --password: Default superadmin password injected into generated bootstrap code. Defaults to admin.
• project_path: Path to the project root. Defaults to current directory.

monitoring command options:

• project_path: Path to the project root. Defaults to current directory.

🐍 Python Version Support

robyn-config is compatible with the following Python versions:

Python >= 3.11

Please make sure you have the correct version of Python installed before starting to use this project.

💡 Features

• Rapid Scaffolding: Instantly generate robust, production-ready Robyn backend projects.
• Integrated Component Management: Use the CLI to inject models, routes, and repositories into your existing architecture, ensuring consistency and best practices.
• Architectural Flexibility: Native support for Domain-Driven Design (DDD) and Model-View-Controller (MVC) patterns.
• ORM Choice: Seamless integration with SQLAlchemy or Tortoise ORM.
• Package Manager choice: Lock/install via uv (default) or poetry, with fresh lock files generated in quiet mode.
• Admin Panel Scaffolding: adminpanel builds an ORM-aware admin module, auto-wires routes, and supports custom superadmin credentials.
• Observability Stack: monitoring injects a /metrics endpoint and provisions Alloy + Loki + Prometheus + Grafana with pre-built dashboards for logs and metrics.
• Resilient operations: create cleans up generated files if it fails; add, adminpanel, and monitoring roll back with a temporary project backup on errors.
• Production Ready: Includes Docker, Docker Compose, and optimized configurations out of the box.
• DevEx: Pre-configured with ruff, pytest, black, and mypy for a superior development experience.
• AI Agent Skills: Installable skills support for AI agents to streamline specialized workflows.

🗒️ How to contribute

🏁 Get started

Feel free to open an issue for any clarifications or suggestions.

⚙️ To Develop Locally

Prerequisites

• Python >= 3.11
• uv (recommended) or pip

Setup

1. Clone the repository:

   git clone https://github.com/Lehsqa/robyn-config.git

2. Setup a virtual environment and install dependencies:

   uv venv && source .venv/bin/activate
   uv pip install -e ".[dev]"

3. Run linters and tests:

   make check

✨ Special thanks

Special thanks to the Robyn team for creating such an amazing framework!