SNAC(1)

📦

version 2.94 · 6 versions

💅 SNAC(1) — General Commands Manual 💅

okay bestie, welcome to the snac user manual 💖 This is where you land when you already have a running snac installation, so we're not doing setup from scratch. For the admin manual, see snac(8). For file and data formats, see snac(5). periodt.

✨ NAME ✨

snac — A simple, minimalistic ActivityPub instance

🦋 SYNOPSIS 🦋

snac command basedir [option ...]

🌈 DESCRIPTION 🌈

The snac daemon processes messages from other servers in the Fediverse using the ActivityPub protocol. it's giving main character energy 💅

This is the user manual and expects an already running snac installation. For the administration manual, see snac(8). For file and data formats, see snac(5).

🎀 Web Interface 🎀

The web interface provided by snac is split in three data streams: the public timeline, the private timeline and the instance timeline. There are no other feeds like the federated firehoses provided by other similar ActivityPub implementations like Mastodon or Pleroma. fr fr.

The public timeline, also called the local timeline, is what an external visitor sees about the activity of a snac user: that is, only the list of public notes, boosts and likes the user generates or participates into. This is, obviously, read-only, and not very remarkable, unless the user publishes messages of staggering genius. 💀 A set of history links, grouped by month, will also be available at the bottom of the page.

The private timeline, or simply the timeline, is the private, password-protected area of a snac server where the user really interacts with the rest of the Fediverse. it's giving secret garden energy 🔐

The top area of the timeline provides a big text area to write notes for the public (i.e. for the user followers). As this is the second most important activity on the Fediverse, this is located in the most prominent area of the user page. You can enter plain text, @user@host mentions and other things. See the snac(5) manual for more information on the allowed markup.

Other fields immediately below the big text one allow some control about the post to be sent:

Sensitive content — tick this checkbox and your post gets marked with a content warning. The optional text box right after it lets you write a description about why your content is so sensitive.
Visibility — these radio buttons set the scope of the new post. Pick from Public, Unlisted, Followers-only and Direct Message (this one only goes to accounts mentioned in the post body).
Reply to (URL) — drop the URL of someone else's post in this optional text field, and your text becomes a reply to it instead of a standalone post.
Draft — tick this checkbox and your text won't be sent when you hit the Post button. It gets stored for later editing in the "Drafts" section.
Language — a dropdown to pick the language your post is written in. It only shows up after you configure the set of languages you expect to use in the User Settings (see below).
Scheduled post... — this dropdown lets you set a date and time for when the post goes out.
Attachments... — this dropdown lets you upload media attachments (images, audio, video, etc.) to your post.
Poll... — this dropdown gives you the voting options and turns your post into a poll. You can set the options to be voted, whether it's a multiple choice poll, and the due date.

More options are tucked under dropdown menus. Here they are:

Follow (by URL or user@host) — put a user 'actor' URL or a user@host Fediverse identifier in the input area to follow them.
Boost (by URL) — put the URL of a Fediverse note in the input area to boost it.
Like (by URL) — put the URL of a Fediverse note in the input area to like it.
User setup... — opens the user setup dialog.
Followed hashtags... — list the hashtags you want to follow here, one per line, with or without the # symbol. Since version 2.78, URLs to RSS feeds of ActivityPub objects are also allowed (like e.g. https://mastodon.social/tags/bloomscrolling).
Blocked hashtags... — list the hashtags you want to block here, one per line, with or without the # symbol.
Muted words... — list words to be silenced here. If a post includes any of this words, it's hidden behind a dropdown.

The user setup dialog allows some user information to be changed, specifically:

