pritunl-webclient

A modern, fully-typed Python client for interacting with the Pritunl VPN API.

Features

• 🚀 Modern & Async-Ready: Built with httpx for both sync usage
• 🔒 Type-Safe: Fully typed with comprehensive type hints
• ✅ Well-Tested: 100% test coverage with 36+ unit tests
• 🎯 Simple API: Clean, intuitive interface
• 🔄 Auto-Reconnection: Automatic session management and re-authentication
• 📦 Zero Config: Works out of the box with sensible defaults
• 🖥️ CLI Included: pritunl command installed automatically with the package

Installation

Using uv (recommended)

uv add pritunl-webclient

Using pip

pip install pritunl-webclient

From source

git clone https://github.com/digglife/pritunl_webclient.git
cd pritunl_webclient
uv pip install -e .

Quick Start

CLI Usage

After installation a pritunl command is available. Set credentials via environment variables:

export PRITUNL_URL=https://vpn.example.com
export PRITUNL_USERNAME=admin
export PRITUNL_PASSWORD=secret
# Optional: disable TLS verification for self-signed certs
export PRITUNL_VERIFY_TLS=false

Commands

# List all servers (shows id, name, status)
pritunl list

# Start a server by name or id
pritunl start "US East"
pritunl start abc123def

# Stop a server by name or id
pritunl stop "US East"
pritunl stop abc123def

Example output

ID          NAME      STATUS
----------  --------  -------
abc123def   US East   online
def456ghi   EU West   offline

---

Python API Quick Start

from pritunl_webclient import Client

# Create a client instance
client = Client("https://vpn.example.com", verify=False)

# Login
client.login("admin", "password")

# List servers
servers = client.list_servers()
print(servers)

# Start a server
server_id = "ididid"
result = client.start_server(server_id)

# Check server status
status = client.check_server_status(server_id)
print(status)

# Stop a server
client.stop_server(server_id)

# Always close when done
client.close()

Using as a Context Manager

from pritunl_webclient import Client

with Client("https://vpn.example.com", verify=False) as client:
    client.login("admin", "password")
    servers = client.list_servers()
    print(servers)
# Client automatically closes

API Reference

Client

__init__(base_url: str, verify: bool = True, timeout: int = 10, username: Optional[str] = None, password: Optional[str] = None)

Create a new Pritunl client.

Parameters:

• base_url: Base URL of the Pritunl web UI (e.g., https://vpn.example.com)
• verify: Whether to verify TLS certificates. Set to False for self-signed certificates
• timeout: Request timeout in seconds (default: 10)
• username: Optional username for automatic login on first auth requirement
• password: Optional password for automatic login on first auth requirement
• timeout: Request timeout in seconds (default: 10)

login(username: str, password: str) -> None

Authenticate with the Pritunl server.

Parameters:

• username: Admin username
• password: Admin password

Raises:

• AuthenticationError: If login fails

list_servers(page: int = 0) -> List[Dict[str, Any]]

List all servers.

Parameters:

• page: Page number for pagination (default: 0)

Returns:

• List of server dictionaries

Raises:

• NotAuthenticated: If not logged in
• PritunlError: If request fails

start_server(server_id: str, server_obj: Optional[Dict[str, Any]] = None) -> Dict[str, Any]

Start a server.

Parameters:

• server_id: Server ID to start
• server_obj: Optional server object. If not provided, will be fetched automatically

Returns:

• Server response dictionary

Raises:

• NotAuthenticated: If not logged in
• ServerNotFound: If server doesn't exist
• PritunlError: If operation fails

stop_server(server_id: str, server_obj: Optional[Dict[str, Any]] = None) -> Dict[str, Any]

Stop a server.

Parameters:

• server_id: Server ID to stop
• server_obj: Optional server object. If not provided, will be fetched automatically

Returns:

• Server response dictionary

Raises:

• NotAuthenticated: If not logged in
• ServerNotFound: If server doesn't exist
• PritunlError: If operation fails

check_server_status(server_id: str) -> List[Dict[str, Any]]

Check server host status.

Parameters:

• server_id: Server ID to check

Returns:

• List of host status dictionaries

Raises:

• NotAuthenticated: If not logged in
• PritunlError: If request fails

close() -> None

Close the HTTP client connection.

Exceptions

• PritunlError: Base exception for all Pritunl errors
• AuthenticationError: Raised when authentication fails
• NotAuthenticated: Raised when an operation requires authentication
• ServerNotFound: Raised when a server is not found

Development

Setup

# Clone the repository
git clone https://github.com/digglife/pritunl-webclient.git
cd pritunl-webclient

# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create virtual environment and install dependencies
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e ".[dev]"

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=pritunl_webclient

# Run with verbose output
pytest -vv

# Run specific test file
pytest tests/test_client.py

Linting and Type Checking

# Run ruff linter
ruff check src tests

# Run ruff formatter
ruff format src tests

# Run type checker
mypy src

Building

# Build distribution packages
uv build

# This creates:
# - dist/pritunl_webclient-*.whl
# - dist/pritunl_webclient-*.tar.gz

Publishing to PyPI

Package publishing is automated via GitHub Actions and runs when a tag matching v* is pushed.

# Example: release version 0.3.0
git tag v0.3.0
git push origin v0.3.0

Before using automated publishing, configure PyPI Trusted Publishing:

1. In PyPI, add a Trusted Publisher for this repository.
2. Set workflow to .github/workflows/publish.yml.
3. Set environment name to pypi.

The workflow verifies that the tag version matches pyproject.toml before publishing.

Notes

• If your Pritunl server uses a self-signed certificate, set verify=False when creating the client
• The client automatically manages session cookies and CSRF tokens
• Credentials are stored in memory for auto-reconnection on session expiry
• All operations require authentication via login() first

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Built with httpx
• Tested with pytest
• Type hints validated with mypy