engielolz.ritsuko.akizuki.best / bash-atproto
atproto library for bash scripts
atproto bash-atproto
fork atom
Shell 100.0%
12 3 0

Clone this repository

https://tangled.org/engielolz.ritsuko.akizuki.best/bash-atproto
git@tangled.org:engielolz.ritsuko.akizuki.best/bash-atproto

For self-hosted knots, clone URLs may differ based on your setup.

Download tar.gz
README.md

bash-atproto#

bash-atproto is a bare-bones atproto client/library that I wrote for imasimgbot and the now-defunct 765coverbot. It is a Bash script that uses cURL to authenticate, create records and upload blobs.

Supported functions#

Functions built into bash-atproto.sh

  • Resolving a handle to did:plc/did:web - bap_didInit
  • Resolving an account's PDS from the DID - bap_findPDS
  • Creating and closing sessions on the PDS - bap_getKeys and bap_closeSession
  • Saving and loading a secrets file (contains your access and refresh tokens) - bap_saveSecrets and bap_loadSecrets
  • Extracting account and token information from the access token - (automatic)
  • Refreshing tokens - bap_refreshKeys
  • Prepare an image, stripping EXIF data and (if needed) resizing it for a set file size and dimensions - bap_prepareImage
  • Uploading blobs - bap_uploadBlobToPDS
  • Working with records:
    • Add string value - bapCYOR_str
    • Add value - bapCYOR_add
    • Add to array - bapCYOR_arr
    • Remove key - bapCYOR_rem
    • Post record - bap_postRecord

Bluesky functions#

With bap-bsky.sh

  • Creating basic Bluesky text post records - bapBsky_createPost
  • Creating Bluesky repost records - bapBsky_createRepost
  • Preparing an image for Bluesky (including resizing and compressing) - bapBsky_prepareImage
  • Creating a post with a single embedded image or video with alt text and embedded image dimensions - bapBsky_postImage and bapBsky_postVideo
  • When working on a post:
    • Start a post - bapBsky_cyorInit
    • Prepare an image for upload - bapBsky_prepareImage
    • Add an image - bapBsky_cyorAddImage
    • Add a video - bapBsky_cyorAddVideo
    • Set language - bapBsky_cyorAddLangs
    • Add tags - bapBsky_cyorAddTags
    • Add self-labels - bapBsky_cyorAddSelfLabels
    • Make reply - bapBsky_cyorAddReply
    • Make quote - bapBsky_cyorAddQuote
    • Submit post - bapBsky_submitPost

Spark functions#

With the experimental bap-sprk.sh

  • Creating a post with a single embedded image with alt text or video - bapSprk_postImage and bapSprk_postVideo
  • When working on a post:
    • Start a post - bapSprk_cyorInit
    • Prepare an image for upload - bapSprk_prepareImage
    • Add an image - bapSprk_cyorAddImage
    • Add a video - bapSprk_cyorAddVideo
    • Submit post - bapSprk_submitPost

Dependencies#

bash-atproto requires cURL 7.76 or later and jq 1.7 or later. Posting images and video additionally requires imagemagick, exiftool, uuidgen and file.

Basic usage#

bash-atproto is loaded with source bash-atproto.sh. From there, most operations will require you to sign-in to an atproto account, which can be done in three functions:

  1. bap_didInit <did or handle> which will resolve your handle to a DID
  2. bap_findPDS $savedDID which will retrieve the account's PDS for use
  3. bap_getKeys $savedDID <password> to log in. The access and refresh tokens are saved in memory and can be written to disk with bap_saveSecrets <file>. It is recommended you use an App Password to log in rather than a normal password.

You may need to load additional scripts to handle other tasks. For example, to post to Bluesky, you will need to source bap-bsky.sh.

If bash-atproto is being used with a bot or other service that runs periodically, the calling application should implement a timer to refresh tokens. bash-atproto provides a function to perform a refresh (bap_refreshKeys) and a timestamp to detect when a token refresh should be performed ($bap_savedAccessExpiry), but it does not do so itself.

Standalone usage#

bash-atproto is mainly meant for use as a component for bash scripts that want to use the AT Protocol, but it by itself can be used as a simple atproto client for the command line. The following commands will log in to your PDS, create a Bluesky post and then log out:

  1. source bash-atproto.sh
  2. bap_didInit <your did or handle>
  3. bap_findPDS $savedDID
  4. bap_getKeys $savedDID <app password>
  5. bap_postToBluesky "Hello, World!" en
  6. bap_closeSession

License#

bash-atproto is licensed under the MIT License. Please note that bash-atproto is hobbyist-grade software and I take no responsibility if it is used to post Discourse™ to your account.