Skip to content

Installation

Egregora requires Python 3.12+ and uses uv for package management.

Install uv

First, install uv if you haven't already:

Bash
1
curl -LsSf https://astral.sh/uv/install.sh | sh
PowerShell
1
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Install Egregora

Install directly from the repository using uvx:

Bash
1
uvx --from git+https://github.com/franklinbaldo/egregora egregora --help

This will install and run Egregora without any local installation. Use uvx for all commands:

Bash
1
2
3
4
5
# Initialize a new blog
uvx --from git+https://github.com/franklinbaldo/egregora egregora init my-blog

# Process WhatsApp export
uvx --from git+https://github.com/franklinbaldo/egregora egregora write export.zip

From PyPI

Bash
1
pip install egregora

From Source

For development (works on Windows, Linux, and macOS):

Bash
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
git clone https://github.com/franklinbaldo/egregora.git
cd egregora

# Quick setup (installs dependencies + pre-commit hooks)
python dev_tools/setup_hooks.py

# Or manual setup
uv sync --extra lint --extra test
uv run pre-commit install

# Run tests
uv run pytest tests/

See Contributing Guide for full development setup.

API Key Setup

Egregora uses Google's Gemini API for content generation. Get a free API key at https://ai.google.dev/gemini-api/docs/api-key.

Bash
1
export GOOGLE_API_KEY="your-google-gemini-api-key"
PowerShell
1
$Env:GOOGLE_API_KEY = "your-google-gemini-api-key"

Verify Installation

Test that everything is working:

Bash
1
egregora --version

Optional Dependencies

Documentation

To build the documentation locally:

Bash
1
2
pip install 'egregora[docs]'
mkdocs serve

Linting

For development and code quality:

Bash
1
2
pip install 'egregora[lint]'
ruff check src/

Next Steps