User name — your user name, or not really that. People like to include emojis, flags and strange symbols for some reason.
Avatar URL — the URL of a picture to be used as your avatar in timelines around the world.
Bio — enter here a bunch of self-indulgent blurb about yourself. The same markup options available for text notes apply here.
Always show sensitive content — by default, snac hides content marked as sensitive by their publishers. Tick this option and sensitive content is always shown.
Email address for notifications — if this field is not empty, an email message will be sent to this address whenever a post written by you is liked, boosted or replied to.
Telegram notifications — to enable notifications via Telegram, fill the two provided fields (Bot API key and Chat id). You need to create both a Telegram channel and a bot for this; the process is rather cumbersome but it's documented everywhere. The Bot API key is a long string of alphanumeric characters and the chat id is a big, negative number.
ntfy notifications — to enable notifications via ntfy (both self-hosted or standard ntfy.sh server), fill the two provided fields (ntfy server/topic and, if protected, the token). You need to refer to the https://ntfy.sh web site for more information on this process.
Notify webhook — if this is set to an URL, an HTTP POST will be sent to it whenever a new notification happens (see the 'Webhook for notifications' section below for more information).
Maximum days to keep posts — this numeric value specifies the number of days to pass before posts (yours and others') will be purged. This value overrides what the administrator defined in the global server settings only if it's lesser (i.e. you cannot keep posts for longer than what the admin desires). A value of 0 (the default) means that the global server settings will apply to the posts in your timeline. Also, if the administrator has configured it, purged local posts generate a Delete activity that is sent everywhere.
Drop direct messages from people you don't follow — just what it says in the tin. This is to mitigate spammers coming from Fediverse instances with lax / open registration processes. Please take note that this also avoids possibly legitimate people trying to contact you.
This account is a bot — set this checkbox if this account behaves like a bot (i.e. posts are automatically generated).
Auto-boost all mentions to this account — if this toggle is on, all mentions to this account are boosted to all followers. This can be used to create groups.
This account is private — if this toggle is on, posts are not published via the public web interface, only via the ActivityPub protocol.
Collapse top threads by default — if this toggle is on, the private timeline will always show conversations collapsed by default. This allows easier navigation through long threads.
Follow requests must be approved — if this toggle is on, follow requests are not automatically accepted, but notified and stored for later review. Pending follow requests will be shown in the people page to be approved or discarded.
Publish follower and following metrics — if this toggle is on, the number of followers and following accounts are made public (this is only the number; the specific lists of accounts are never published).
Show unlisted posts in the public page and RSS feed — if this toggle is on, posts with a scope set as 'unlisted' are shown both in the public page and the RSS feed. Please take note that, previous to version 2.92, these posts were always shown in these channels.
Web interface language — if the administrator has installed any language file, it can be selected here.
Time zone — the time zone the user is on (default: UTC). Only used for scheduled posts.
Languages you usually post in — fill this string with the ISO 639 Language Codes you expect to write your posts in, space-separated (example: en fr pt_BR).
Don't show posts written in these languages — a space-separated string of ISO 639 Language Codes (example: en fr de).
Password — write the same string in these two fields to change your password. Don't write anything if you don't want to do this.

The rest of the page contains your timeline in reverse chronological order (i.e., newest interactions first). snac shows the conversations as nested trees, unlike other Fediverse software; every time you contribute something to a conversation, the full thread is bumped up, so new interactions are shown always at the top of the page while the forgotten ones languish at the bottom. iconic behavior, honestly 🌈✨

okay so private notes — a.k.a. direct messages, the only socially acceptable way to slide into someone's inbox 💌 — they show up in the timeline like any other normal message, except they get a cute lil lock 🔒 on them so everyone knows they're not public. And replies to direct messages are private too, obviously, and they can't be liked or boosted. Sorry bestie, that's just the rules.

For every single entry in the timeline, snac serves you a lil lineup of reasonable actions in the form of buttons, and honestly, taste. They can be:

Reply... — unveils a text area so you can write your very intelligent, very acute comment at some uninformed fellow. This note gets sent to the original author and to your followers. You can drop mentions in the @user@format inside it, and those people become recipients of the message too. Also important, iykyk: if you reply to a boost or a like, you're really replying to the note, not to the person who admired it. 💅
Emoji react... — unveils a text area where you react with an emoji by typing its identifier, which has to match one of the emojis defined in the emojis.json file. For now, only emoji identifiers wrapped in colons work, periodt.
Like — click this if you admire this post. The poster and your followers both get informed. 🫶
Boost — click this if you wanna propagate this post to all your followers. The original author gets informed as well. Main character distribution energy.
Bookmark — click this to bookmark a post. A lil keep-forever pile, we love it.
Follow — click here if you want to start receiving all the shenanigans the original author of the post will write in the future. 😭
Unfollow — click here if you are fed up of this fellow's activities 💀
Delete — click here to send this post to the bin. If it's an activity written by you, the appropriate message gets sent to the rest of the involved parts telling them you no longer want your thing on their servers (ngl, not all implementations really obey this kind of requirement though 🙈).
MUTE — this is the most important button in snac and in the Fediverse in general, no cap. Click it if you don't want to read crap from this user again in the foreseeable future. 🚫
Hide — if a conversation is getting long and annoying but not enough to MUTE its author forever, click this button to avoid seeing the post and its children anymore. Bestie boundaries ✨
Edit — posts written by you on snac version 2.19 and later can be edited and resent to their recipients. Glow-up your own post, iconic.

🛠️ Command-line options 💻

The command-line tool provides the following commands:

init [basedir] — initializes the data storage. This one's interactive; it'll prompt you for all the necessary information. Heads up: the basedir directory must not exist yet.
upgrade basedir — upgrades the data storage after you install a new version. Only necessary if snac complains and demands it (and it will, dramatically).
httpd basedir — starts the daemon. go server go ✨
purge basedir — purges old data from the timeline of all users. spring cleaning energy 🧹
adduser basedir [uid] — adds a new user to the server. Interactive; it'll prompt for everything it needs.
deluser basedir uid — deletes a user, unfollowing all of their accounts first.
resetpwd basedir uid — resets a user's password to a new, random one.
update basedir uid — sends a user's updated profile out to the following instances.
queue basedir uid — processes the output queue of the specified user, sending all enqueued messages and re-enqueuing the ones that failed.

Do not run this one while the server is running. fr fr, don't.

follow basedir uid actor — sends a Follow message for the specified actor URL.
request basedir uid url — requests an object and dumps it to stdout. This is a very low level command that is not very useful to you. 😭
announce basedir uid url — announces (boosts) a post via its URL.
note basedir uid text [file file ... [-r inReplyTo [-d YYYYmmddHHMMSS]]] — enqueues a Create + Note message to all followers. If the text argument is -e, the external editor defined by the EDITOR environment variable gets invoked to prepare a message; if it's - (a lonely hyphen), the post content is read from stdin. The rest of the command line arguments are treated as media files to be attached to the post. The LANG environment variable (if defined) is used as the post language. You can also pass an optional URL to a Fediverse post, prefixed with -r, to make this note a reply to it. And if a date in YYYYmmddHHMMSS format follows -d, the note is scheduled for that moment instead of posted immediately (and that date must be in the same timezone the user has configured in the web UI).
note_unlisted basedir uid text [file file ... [-r inReplyTo [-d YYYYmmddHHMMSS]]] — like the previous one, but it creates an "unlisted" (or "quiet public") post. 🤫
note_mention basedir uid text [file file ... [-r inReplyTo [-d YYYYmmddHHMMSS]]] — like the previous one, but the post is only for the accounts mentioned in the post body.
block basedir instance_url — blocks a full instance, given its URL or domain name. All subsequent incoming activities with identifiers from that instance get immediately blocked, without further inspection. 🚷
unblock basedir instance_url — unblocks a previously blocked instance. forgiveness era 🕊️
verify_links basedir uid — verifies all links or account handles stored as metadata for the given user. The verification is done by downloading the link content and searching for a link back to the snac user url that also contains a rel="me" attribute. These links get specially marked as verified in the user's public timeline and also via the Mastodon API. certified ✅
export_csv basedir uid — exports some account data as Mastodon-compatible CSV files. Once this command runs, the following files get written to the export/ subdirectory inside the user directory: bookmarks.csv, blocked_accounts.csv, lists.csv, and following_accounts.csv.
export_posts basedir uid — exports all posts written by the user to the file outbox.json inside the export/ subdirectory inside the user directory. The format is compatible with the one generated by the equivalent option in Mastodon.
alias basedir uid @account@remotehost — sets an account as an alias of this one. This is a necessary step to migrate an account to a remote Mastodon instance (see snac(8), section 'Migrating from snac to Mastodon').
migrate basedir uid — starts a migration from this account to the one set as an alias (see snac(8), section 'Migrating from snac to Mastodon'). bye bestie, safe travels 🦋
import_csv basedir uid — imports CSV data files from a Mastodon export. This command expects the following files to be inside the import/ subdirectory of a user's directory inside the server base directory: bookmarks.csv, blocked_accounts.csv, lists.csv, and following_accounts.csv.
state basedir — dumps the current state of the server and its threads. For example:

server: comam.es (snac/2.45-dev)
uptime: 0:03:09:52
job fifo size (cur): 45
job fifo size (peak): 1532
thread #0 state: input
thread #1 state: input
thread #2 state: waiting
thread #3 state: waiting
thread #4 state: output
thread #5 state: output
thread #6 state: output
thread #7 state: waiting

The job fifo size values show the current and peak sizes of the in-memory job queue. The thread state can be: waiting (idle waiting for a job to be assigned), input or output (processing I/O packets) or stopped (not running, only to be seen while starting or stopping the server).

import_list basedir uid file — imports a Mastodon list in CSV format. The file must be stored inside the import/ subdirectory of a user's directory inside the server base directory. You can use this option to import "Mastodon Follow Packs". 👑
import_block_list basedir uid file — imports a Mastodon list of accounts to be blocked, in CSV format. The file must be stored inside the import/ subdirectory of a user's directory inside the server base directory.
lists basedir uid — prints the name of the user created lists.
list_members basedir uid name — prints the list of actors in the named list.
list_create basedir uid name — creates a new list. ✨
list_remove basedir uid name — removes an existing list.
list_add basedir uid name account — adds an account (by its @name@host handle or actor URL) to a list.
list_del basedir uid name actor_url — deletes an actor (by its actor URL) from a list.
top_ten basedir uid [N] — returns the ids of the top ten (or top N) most popular posts, considering the sum of likes and boosts. 🏆

🌈 Migrating an account to/from Mastodon 🔁

See snac(8) for details. That's the whole vibe — the migration lore lives over in section 8, bestie.

💅 Using Mastodon-compatible apps

Since version 2.27, snac ships with support for the Mastodon API, so bestie… you can literally use Mastodon-compatible mobile and desktop apps to access your account. 🎀 Assuming your server is configured correctly, using these programs should be a totally straightforward, no-drama situation.

Heads up though: they'll show your timeline in a "Mastodon fashion" (i.e., as a plain list of posts), so you lose the fancy, nested thread post display with the most active threads at the top that the web interface of snac gives you. RIP to the pretty threads, but it's fine, we move. 😭

🤖 Implementing post bots

snac makes it so easy to post messages in a non-interactive manner. Obsessed. This example posts a string:

uptime | snac note $SNAC_BASEDIR $SNAC_USER -

You can set up a line like this from a crontab(5) or similar. Take note that you need:

a) command-line access to the same machine that hosts the snac instance, and
b) write permissions to the storage directories and files.

