Using the BOX helper¶
The [BOX] helper is a CLI tool for interacting servers that support the Client to Server ActivityPub protocol and OAuth2 user authorization.
Authorization¶
In order to authorize BOX to an ONI instance you can do it very simple:
# instead of passing the --secret flag, we can use the OAUTH2_SECRET=AnotherSecretPassword env variable
$ box authorize --as https://social.example.com --secret AnotherSecretPassword
5:52PM INF OK
# For a FedBOX instance, where the OAuth2 client needs to exist as an [Application actor](),
# the authorization needs to pass both SECRET and APP
$ export OAUTH2_APP=https://fedbox.example.com/actors/21111111-ffff-cccc-aaaa-eeeeeeeeeeed
$ export OAUTH2_SECRET=AnotherSecretPassword
$ box authorize --as https://fedbox.example.com/actors/00000001-0001-eeef-bbbc-101010101011
2:15PM INF OK
Post a text entry¶
The most basic operation is to post a simple text post.
$ box post --as https://social.example.com --name "First post!" --content "Hello Fediverse!"
5:56PM DBG OK IRI=https://social.example.com/ duration=12.234175ms log=client status="200 OK"
5:56PM INF success id=https://social.example.com/outbox/1755861965567 object=https://social.example.com/outbox/1755861965567/object op=Create
Posting allows for a little bit more convenience over needing to pass the content in a command line flag by allowing you to edit in your preferred $EDITOR.
To take advantage of that, you simply need to keep all content related flags empty. They are --name, --summary and --content.
Upload an image¶
$ box upload --as https://social.example.com --name "First image!" \
--summary "The summary works as 'alt' text for images" --path ./example.png
6:05PM DBG OK IRI=https://social.example.com/ duration=11.044419ms log=client status="200 OK"
6:05PM INF success id=https://social.example.com/outbox/1755864320719 object=https://social.example.com/outbox/1755864320719/object op=Create
If uploading large images, you can use the --optimize flag to generate web-optimized variants for it.
This creates small, medium and large variants of the image and uploads them together. Luckily the ActivityPub Image objects support multiple versions and ONI can render them relatively well taking advantage of that.
Deleting an object¶
Deleting objects can be done with the following command:
$ box delete --as https://social.example.com https://social.example.com/outbox/1755864320719/object
6:09PM DBG OK IRI=https://social.example.com/ duration=7.977597ms log=client status="200 OK"
6:09PM DBG OK IRI=https://social.example.com/outbox/1755864320719/object duration=4.30088ms log=client status="200 OK"
6:09PM INF success id=https://social.example.com/outbox/1755866986821 object=https://social.example.com/outbox/1755864320719/object op=Delete
Undoing an activity¶
Sometimes Deleteing an object is not what you want.
For example if you want to reuse the ID of a deleted object, it’s not possible to do in the current way GoActivityPub works, as the deleted object is now a Tombstone and changing an object’s Type is not possible.
So what you can do is to Undo the activity used to create the object in the first place. Here’s an example for the above:
$ box undo --as https://social.example.com https://social.example.com/outbox/1755864320719
6:29PM DBG OK IRI=https://social.example.com/ duration=8.542569ms log=client status="200 OK"
6:29PM DBG OK IRI=https://social.example.com/outbox/1755864320719 duration=3.451258ms log=client status="200 OK"
6:29PM INF success id=https://social.example.com/outbox/1755872961055 object=https://social.example.com/outbox/1755864320719 op=Undo
Changing the visibility of an ONI collection to non-public¶
Collections in ONI get created as public accesible by default. The objects contained within are still filtered out if they are not public, but the collection itself can be accessed by anyone.
To change that, we need to remove the public namespace https://www.w3.org/ns/activitystreams#Public from the CC recipients list with something else.
When the editor opens you can replace the public namespace IRI with something like the actor’s followers collection, in our example that would be: https://social.example.com/followers.
$ box edit --as https://social.example.com https://social.example.com/inbox --cc
11:25AM DBG OK IRI=https://social.example.com duration=8.856835ms log=client status="200 OK"
11:25AM DBG OK IRI=https://social.example.com duration=2.28738ms log=client status="200 OK"
11:25AM DBG OK IRI=https://social.example.com/inbox duration=2.27656ms log=client status="200 OK"
11:25AM INF success id=https://social.example.com/outbox/1756002242275 object=https://social.example.com/inbox op=Update
Naturally this operation can be effected on any object to change its visibility.