Installation
Clone the repo, install dependencies with uv, and run your first generation.
Requirements
| Requirement | Version |
|---|---|
| Python | 3.13+ |
| uv | latest |
| GitHub Token | PAT with read:user, public_repo |
macOS extras
For QR code generation, you also need Cairo: brew install cairo. Set DYLD_LIBRARY_PATH=$(brew --prefix cairo)/lib:$DYLD_LIBRARY_PATH before running.
Clone
git clone https://github.com/YOUR_USERNAME/YOUR_USERNAME.git
cd YOUR_USERNAMEThis is a GitHub profile README repo — your username is the repo name. See the Fork & Repurpose guide for full setup.
Install
The project uses optional dependency groups — install only what you need:
uv sync --all-groupsuv run readme dev installuv sync --all-groups installs format, lint, test, and all generation extras in one shot. For CI or minimal setups, use uv sync for core only.
First run
Generate a default config, then run the full pipeline:
uv run readme config generate-default --path config.yamluv run readme config view --path config.yamluv run readme generate banner --config-path config.yamluv run readme generate qr --config-path config.yamluv run readme generate word-cloud \
--config-path config.yaml \
--techs-path .github/assets/topics.md \
--output-path .github/assets/img/wordcloud.svgWord cloud generation requires .github/assets/topics.md to exist. Run the starred CLI first or use the CI workflow to generate it.
Environment variables
| Variable | Required | Purpose |
|---|---|---|
GITHUB_TOKEN | For metrics/art | GitHub API authentication |
LOG_LEVEL | No | Loguru log level (default INFO) |
DEBUG_MODE | No | Enable verbose debug logging |
Set them in your shell or a .env file (python-dotenv is not included — export manually or use direnv).