Skip to content

CLI Reference

The Wiverno CLI provides command-line tools for running and managing Wiverno applications.

Module: wiverno.cli

Overview

The CLI is built with Typer and provides commands for:

  • Running development servers with hot reload
  • Running production servers
  • Serving documentation
  • Getting help and usage information

Installation

The CLI is automatically installed when you install Wiverno:

pip install wiverno

Global Options

All commands support --help to show detailed help:

wiverno --help
wiverno run --help
wiverno run dev --help

Commands

wiverno run dev

Start a development server with automatic hot reload.

Usage:

wiverno run dev [OPTIONS]

Options:

  • --host, -h TEXT - Server host address

  • Default: localhost

  • Example: --host 0.0.0.0 to listen on all interfaces

  • --port, -p INTEGER - Server port number

  • Default: 8000

  • Example: --port 3000 to use port 3000

  • --app-module, -m TEXT - Module containing the WSGI application

  • Default: run

  • Example: --app-module app to load from app.py

  • Example: --app-module myapp.wsgi to load from myapp/wsgi.py

  • --app-name, -a TEXT - Name of the application variable in the module

  • Default: app

  • Example: --app-name application to use variable application

  • --watch, -w TEXT - Comma-separated list of directories to watch

  • Default: Current directory
  • Example: --watch src,templates to watch specific directories

Examples:

# Start development server with defaults
wiverno run dev

# Use custom port
wiverno run dev --port 3000

# Listen on all network interfaces
wiverno run dev --host 0.0.0.0

# Custom app location
wiverno run dev --app-module myapp --app-name application

# Watch specific directories
wiverno run dev --watch src,templates

Features:

  • Automatic restart on file changes (Python, HTML, CSS, JS)
  • Live reload enabled
  • Detailed error messages with tracebacks
  • Graceful shutdown with Ctrl+C

wiverno run prod

Start a production server without automatic restarts.

Usage:

wiverno run prod [OPTIONS]

Options:

  • --host, -h TEXT - Server host address

  • Default: localhost

  • Example: --host 0.0.0.0

  • --port, -p INTEGER - Server port number

  • Default: 8000

  • Example: --port 8080

  • --app-module, -m TEXT - Module containing the WSGI application

  • Default: run

  • --app-name, -a TEXT - Name of the application variable in the module

  • Default: app

Examples:

# Start production server with defaults
wiverno run prod

# Use custom host and port
wiverno run prod --host 0.0.0.0 --port 8080

# Custom app location
wiverno run prod --app-module myapp --app-name application

Notes:

  • No automatic restarts on file changes
  • No file watching
  • Suitable for deployment environments
  • For better production setup, use external WSGI servers (Gunicorn, uWSGI, Waitress)

wiverno docs

Serve project documentation using MkDocs with live reload.

Usage:

wiverno docs [OPTIONS]

Options:

  • --host, -h TEXT - Documentation server host

  • Default: 127.0.0.1

  • --port, -p INTEGER - Documentation server port

  • Default: 8000

  • --open/--no-open - Open browser automatically

  • Default: --open
  • Use --no-open to prevent automatic browser opening

Examples:

# Serve docs at default address
wiverno docs

# Use custom port
wiverno docs --port 8001

# Don't open browser automatically
wiverno docs --no-open

# Listen on all interfaces
wiverno docs --host 0.0.0.0

Requirements:

  • mkdocs.yml file in project root
  • MkDocs installed: pip install mkdocs-material mkdocstrings[python]

Features:

  • Live reload on documentation changes
  • Automatic browser opening
  • Built on MkDocs with Material theme

wiverno start

Quick start command (placeholder for future features).

Usage:

wiverno start

Status: Currently a placeholder. Future versions will include:

  • Project scaffolding
  • Template generation
  • Configuration wizard

wiverno help

Show comprehensive help with available commands and examples.

Usage:

wiverno help

Displays:

  • Overview of Wiverno
  • List of available commands
  • Usage examples for common tasks
  • Documentation links

Common Workflows

Basic Development Setup

  1. Create your application file run.py:
from wiverno.main import Wiverno

app = Wiverno()

@app.get("/")
def home(request):
    return "Hello, World!"
  1. Start development server:
wiverno run dev
  1. Visit http://localhost:8000

Custom Project Structure

For a project with custom structure:

  1. Application in myapp/wsgi.py:
from wiverno.main import Wiverno

app = Wiverno()

@app.get("/")
def home(request):
    return "Hello"
  1. Run with custom module path:
wiverno run dev --app-module myapp.wsgi

Multiple Directories

To watch multiple directories for changes:

wiverno run dev --watch src,templates,static

Production Deployment

For production, use external WSGI servers:

# Create production app file
cat > production.py << 'EOF'
from app import app
EOF

# Run with Gunicorn
gunicorn production:app --bind 0.0.0.0:8000

Or use the prod command for testing:

wiverno run prod --host 0.0.0.0 --port 8000

Environment Variables

The CLI respects common environment variables:

# Set Python path
export PYTHONPATH=/path/to/project

# Run with custom Python path
wiverno run dev

Exit Codes

  • 0 - Success
  • 1 - Error (missing module, configuration error, etc.)

Troubleshooting

Module Not Found

Error: ERROR: Module 'app.py' not found in current directory

Solution:

  • Make sure you're in the project root directory
  • Check the module name with -m option
  • Use --app-module to specify correct path

Application Variable Not Found

Error: ERROR: Application 'app' not found in module 'run'

Solution:

  • Ensure your module has the application variable
  • Use --app-name to specify the correct variable name
  • Example: wiverno run dev --app-name application

MkDocs Not Installed

Error: ERROR: MkDocs is not installed

Solution:

pip install mkdocs-material mkdocstrings[python]

Or install all dev dependencies:

uv pip install -e .[dev]

Port Already in Use

Error: Address already in use

Solution:

  • Use a different port: wiverno run dev --port 3000
  • Kill process using the port
  • Wait and retry

See Also