# RatProto – Ruby ATProto Tool 🐀

RatProto (`rat`) is a small command-line tool in Ruby for accessing the Bluesky API / AT Protocol.

It builds on top of the existing ATProto Ruby gems:

- [`minisky`](https://tangled.org/mackuba.eu/minisky/) — XRPC client
- [`skyfall`](https://tangled.org/mackuba.eu/skyfall/) — firehose & Jetstream streaming
- [`didkit`](https://tangled.org/mackuba.eu/didkit/) — DID & handle resolution

> [!NOTE]
> Part of ATProto Ruby SDK: [ruby.sdk.blue](https://ruby.sdk.blue)


## Installation

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+.

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/).

To install `rat`, run:

```
[sudo] gem install ratproto
```

## Features

Currently implemented features/commands:

- resolving DIDs & handles (`rat resolve`)
- fetching & printing ATProto records (`rat fetch`)
- streaming firehose / Jetstream events with optional filters (`rat stream`)


## Resolving a DID or handle

```
rat resolve <did>|<handle>
```

Pass a DID or a handle (@ optional) to look up the given account's identity & print the DID document:

```
$ rat resolve atproto.com

{
  "@context": [
    "https://www.w3.org/ns/did/v1",
    "https://w3id.org/security/multikey/v1",
    "https://w3id.org/security/suites/secp256k1-2019/v1"
  ],
  "id": "did:plc:ewvi7nxzyoun6zhxrhs64oiz",
  "alsoKnownAs": [
    "at://atproto.com"
  ],
  "verificationMethod": [
    {
      "id": "did:plc:ewvi7nxzyoun6zhxrhs64oiz#atproto",
      "type": "Multikey",
      "controller": "did:plc:ewvi7nxzyoun6zhxrhs64oiz",
      "publicKeyMultibase": "zQ3shunBKsXixLxKtC5qeSG9E4J5RkGN57im31pcTzbNQnm5w"
    }
  ],
  "service": [
    {
      "id": "#atproto_pds",
      "type": "AtprotoPersonalDataServer",
      "serviceEndpoint": "https://enoki.us-east.host.bsky.network"
    }
  ]
}
```


## Fetching a record

```
rat fetch at://<did>/<collection>/<rkey>
```

Pass an at:// URI as the argument to fetch a single record from the user’s PDS:

```
% rat fetch at://did:plc:ragtjsm2j2vknwkz3zp4oxrd/app.bsky.feed.post/3lxxmboqmf22j

{
  "text": "a gatinha gorda",
  "$type": "app.bsky.feed.post",
  "embed": {
    "$type": "app.bsky.embed.images",
    "images": [
      {
        "alt": "Kit lying on the ground under the chair ",
        "image": {
          "$type": "blob",
          "ref": {
            "$link": "bafkreiebzsetrrvymvq6dvwma77zqprnv73ovgeqilanzi453dm6xart4q"
          },
          "mimeType": "image/jpeg",
          "size": 963750
        },
        "aspectRatio": {
          "width": 2000,
          "height": 1500
        }
      }
    ]
  },
  "langs": [
    "en"
  ],
  "createdAt": "2025-09-03T21:48:05.910Z"
}
```

## Streaming commit events

```
rat stream <firehose-host> [-j] [-r cursor] [-c collections] [-d dids]
```

Rat can connect to either a relay/PDS firehose:

```
rat stream bsky.network
```

or a Jetstream service (use `-j`):

```
rat stream -j jetstream2.us-east.bsky.network
```

You can also pass a cursor to connect with using `-r` / `--cursor` (tip: pass `-r0` to rewind as far back as the buffer allows).

Once connected, you’ll see output like:

```
[2025-01-02T12:34:56+01:00] did:plc:xwnehmdpjluz2kv3oh2mfi47 :create app.bsky.feed.post 3mbjs5rgtin2z {"text":"hi", ...}
[2025-01-02T12:34:57+01:00] did:plc:3mfkuhmjxd2wvz2e7nhl4poi :delete app.bsky.graph.follow 3mbjs5rghri23
```

Press Ctrl-C to disconnect.

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):


### Filtering by DID

To print only events from given DID(s):

```
rat stream bsky.network -d did:plc:abcd1234,did:plc:xyz9999,...
```

You can either pass a comma-separated list as one parameter, or repeat `-d val` more than once.


### Filtering by collection

To print only records from given collection(s):

```
rat stream bsky.network -c app.bsky.feed.post -c app.bsky.actor.profile
```


## Credits

Copyright © 2026 Kuba Suder ([@mackuba.eu](https://bsky.app/profile/did:plc:oio4hkxaop4ao4wz2pp3f4cr)).

The code is available under the terms of the [zlib license](https://choosealicense.com/licenses/zlib/) (permissive, similar to MIT).

Bug reports and pull requests are welcome 😎