Skip to content

Setup Locally

Clone, install, and run r10n for repeated use or development. This makes all automation features available persistently on your machine.

Prerequisites

You need uv installed. If you don't have it:

curl -LsSf https://astral.sh/uv/install.sh | sh

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

brew install uv

Verify installation:

uv --version

Installation

Step 1: Clone the Repository

git clone https://github.com/pruthivithejan/r10n.git
cd r10n

Step 2: Install Dependencies

uv sync

This creates a virtual environment and installs all dependencies automatically, including contributor tooling like documentation builders and testing frameworks.

Step 3: Verify Installation

uv run r10n --help

You should see:

Usage: r10n [OPTIONS] COMMAND [ARGS]...

  r10n - Automate repetitive data and workflow tasks

Options:
  --help  Show this message and exit.

Commands:
  fill-pdfs     Fill PDF templates with data
  colors        Convert CSS colors to oklch() format
  contacts      Generate VCF contact cards from phone numbers
  email         Send bulk personalized emails
  images        Optimize and convert images to WebP

Project Structure

After installation, your directory looks like this:

r10n/
├── src/
│   ├── cli.py                    # Main CLI entry point
│   └── automations/              # Automation modules
├── local/                        # Your working directory (gitignored)
│   ├── inputs/                   # Place your input files here
│   │   ├── contacts/
│   │   ├── fill-pdfs/
│   │   ├── images/
│   │   └── email/
│   ├── outputs/                  # Generated files appear here
│   │   ├── contacts/
│   │   ├── fill-pdfs/
│   │   ├── images/
│   │   └── email/
│   └── configs/                  # Configuration files
├── configs/                      # Default config templates
├── docs/                         # Documentation
└── tests/                        # Test suite

Running Automations

Interactive Mode

Run any command without arguments for step-by-step prompts:

uv run r10n contacts

Command Line Mode

Pass all options directly for scripting:

uv run r10n contacts \
  --input local/inputs/contacts/numbers.txt \
  --prefix Customer \
  --output local/outputs/contacts/customers.vcf

Setting Up Your Workspace

Create the Local Folder Structure

mkdir -p local/inputs/contacts
mkdir -p local/inputs/fill-pdfs
mkdir -p local/inputs/images
mkdir -p local/inputs/email
mkdir -p local/outputs/contacts
mkdir -p local/outputs/fill-pdfs
mkdir -p local/outputs/images
mkdir -p local/outputs/email
mkdir -p local/configs

Or run the setup script (if available):

uv run python scripts/setup.py

Example: Contacts Workflow

  1. Create your input file:
cat > local/inputs/contacts/numbers.txt << 'EOF'
# Customer phone numbers
0771234567
0781234567
+94791234567
EOF
  1. Run the automation:
uv run r10n contacts \
  --input local/inputs/contacts/numbers.txt \
  --prefix Customer \
  --output local/outputs/contacts/customers.vcf
  1. Check the output:
ls -la local/outputs/contacts/

Example: Fill PDFs Workflow

  1. Place your template PDF in local/inputs/fill-pdfs/

  2. Create your data file:

cat > local/inputs/fill-pdfs/participants.csv << 'EOF'
name,course,date
John Doe,Web Development,2025-01-15
Jane Smith,Data Science,2025-01-15
EOF
  1. Run the automation:
uv run r10n fill-pdfs \
  --recipients local/inputs/fill-pdfs/participants.csv

Example: Images Workflow

  1. Copy images to process:
cp ~/Desktop/photos/* local/inputs/images/
  1. Run the optimization:
uv run r10n images \
  --input local/inputs/images/ \
  --output local/outputs/images/ \
  --quality 85

Configuration Files

Some automations support configuration files for default settings.

Email Configuration

Create local/configs/email.json:

{
  "smtp_server": "smtp.gmail.com",
  "smtp_port": 587,
  "email": "your-email@gmail.com",
  "password": "your-app-password",
  "subject": "Your Certificate",
  "use_tls": true
}

Images Configuration

Create local/configs/images.json:

Note: The current CLI does not load this file directly. This format is provided for programmatic use or future CLI support.

{
  "input_directory": "local/inputs/images",
  "output_directory": "local/outputs/images",
  "prefix": "img",
  "max_size_mb": 1.0,
  "quality": 85,
  "max_width": 1920,
  "max_height": 1080,
  "convert_to_webp": true,
  "preserve_aspect_ratio": true,
  "auto_orient": true,
  "preserve_filename": false
}

Updating r10n

Pull the latest changes:

cd r10n
git pull
uv sync

If you installed via standalone binary, use:

r10n upgrade

Development Setup

If you want to contribute or modify r10n:

Run Tests

uv run pytest

Run Linting

uv run ruff check src tests

Format Code

uv run black src tests

Pre-commit Hooks

The project uses lefthook for git hooks:

# Install lefthook (if not already installed)
brew install lefthook  # or: npm install -g lefthook

# Enable hooks
lefthook install

Now tests and linting run automatically before each commit.

Troubleshooting

"Command not found: uv"

Install uv:

curl -LsSf https://astral.sh/uv/install.sh | sh

Restart your terminal or run:

source ~/.bashrc  # or ~/.zshrc

"ModuleNotFoundError"

Run uv sync to install dependencies:

uv sync

"Permission denied" on outputs

Make sure the output directory exists and is writable:

mkdir -p local/outputs/contacts
chmod 755 local/outputs/contacts

Tests Failing

Run tests with verbose output to see details:

uv run pytest -v

Next Steps