Control D Sync

A tiny Python script that keeps your Control D Folders in sync with a set of remote block-lists.

What it does

1. Downloads the current JSON block-lists.
2. Deletes any existing folders with the same names.
3. Re-creates the folders and pushes all rules in batches.

Quick start

Obtain Control D API token

1. Log in to your Control D account.
2. Navigate to the "Preferences > API" section.
3. Click the "+" button to create a new API token.
4. Copy the token value.

Obtain Control D profile ID

1. Log in to your Control D account.
2. Open the Profile you want to sync.
3. Copy the profile ID from the URL.

https://controld.com/dashboard/profiles/741861frakbm/filters
                                        ^^^^^^^^^^^^

Configure the script

1. Clone & install

   git clone https://github.com/your-username/ctrld-sync.git
   cd ctrld-sync
   uv sync

2. Configure secrets Create a .env file (or set GitHub secrets) with:

   TOKEN=your_control_d_api_token
   PROFILE=your_profile_id  # or comma-separated list of profile ids (e.g. your_id_1,your_id_2)

   For GitHub Actions, set TOKEN and PROFILE secrets to the raw values (not the full TOKEN=... / PROFILE=... lines).

3. Configure Folders Edit the FOLDER_URLS list in main.py to include the URLs of the JSON block-lists you want to sync.

Note

Currently only Folders with one action are supported. Either "Block" or "Allow" actions are supported.

4. Run locally

   uv run python main.py --dry-run            # plan only, no API calls
   uv run python main.py --profiles your_id   # live run (requires TOKEN)

5. Run in CI The included GitHub Actions workflow (.github/workflows/ci.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

1. Fork this repo.
2. Go to the "Actions" Tab and enable actions.
3. Go to the Repo Settings.
4. Under "Secrets and variables > Actions" create the following secrets like above, under "Repository secrets":
   • TOKEN: your Control D API token
   • PROFILE: your Control D profile ID(s)

Requirements

• Python 3.13+
• uv (for dependency management)