robyn-config

Downloads PyPI version License Python DeepWiki

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.

Optional infrastructure can be generated alongside the application:

# Add a Redis broker and both supported NoSQL datastores
robyn-config create analytics --broker redis --nosql mongodb,neo4j ./analytics

# Add a Celery worker and its periodic-job scheduler
robyn-config create jobs --worker celery --scheduler ./jobs

# Reuse RabbitMQ for Dramatiq and enable the experimental APScheduler template
robyn-config create events --broker rabbitmq --worker dramatiq --scheduler --worker-exp-mode ./events

The same broker, NoSQL, worker, scheduler, and experimental-mode controls are available as editable fields in interactive mode.

βž• 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.

  • --broker: Add message broker settings, infrastructure templates, and a Docker Compose service. Options: none (default), redis, rabbitmq, kafka.

  • --nosql: Add optional NoSQL datastore templates and Docker Compose services. Supported providers: mongodb, neo4j. Repeat the flag or pass comma-separated values to select both, for example --nosql mongodb,neo4j.

  • --worker: Add a background worker template and queue configuration. Options: none (default), celery, rq, dramatiq, huey. Compatible selected brokers are reused; otherwise the generated worker uses the default Valkey service.

  • --scheduler: Generate periodic-job scheduling for the selected worker. For RQ this adds --with-scheduler unless experimental mode is enabled.

  • --worker-exp-mode: Enable an opt-in worker integration where supported: Celery with Kafka transport, RQ cron with --scheduler, or Dramatiq APScheduler with --scheduler.

  • 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.

  • Broker Scaffolding: Generate ready-to-run Redis, RabbitMQ, or Kafka infrastructure with settings, environment defaults, and Docker Compose services.

  • NoSQL Scaffolding: Select MongoDB, Neo4j, or both and generate provider-specific infrastructure templates and Docker Compose services.

  • Worker Scaffolding: Generate Celery, RQ, Dramatiq, or Huey worker templates with broker-aware queue wiring and optional periodic-job scheduling.

  • 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!