diff --git a/README.md b/README.md index b721fb29..48e5ab84 100644 --- a/README.md +++ b/README.md @@ -40,10 +40,25 @@ https://controld.com/dashboard/profiles/741861frakbm/filters ```bash git clone https://github.com/YOUR_USERNAME/ctrld-sync.git cd ctrld-sync + ``` + +2. **Install dependencies** + + Choose one of the following methods: + + **Using pip (recommended for CI/production):** + ```bash + pip install -r requirements.txt + ``` + + **Using uv (faster for local development):** + ```bash uv sync ``` + + Both methods are fully supported. Our main sync CI workflow uses `pip` for consistency with caching, while other workflows use `uv`; `uv` is generally faster for local development. -2. **Configure secrets** +3. **Configure secrets** Create a `.env` file (or set GitHub secrets) with: ```py TOKEN=your_control_d_api_token @@ -51,7 +66,7 @@ https://controld.com/dashboard/profiles/741861frakbm/filters ``` For GitHub Actions, set `TOKEN` and `PROFILE` secrets to the raw values (not the full `TOKEN=...` / `PROFILE=...` lines). -3. **Configure Folders** +4. **Configure Folders** Edit the `DEFAULT_FOLDER_URLS` list in `main.py` to include the URLs of the JSON block-lists you want to sync. **Example configuration:** @@ -77,20 +92,20 @@ https://controld.com/dashboard/profiles/741861frakbm/filters You can add your own JSON block-list URLs or use command-line arguments: ```bash - uv run python main.py --folder-url https://example.com/my-blocklist.json + python main.py --folder-url https://example.com/my-blocklist.json ``` > [!NOTE] > Currently only Folders with one action are supported. > Either "Block" or "Allow" actions are supported. -4. **Run locally** +5. **Run locally** ```bash - uv run python main.py --dry-run # plan only, no API calls - uv run python main.py --profiles your_id # live run (requires TOKEN) + python main.py --dry-run # plan only, no API calls + python main.py --profiles your_id # live run (requires TOKEN) ``` -5. **Run in CI** +6. **Run in CI** The included GitHub Actions workflow (`.github/workflows/sync.yml`) runs a dry-run daily at 02:00 UTC and on PRs, writes `plan.json`, and uploads it as an artifact for review. ### Configure GitHub Actions @@ -104,7 +119,7 @@ https://controld.com/dashboard/profiles/741861frakbm/filters ## Requirements - Python 3.13+ -- `uv` (for dependency management) +- Runtime dependencies (install with `pip install -r requirements.txt` or `uv sync`) ## Testing