mackuba.eu
+100
-73
README.md
+100
-73
README.md
···
1
1
# RatProto – Ruby ATProto Tool 🐀
2
2
3
-
`rat` is a small command-line tool for working with the **Bluesky AT Protocol** from Ruby.
3
+
RatProto (`rat`) is a small command-line tool in Ruby for accessing the Bluesky API / AT Protocol.
4
4
5
5
It builds on top of the existing ATProto Ruby gems:
6
6
7
-
- [`minisky`](https://ruby.sdk.blue/minisky/) — XRPC client for PDS/AppView
8
-
- [`skyfall`](https://ruby.sdk.blue/skyfall/) — firehose & Jetstream streaming
9
-
- [`didkit`](https://ruby.sdk.blue/didkit/) — DID & handle resolution
7
+
- [`minisky`](https://tangled.org/mackuba.eu/minisky/) — XRPC client
8
+
- [`skyfall`](https://tangled.org/mackuba.eu/skyfall/) — firehose & Jetstream streaming
9
+
- [`didkit`](https://tangled.org/mackuba.eu/didkit/) — DID & handle resolution
10
10
11
-
You can use `rat` to:
11
+
> [!NOTE]
12
+
> Part of ATProto Ruby SDK: [ruby.sdk.blue](https://ruby.sdk.blue)
12
13
13
-
- fetch AT Protocol records
14
-
- stream firehose / Jetstream commits with optional filters
15
-
- resolve DIDs & handles
16
14
15
+
## Installation
17
16
18
-
> [!CAUTION]
19
-
> Here be dragons - currently 100% vibe-coded using ChatGPT. Seems to be working correctly. Will be rewritten manually in the next version :)
17
+
To run this tool, you need some reasonably recent version of Ruby installed – it should run on Ruby 2.6 and above, although it's recommended to use a version that still gets maintainance updates, i.e. currently 3.2+.
20
18
19
+
An older version of Ruby (2.6.x) that should work is shipped with macOS versions 11.0 or later, a recent version of Ruby is also likely to be already installed on most Linux systems, or at least available through the OS's package manager. More installation options can be found on [ruby-lang.org](https://www.ruby-lang.org/en/downloads/).
21
20
22
-
## Installation
21
+
To install `rat`, run:
23
22
24
23
```
25
-
gem install ratproto
24
+
[sudo] gem install ratproto
26
25
```
27
26
27
+
## Features
28
28
29
-
## Usage
29
+
Currently implemented features/commands:
30
30
31
-
```
32
-
rat fetch at://<did>/<collection>/<rkey>
33
-
rat stream <relay.host> [options]
34
-
rat resolve <did-or-handle>
35
-
```
36
-
31
+
- resolving DIDs & handles (`rat resolve`)
32
+
- fetching & printing ATProto records (`rat fetch`)
33
+
- streaming firehose / Jetstream events with optional filters (`rat stream`)
37
34
38
-
### Fetching a record
39
35
40
-
Use an at:// URI to fetch a record directly from the user’s PDS:
36
+
## Resolving a DID or handle
41
37
42
38
```
43
-
rat fetch at://did:plc:abcd1234/app.bsky.feed.post/3kz4vx5j
39
+
rat resolve <did>|<handle>
44
40
```
45
41
46
-
Example output:
42
+
Pass a DID or a handle (@ optional) to look up the given account's identity & print the DID document:
47
43
48
44
```
45
+
$ rat resolve atproto.com
46
+
49
47
{
50
-
"$type": "app.bsky.feed.post",
51
-
"text": "hello world 👋",
52
-
"createdAt": "2025-01-01T12:34:56.789Z"
48
+
"@context": [
49
+
"https://www.w3.org/ns/did/v1",
50
+
"https://w3id.org/security/multikey/v1",
51
+
"https://w3id.org/security/suites/secp256k1-2019/v1"
52
+
],
53
+
"id": "did:plc:ewvi7nxzyoun6zhxrhs64oiz",
54
+
"alsoKnownAs": [
55
+
"at://atproto.com"
56
+
],
57
+
"verificationMethod": [
58
+
{
59
+
"id": "did:plc:ewvi7nxzyoun6zhxrhs64oiz#atproto",
60
+
"type": "Multikey",
61
+
"controller": "did:plc:ewvi7nxzyoun6zhxrhs64oiz",
62
+
"publicKeyMultibase": "zQ3shunBKsXixLxKtC5qeSG9E4J5RkGN57im31pcTzbNQnm5w"
63
+
}
64
+
],
65
+
"service": [
66
+
{
67
+
"id": "#atproto_pds",
68
+
"type": "AtprotoPersonalDataServer",
69
+
"serviceEndpoint": "https://enoki.us-east.host.bsky.network"
70
+
}
71
+
]
53
72
}
54
73
```
55
74
56
-
### Resolving a DID or handle
57
75
58
-
You can resolve either a DID:
76
+
## Fetching a record
59
77
60
78
```
61
-
rat resolve did:plc:abcd1234
79
+
rat fetch at://<did>/<collection>/<rkey>
62
80
```
63
81
64
-
or a handle:
82
+
Pass an at:// URI as the argument to fetch a single record from the user’s PDS:
65
83
66
84
```
67
-
rat resolve @example.com
85
+
% rat fetch at://did:plc:ragtjsm2j2vknwkz3zp4oxrd/app.bsky.feed.post/3lxxmboqmf22j
86
+
87
+
{
88
+
"text": "a gatinha gorda",
89
+
"$type": "app.bsky.feed.post",
90
+
"embed": {
91
+
"$type": "app.bsky.embed.images",
92
+
"images": [
93
+
{
94
+
"alt": "Kit lying on the ground under the chair ",
95
+
"image": {
96
+
"$type": "blob",
97
+
"ref": {
98
+
"$link": "bafkreiebzsetrrvymvq6dvwma77zqprnv73ovgeqilanzi453dm6xart4q"
99
+
},
100
+
"mimeType": "image/jpeg",
101
+
"size": 963750
102
+
},
103
+
"aspectRatio": {
104
+
"width": 2000,
105
+
"height": 1500
106
+
}
107
+
}
108
+
]
109
+
},
110
+
"langs": [
111
+
"en"
112
+
],
113
+
"createdAt": "2025-09-03T21:48:05.910Z"
114
+
}
68
115
```
69
116
70
-
Example output:
117
+
## Streaming commit events
71
118
72
119
```
73
-
did:plc:abcd1234
74
-
{
75
-
"@context": "...",
76
-
"id": "did:plc:abcd1234",
77
-
...
78
-
}
120
+
rat stream <firehose-host> [-j] [-r cursor] [-c collections] [-d dids]
79
121
```
80
122
81
-
### Streaming commit events
82
-
83
-
Rat can connect to either a relay/PDS firehose, or a Jetstream JSON stream:
123
+
Rat can connect to either a relay/PDS firehose:
84
124
85
125
```
86
126
rat stream bsky.network
87
127
```
88
128
89
-
You’ll see output like:
129
+
or a Jetstream service (use `-j`):
90
130
91
131
```
92
-
[2025-01-02T12:34:56+01:00] did:plc:abcd1234 :create app.bsky.feed.post 3rblblbl {"text":"hi"}
93
-
[2025-01-02T12:34:57+01:00] did:plc:efgh5678 :delete app.bsky.graph.follow 3szxczxc
132
+
rat stream -j jetstream2.us-east.bsky.network
94
133
```
95
134
96
-
Press Ctrl-C to disconnect.
135
+
You can also pass a cursor to connect with using `-r` / `--cursor` (tip: pass `-r0` to rewind as far back as the buffer allows).
97
136
98
-
To use Jetstream, add `--jetstream` or `-j`:
137
+
Once connected, you’ll see output like:
99
138
100
139
```
101
-
rat stream -j jetstream1.us-east.bsky.network
140
+
[2025-01-02T12:34:56+01:00] did:plc:xwnehmdpjluz2kv3oh2mfi47 :create app.bsky.feed.post 3mbjs5rgtin2z {"text":"hi", ...}
141
+
[2025-01-02T12:34:57+01:00] did:plc:3mfkuhmjxd2wvz2e7nhl4poi :delete app.bsky.graph.follow 3mbjs5rghri23
102
142
```
103
143
104
-
#### Filtering by DID and/or collection
144
+
Press Ctrl-C to disconnect.
105
145
106
-
You can filter on DID:
146
+
You can also apply the filtering options below (for Jetstream, these are passed to the server to apply filtering server-side via `wantedCollections` / `wantedDids` parameters):
107
147
108
-
```
109
-
rat stream jetstream1.us-east.bsky.network \
110
-
--jetstream \
111
-
--did did:plc:abcd1234,did:plc:wxyz9999
112
-
```
113
148
114
-
Or collection:
149
+
### Filtering by DID
150
+
151
+
To print only events from given DID(s):
115
152
116
153
```
117
-
rat stream jetstream1.us-east.bsky.network \
118
-
--jetstream \
119
-
--collection app.bsky.feed.post
154
+
rat stream bsky.network -d did:plc:abcd1234,did:plc:xyz9999,...
120
155
```
121
156
122
-
Or both:
157
+
You can either pass a comma-separated list as one parameter, or repeat `-d val` more than once.
123
158
124
-
```
125
-
rat stream jetstream1.us-east.bsky.network \
126
-
--jetstream \
127
-
-d did:plc:abcd1234 \
128
-
-c app.bsky.feed.post,app.bsky.graph.follow
129
-
```
130
159
131
-
You can repeat both options instead if you prefer:
160
+
### Filtering by collection
132
161
133
-
```
134
-
rat stream host --jetstream -d did:1 -d did:2 -c app.bsky.feed.post
135
-
```
136
-
137
-
#### Starting from a cursor
162
+
To print only records from given collection(s):
138
163
139
164
```
140
-
rat stream host -r 12345
165
+
rat stream bsky.network -c app.bsky.feed.post -c app.bsky.actor.profile
141
166
```
142
167
143
168
144
169
## Credits
145
170
146
-
Copyright © 2026 Kuba Suder ([@mackuba.eu](https://bsky.app/profile/mackuba.eu)) & ChatGPT.
171
+
Copyright © 2026 Kuba Suder ([@mackuba.eu](https://bsky.app/profile/did:plc:oio4hkxaop4ao4wz2pp3f4cr)).
147
172
148
173
The code is available under the terms of the [zlib license](https://choosealicense.com/licenses/zlib/) (permissive, similar to MIT).
174
+
175
+
Bug reports and pull requests are welcome 😎