Examples for using BOX with ONI instances¶
Interacting with ONI using BOX is using the basic operations already described in the basic BOX documentation.
Here we detail a couple of ONI specific operations.
You must be authorization with the server first in order for these to work.
Uploading a new image for the ONI actor¶
The default image for the ONI main actor is an SVG of the kanji for Oni spirit.
To change that we can first upload a suitable image either in jpg, or png format. We suggest a square image.
$ box upload --as https://social.example.com --name "Malevich's black square" \
--summary "An image showing a painting of a black square in a wide white framing" --path ./malevich.png --id https://social.example.com/icon
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/1755864382827 object=https://social.example.com/icon op=Create
The next step is to edit the actor in order to change the icon:
$ box edit --as https://social.example.com --icon
06:24PM INF success id=https://social.example.com/outbox/1757500242236 object=https://social.example.com op=Update
Similarly you can edit the image property for the actor.
$ box edit --as https://social.example.com --image
06:27PM INF success id=https://social.example.com/outbox/1757500248537 object=https://social.example.com op=Update
Based on the icon and the image, the web components of ONI compute a colour palette that’s going to be used for the CSS.
The image determines the background colour and if it’s going to be a light or dark theme.
The icon determines the foreground, background, link, and accent colours.
Editing the name, summary and details of the main actor¶
Similarly to the icon and image, you can edit the textual properties of the actor.
They are --name, --preferred-username for name and username, --summary for a short description of the user, and --content for a more detailed, longer and supporting HTML text.
$ box edit --as https://social.example.com --name
06:33PM INF success id=https://social.example.com/outbox/1757500258216 object=https://social.example.com op=Update
Changing the type of an object¶
Before changing the type of an object please make sure you’re aware of the caveats of doing that.
So, for the main actor of ONI you could use another actor type: Person, Group or Service.
$ box edit --as https://social.example.com --type
06:39PM INF success id=https://social.example.com/outbox/1757500440109 object=https://social.example.com op=Update
Authoring a text post¶
BOX uses the locally configured text editor for handling text, so when we want to create a new post using a command like this:
$ box post --as https://social.example.com --id https://social.example.com/news/october-2025
A new editor window will be opened to accept your input.
The editor can be configured through the --editor CLI argument, or it defaults to the $EDITOR environment variable.
The post processing of the submitted text follows the following conventions.
If the first line is followed by two empty lines, it will be considered the title of the post. Which can be also passed through the --name CLI argument.
If at any point there are another two empty lines, the paragraphs preceding it will be used as a summary. Which can be also passed through the --summary CLI argument.
The remainder of the text will be the content of the post. Again, it can be passed through the --content CLI argument.
Make sure to read the short help of the command for other arguments and options. You can control visibility and if the post should have attached media.
BOX also tries to extract additional tags and mentions from the text.
Tags are marked by starting with the traditional # symbol, and mentions use the double @ notation used by Fediverse servers for WebFinger access.