A tool for adding all Bluesky users with a matching handle to a user list
mackuba.eu
1# Userlist Sync
2
3A small tool written in Ruby for adding all users with handles matching some kind of pattern (e.g. all [*.gov](https://bsky.app/profile/did:plc:oio4hkxaop4ao4wz2pp3f4cr/lists/3lcq5ovmsjn2s)) to a user list on Bluesky.
4
5
6## How to use
7
81) Deploy this repo to some kind of server using a method of your choice (manual `git clone`, Capistrano, etc.).
9
102) Make sure you have a reasonably new version of Ruby installed there. Any recent Linux distribution should have Ruby 3.0 or newer available as a package (as of January 2025, the latest version is 3.4.1, 3.1.x is in security maintenance mode, and 3.0.x is EOL); however, this code should work with 2.6 or 2.7 too, though that's not recommended. You can also install Ruby using tools such as [RVM](https://rvm.io), [asdf](https://asdf-vm.com), [ruby-install](https://github.com/postmodern/ruby-install) or [ruby-build](https://github.com/rbenv/ruby-build).
11
123) `cd` into the project directory and install gem dependencies using `bundle`. You might want to configure it to install the gems into the local directory instead of system-wide, e.g.:
13
14```
15bundle config --local bundle_path ./vendor
16bundle
17```
18
194) Create a `config/auth.yml` file with authentication info for the account that manages the lists. It should look like this (sorry, no OAuth yet):
20
21```
22id: your.handle
23pass: app-pass-word
24```
25
26This file will also be used to keep access tokens (try to delete the tokens from there if something goes wrong and the app can't authenticate).
27
285) Create a second config file `config/config.yml` with options for the list and handles:
29
30```
31jetstream_host: jetstream2.us-east.bsky.network
32handle_patterns:
33 - "*.uk"
34list_key: 3lqwertyuiop
35```
36
37Fields in the config:
38
39- `jetstream_host` - Jetstream server hostname, see [here](https://github.com/bluesky-social/jetstream?tab=readme-ov-file#public-instances)
40- `handle_patterns` - list of one or more handle patterns to look for; the entries are currently not regexps, but just simple patterns with `*` matching one or more characters
41- `list_key` - the *rkey* of the list to which accounts should be added (the last part of the list URL)
42
436) Test if the app works by running:
44
45```
46./run_sync.rb
47```
48
49The app will save some data like current cursor and list of known accounts to `data/data.json` (on first run, it will fetch the initial state of the list first).
50
517) Use something like `systemd` to launch the service automatically and keep it running (you can find a sample systemd service file in the [dist folder](https://github.com/mackuba/userlist_sync/blob/master/dist/userlist_sync.service)).
52
53
54## Credits
55
56Copyright © 2024-25 Kuba Suder ([@mackuba.eu](https://bsky.app/profile/mackuba.eu)).
57
58The code is available under the terms of the [zlib license](https://choosealicense.com/licenses/zlib/) (permissive, similar to MIT).
59
60Bug reports and pull requests are welcome 😎