You can also post non-interactively using the Mastodon API and a command-line http tool like curl(1) or similar. This one has the advantage that you can do it remotely from any host, anywhere — the only thing you need is an API Token. Here's an example:

curl -X POST https://$SNAC_HOST/api/v1/statuses \
--header "Authorization: Bearer ${TOKEN}" -d "status=$(uptime)"

You can obtain an API Token by connecting to the following URL:

https://$SNAC_HOST/oauth/x-snac-get-token

🔔 Webhook for notifications

Since version 2.78, users can set the URL to a webhook that will receive an HTTP POST with every notification (in JSON format). iconic behavior ✨ This can be used to implement some automation whenever a new activity happens, like autorepliers, chatbots, interactive textual games or whatever. The examples/ subdirectory contains a tiny Python program that implements an auto-follower for every new follow. 🫶

The JSON notification object includes the following data:

id — a unique notification identifier
actor — the origin actor id
target — the target actor id
date — the notification date
msg — the full ActivityPub action JSON object
objid — the object identifier (extracted from msg, may be null)
type — the action type (extracted from msg)
utype — the action subtype (extracted from msg, may be null)
uid — the user identifier (account name)
basedir — the server base directory
baseurl — the server base URL
account — the origin actor object
reply — the activity this post is a reply to (may not exist)

