Skip to content

CLI Commands

Complete guide to Wiverno's command-line interface.

Overview

Wiverno provides a powerful CLI for managing your application development, testing, and deployment. All commands are available through the wiverno command.

Quick Reference

wiverno run dev              # Start development server
wiverno run prod             # Start production server
wiverno docs                 # Serve documentation
wiverno help                 # Show help

Server Commands

Development Server

Start a development server with hot reload:

# Basic usage
wiverno run dev

# Custom port
wiverno run dev --port 3000

# Custom host (listen on all 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,lib

Options:

  • --host, -h - Server host address (default: localhost)
  • --port, -p - Server port number (default: 8000)
  • --app-module, -m - Module containing the WSGI app (default: run)
  • --app-name, -a - Name of the app variable (default: app)
  • --watch, -w - Comma-separated directories to watch

Example:

# run.py
from wiverno.main import Wiverno

app = Wiverno()

@app.get("/")
def index(request):
    return "Hello, World!"

Run:

wiverno run dev

The server will automatically reload when you modify Python files.

Production Server

Start a production server without hot reload:

# Basic usage
wiverno run prod

# Custom configuration
wiverno run prod --host 0.0.0.0 --port 8080

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

Options:

  • --host, -h - Server host address (default: localhost)
  • --port, -p - Server port number (default: 8000)
  • --app-module, -m - Module containing the WSGI app (default: run)
  • --app-name, -a - Name of the app variable (default: app)

Note: For production deployment, consider using a production WSGI server like:

  • Gunicorn: gunicorn app:app
  • uWSGI: uwsgi --http :8000 --wsgi-file app.py --callable app
  • Waitress: waitress-serve --port=8000 app:app

Documentation Commands

Serve Documentation

Start a documentation server with live reload:

# Default (opens in browser)
wiverno docs

# Custom port
wiverno docs --port 3000

# Custom host
wiverno docs --host 0.0.0.0

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

Options:

  • --host, -h - Documentation server host (default: 127.0.0.1)
  • --port, -p - Documentation server port (default: 8000)
  • --open/--no-open - Open browser automatically (default: True)

Example:

wiverno docs --port 8001

Opens documentation at http://127.0.0.1:8001

Note: To build or deploy documentation, use the Makefile:

make docs        # Build static documentation
make docs-deploy # Deploy to GitHub Pages

Help Command

Show comprehensive help and usage examples:

wiverno help

Displays:

  • Available commands
  • Command descriptions
  • Usage examples
  • Quick reference

Environment Variables

Configure Wiverno behavior with environment variables:

# Development server
export WIVERNO_HOST=0.0.0.0
export WIVERNO_PORT=5000
export WIVERNO_DEBUG=true

# Documentation
export WIVERNO_DOCS_PORT=8001

Configuration Files

pyproject.toml

Project configuration:

[project]
name = "myapp"
version = "0.1.0"

[project.scripts]
myapp = "myapp.cli:main"

mkdocs.yml

Documentation configuration (required for wiverno docs):

site_name: My Application
theme:
  name: material

nav:
  - Home: index.md
  - Guide: guide.md

Common Workflows

Local Development

# Start development server
wiverno run dev

# In another terminal, serve docs
wiverno docs --port 8001

Building for Production

# Test production mode locally
wiverno run prod

# Build documentation (use Makefile)
make docs

# Deploy everything
make docs-deploy

CI/CD Pipeline

# Install dependencies
uv pip install -e .[dev]

# Run tests
pytest

# Build docs (use Makefile)
make docs

# Deploy (on main branch)
make docs-deploy

Troubleshooting

Module Not Found

ERROR: Module 'run.py' not found in current directory.

Solution: Make sure you're in the project root or specify the correct module:

wiverno run dev --app-module myapp

Application Not Found

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

Solution: Check that your module has the correct variable name:

# run.py
from wiverno.main import Wiverno

app = Wiverno()  # Must match --app-name

Or specify the correct name:

wiverno run dev --app-name application

Port Already in Use

ERROR: Address already in use

Solution: Use a different port:

wiverno run dev --port 3000

MkDocs Not Installed

ERROR: MkDocs is not installed.

Solution: Install documentation dependencies:

uv pip install mkdocs-material mkdocstrings[python]

Or install all dev dependencies:

uv pip install -e .[dev]

mkdocs.yml Not Found

ERROR: mkdocs.yml not found in current directory.

Solution: Create mkdocs.yml in your project root:

site_name: My Project
theme:
  name: material
nav:
  - Home: index.md

Advanced Usage

Custom Module Structure

# For this structure:
# myproject/
#   myapp/
#     __init__.py
#     application.py  # contains 'wsgi_app'

wiverno run dev --app-module myapp.application --app-name wsgi_app

Multiple Applications

# Development app
wiverno run dev --port 8000 --app-name dev_app

# Admin app (in another terminal)
wiverno run dev --port 8001 --app-name admin_app

Docker Integration

FROM python:3.12-slim

WORKDIR /app
COPY . .
RUN pip install .

CMD ["wiverno", "run", "prod", "--host", "0.0.0.0", "--port", "8000"]

Shell Completion

Enable shell completion (future feature):

# Bash
wiverno --install-completion bash

# Zsh
wiverno --install-completion zsh

# PowerShell
wiverno --install-completion powershell

See Also