Command-Line Interface

The openviper command provides project scaffolding and a development server. It is installed automatically with the framework and is the primary entry point for creating new projects, generating app scaffolds, and running the ASGI server.

Management commands (migrations, superuser creation, task workers, etc.) are handled by the viperctl sub-command documented in Core & CLI.

Global options

openviper --version          # print framework version
openviper --help             # list all commands

create-project

Scaffold a new OpenViper project with settings, ASGI entry point, routes, views, templates, and a .gitignore.

openviper create-project myblog

This creates the following layout:

myblog/
├── viperctl.py
├── .gitignore
├── static/
├── templates/
│   └── home.html
├── tests/
│   └── __init__.py
└── myblog/
    ├── __init__.py
    ├── settings.py
    ├── asgi.py
    ├── routes.py
    └── views.py

Arguments:

Argument	Type	Description
`NAME`	string	Required. A valid Python identifier used as the project package name.

Options:

Option	Type	Default	Description
`--directory` / `-d`	string	CWD	Parent directory in which the project folder is created.

Generated files:

File	Purpose
`viperctl.py`	Per-project management CLI entry point (`python viperctl.py <command>`).
`<name>/settings.py`	Frozen dataclass subclassing `Settings` with `DATABASES`, `SECRET_KEY`, and `INSTALLED_APPS` pre-configured.
`<name>/asgi.py`	ASGI application module that bootstraps `OPENVIPER_SETTINGS_MODULE` and creates the `OpenViper` instance.
`<name>/routes.py`	Top-level route definitions wiring admin and root routers.
`<name>/views.py`	Example async views (HTML home page and JSON API index).
`templates/home.html`	Starter Jinja2 template rendered by the home view.
`.gitignore`	Standard Python `.gitignore` (`__pycache__`, `.env`, `db.sqlite3`, etc.).

A cryptographically random SECRET_KEY is generated and embedded in settings.py for development. Set the ``SECRET_KEY`` environment variable to a separate strong value in production.

After scaffolding, start the development server:

cd myblog
python viperctl.py start-server

create-app

Scaffold a new app package inside an existing OpenViper project. Delegates to viperctl create-app (see Core & CLI).

openviper create-app blog

Arguments:

Argument	Type	Description
`NAME`	string	Required. A valid Python identifier used as the app package name.

Options:

Option	Type	Default	Description
`--directory` / `-d`	string	CWD	Target directory containing the project.

run

Run an OpenViper ASGI application with uvicorn.

openviper run app
openviper run app.py
openviper run myproject.asgi:app

The TARGET argument is resolved as follows:

app.py is stripped to app (module import convention).
module:attr syntax selects a specific ASGI callable; the default attribute is app.
The current working directory is added to sys.path so bare module names resolve without installation.

Arguments:

Argument	Type	Description
`TARGET`	string	Required. Module or `module:attr` containing the ASGI application.

Options:

Option	Type	Default	Description
`--host` / `-h`	string	`127.0.0.1`	Bind address.
`--port` / `-p`	int	`8000`	Bind port.
`--reload` / `--no-reload`	flag	`True`	Auto-reload on file changes. When enabled, workers is forced to 1.
`--workers` / `-w`	int	`1`	Number of worker processes (ignored when `--reload` is set).

Examples:

# Development with auto-reload
openviper run app --reload

# Production with 4 workers
openviper run myproject.asgi:app --no-reload --workers 4

# Bind to all interfaces on port 8080
openviper run app --host 0.0.0.0 --port 8080

version

Print the installed OpenViper version.

openviper version

viperctl (sub-command)

Dispatches per-project management commands. Full documentation is in Core & CLI.

There are two ways to run viperctl commands:

1. ``openviper viperctl`` - works from any project directory:

# From inside any project directory, use '.' to target the CWD
openviper viperctl migrate .
openviper viperctl makemigrations .
openviper viperctl console .
openviper viperctl start-server .

# Or specify a module name explicitly
openviper viperctl migrate myproject
openviper viperctl --settings myproject.settings console

2. ``python viperctl.py`` - from a project that has a viperctl.py:

# Generated by 'openviper create-project'
cd myproject
python viperctl.py migrate
python viperctl.py makemigrations
python viperctl.py console
python viperctl.py start-server

Both approaches are equivalent. openviper viperctl auto-discovers the project layout (root-layout or module-organized) from the current working directory, while python viperctl.py uses the settings module configured in the script.

Target resolution for ``openviper viperctl``:

. - auto-detect the project from the current working directory. For root-layout projects (e.g. examples/fx), the CWD itself is the app. For module-organized projects (e.g. examples/ai_moderation_platform), the single Python package subdirectory containing settings.py and models.py/routes.py is detected automatically.
myproject - a dotted module path resolved relative to the CWD.

Supported commands: makemigrations, migrate, console, start-server, start-worker, collectstatic, test, createsuperuser, changepassword.