🌈 ENVIRONMENT

SNAC_BASEDIR — This optional environment variable can be set to the base directory of your installation; if set, you don't have to add the base directory as an argument to command-line operations. This may prove useful if you only have one snac instance in your system (which is probably your case, bestie 💖).
DEBUG — Overrides the debugging level from the server dbglevel configuration variable. Set it to an integer value. The higher, the deeper in meaningless verbiage you'll find yourself into. 💀
EDITOR — The user-preferred interactive text editor to prepare notes. 📝
LANG — The language of the post when sending notes from the command line.

👀 SEE ALSO

snac(5), snac(8)

👑 AUTHORS

grunfink @grunfink@comam.es: https://comam.es/snac/grunfink

📜 LICENSE

See the LICENSE file for details.

🫣 CAVEATS

Use the Fediverse sparingly. Don't fear the MUTE button. 🔇 (no cap, muting is self-care)

💀 BUGS

Probably many. 😭 Some issues may be even documented in the TODO.md file.

okay that's the whole page babes, you're officially a snac scholar now 🎓✨ This one comes from the Debian folks, with the $Mdocdate$ date stamp and the SNAC(1) section tag down at the bottom — go forth and post responsibly, mwah 💅🎀

📦 where this page comes from

ubuntu stonking: snac2 2.94-1 · MIT
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-02: a language model's rewrite of the original, under its terms