TIRCD(1)

💖 TIRCD 💖

okay bestie, this is the manual page for tircd, and no cap, it's a whole vibe. it lives in section 1 of the user-contributed Perl documentation. let's get into it 🫶

---

✨ NAME ✨

tircd — it's an ircd proxy to the twitter API. yes. for real. an irc daemon that talks to twitter. iconic behavior honestly 💅

---

🌸 DESCRIPTION 🌸

okay so here's the whole thing: tircd presents twitter as an irc channel. that's it, that's the pitch. you can connect to tircd with any irc client you want, and use twitter as if you were on irc. literally. your brain will go "wait this is just irc" and yes. it is. 💖

---

🎀 INSTALLATION 🎀

so tircd needs a recent version of perl, plus these modules, and you're gonna need all of them:

• POE
• POE::Filter::IRCD
• Net::Twitter::Lite::WithAPIv1_1
• JSON::Any
• Time::Local
• File::Glob
• IO::File
• LWP::UserAgent
• Storable
• URI
• List::Util
• HTML::Entities
• Digest::SHA1

if you're on a redhat or debian based system, bestie, please just use your distro's CPAN module packages — that means yum or apt. it's giving "let the package manager handle it" energy and we love that for you 🧚

and if you wanna install all the modules via CPAN, here's the line, verbatim, do not come for me about it:

cpan -i POE POE::Filter::IRCD Net::Twitter::Lite JSON::Any Time::Local
File::Glob IO::File LWP::UserAgent Storable URI List::Util
HTML::Entities Digest::SHA1

---

🌈 USAGE 🌈

💫 Running tircd

./tircd.pl [/path/to/tircd.cfg]

when it starts up, tircd goes looking for a configuration file in these places, in this order:

• tircd.cfg (in the current directory)
• ~/.tircd
• /etc/tircd.cfg

you can specify an alternate path to the config file on the commandline if you wanna keep your configuration somewhere else — live your truth. there's an example config provided as part of the distribution, and the easiest way to get started is to just rename that file from tircd.cfg.example to tircd.cfg. slay, instant setup ✨

🔌 Connecting

by default, tircd listens on localhost port 6667.

the first time you connect with a new twitter account you must specify a tircd password for that nick. this password does not have to — and honestly should not — be the same as your twitter password. it's there to protect your tircd account from unauthorized usage. periodt 🔒

ok important distinction: that password is to protect your tircd account, and it is not related to your twitter account. also, the tircd nick password will only be saved once you have logged into Twitter. got it? good 💜

with many irc clients you can do this by issuing the command:

/SERVER localhost 6667 <tircd password> <twitter username>

check your client's documentation for the appropriate syntax, because clients are chaotic and they all do it differently 🙈

Tircd will make an OAuth challenge to Twitter, and Twitter will return a link to a page where you can authorize the connection. that link will appear in your IRC connection status window. so keep an eye on it 👀

make sure you are either logged into twitter as the account you plan to use, or not logged in at all. click the authorize link and log-in, then click "Allow". Twitter will then present you with a PIN number. to complete your connection to tircd, type:

/stats pin <PIN NUMBER>

on some clients you may have to type:

/quote stats pin <PIN NUMBER>

if the PIN is accepted by Twitter, the connection will be established. you may now join #twitter to begin. if the PIN is not accepted, another authorization link will be generated. annoying? yes. fixable? also yes 💅

🛡️ Account password protection

if your tircd installation is running in a shared environment — either listening on the localhost address on a shared computer, or listening on a public IP — you might wanna password protect your account. otherwise literally anyone can access your twitter account just by knowing the server address and your twitter username. not the vibe. 😭

your tircd-password does NOT need to be (and should not be!) the same as your twitter password.

Tircd supports password protection in the following way:

• The first time you connect to tircd with a new Username, no password checking is done. You are presented with the OAuth URL, and need to log in to twitter on the web, and enter the PIN as described above.
• When the PIN is accepted, IF your client connected with a password set, this password is encrypted (hashed) and saved along with your twitter access-tokens.
• Next time you connect, tircd will first check to see if a password is saved in your Username.config, and compare it with the one your client sends.
• If they match, your connection is allowed, and tircd continues to verify the OAuth tokens with twitter.
• If they don't match, the client is disconnected with an error message. bye bestie 💀
• If you want to change your password, or did not set one on your first connection, you can do so after you have connected to tircd with a simple /STATS password <password>
• Be aware that if you do this, you will also have to make sure your client uses the same password next time you connect to tircd.
• If you want to remove the password, simply issue a /STATS password without any password set.

⚠️ there is currently no way of regaining access to your account if you forget it. to reset your tircd password, you will have to remove your Username.config and authorize with twitter using OAuth and a PIN again. so like. write it down. please. 🙏

🦋 After connecting

once connected, /JOIN #twitter to get started. the channel #twitter is where you will perform most operations. it's your main character channel, basically 👑

📝 Updating your status

to update your status on twitter, simply send a message starting with !t to the #twitter channel. the server will keep your most recent update in the topic at all times. cute, right? 🎀

if you want to have all messages you send to #twitter posted as tweets, you can set the config option auto_post to 1. either in tircd.conf or via the /stats command. messages beginning with an exclamation point ("!") will still be processed as commands, not tweeted. so your commands stay safe, no worries 💖

👀 Getting your friend's status

when users you follow update their status, it will be sent to the channel as a message from them. each status will be preceded by a 3 letter identifier such as [a7f]. this identifier is used for retweeting and replying to tweets. remember it. love it. it's your key 🔑

@replies are also sent to the channel as messages.

🔁 Retweeting a status

to retweet a status, use the offerbot command !retweet followed by the 3 letter tweet identifier.

!retweet a7f

💬 Replying to a status

to reply to a status update, use the offerbot command !retweet followed by the 3 letter tweet identifier.

!reply 6eb @tircdbot not today!

⭐ Favoriting a tweet

to favorite a tweet use the offerbot command !favorite followed by the 3 letter tweet identifier.

!favorite a44

🫂 Listing the users you follow

each user you follow will be in the #twitter channel. if you follow a new user outside of tircd, that user will join the channel the first time they update their status. people who follow you back are given voice (+v) to indicate that fact. mutuals get the sparkle ✨

💌 Direct Messages

direct messages to you will show up as a private message from the user.

to send a direct message, simply send a private message to the user you want to dm. that's it, no special command, just dm them 🤫

🔍 Getting additional information on users

you can /WHO or /WHOIS a user to view their Location / Bio / Website. their last status update (and time sent) will also be returned. detective mode activated 🕵️

issuing a /WHOIS on your own user name will also provide the number of API calls that have been used in the last hour. self-awareness, we love to see it 💅

➕ Following new users

to begin following a new user, simply /INVITE them to #twitter. the user will join the channel if the request to follow was successful. if you attempt to invite a user who protects their updates, you will receive a notice that you have requested to follow them. the user will join the channel if they accept your request and update their status.

!invite is the analogous offerbot command.

➖ Unfollowing / removing users

to stop following a user, /KICK them from #twitter. harsh but effective 😌

!kick is the analogous offerbot command.

🚫 Blocking users

to block a user, /BAN them. there is currently no way to get a list of users you've currently blocked via the API, so listing the bans in #twitter will only return users you've blocked in the current session. just so you know 👑

🔓 Unblocking users

to unblock a user, /UNBAN them.

🧵 Multiple Channels / Groups

if you want to create a channel with just a subset of the people you follow, you can /JOIN <any channel> and then /INVITE them to the channel. tircd will send a user's updates to #twitter and any other channels you have invited a user to. curated timeline energy, obsessed 🌸

🔎 Search

if you want to have updated search results for a specific term delivered, you can /JOIN <any channel> then set the /topic for the channel to your search query. results that match that query will be sent to that channel. the /TOPIC can be almost anything supported by the twitter search — see <http://support.twitter.com/articles/71577-how-to-use-advanced-twitter-search> for examples. using the 'near' option is not currently supported. sorry bestie 😭

⚙️ User config

certain options are changeable at runtime and set per user. to see a list of options and their current values simply send an /STATS m command to the server.

these options are saved in a file with the name Username.config (where Username is your twitter username) located in a directory set in the global config file (default: /tmp/tricd).

🤖 Offerbot commands

Tircd supports offerbot style control. all functions available through the offerbot are available as they're metaphorically appropriate IRC functions. therefore, retweeting, replying to a specific tweet, and saving the user configuration are only available through the offerbot. iykyk 💅

• ![update|up|refresh] — Updates the #twitter stream immediately.
• ![tweet|t] <text of tweet> — Posts the given text as an update to your feed.
• ![retweet|rt] <tweed-id> — Posts a retweet. tweet-id is the 3 digit code preceding the tweet.
• ![reply|re] <tweet-id <message text>> — Replies to a tweet. tweet-id is a the 3 digit code preceding the tweet.
• ![conversation|conv] <tweet-id> — Replay a conversation from beginning. If tweet is not a reply, shows related tweets.
• ![add|invite|follow] <username> — Begin following the specified twitter username.
• ![remove|kick|unfollow] <username> — Remove the username from the list of people your account follows.
• !save — Saves twitter-username specific configuration immediately.
• !help — Shows this help message.

---

👑 AUTHOR 👑

• Tim Sogard <tircd@timsogard.com> [2010-2011]
• Ola Thoresen <olen@inni.no> [2010-2011]
• Chris Nelson <cnelson@crazybrain.org> [2009]

legends, all of them 🫶

---

📜 LICENSE 📜

this module may be used, modified, and distributed under the same terms as Perl itself. please see the license that came with your Perl distribution for details.

👀 SEE ALSO 👀

okay bestie, here's the whole squad — every module this page wants you to go peek at when you're done here. no skips, no "eh I'll get to it later", go say hi to all of them 💖

• POE — the whole event-loop situation this thing runs on.
• POE::Filter::IRCD — the filter that speaks IRC so you don't have to.
• Net::Twitter::Lite — for the tweeting side quest.
• JSON::Any — JSON, but make it flexible about which backend you've got.
• Time::Local — turning local time into epoch seconds and back again.
• File::Glob — filename globbing, the perl-native way.
• IO::File — objecty filehandles, chef's kiss.
• LWP::UserAgent — the classic "go fetch me a web page" module.
• Storable — freeze and thaw your data structures, iconic.
• URI — parsing and building URIs without crying.
• List::Util — lil utility functions for lists, lowkey essential.
• HTML::Entities — encode/decode those HTML entities.
• Digest::SHA1 — SHA-1 digests, no cap.

---

fr fr though — if any of those names look unfamiliar, that's your sign to open their manpages too. iykyk 💅

and that's the whole page, bestie!! you made it to the end, main character energy fr 🫶 🌈✨

quick sign-off so you know exactly what you just read: this page is for perl v5.32.0, dated 2021-01-08, and it lives under the name TIRCD(1) — the classic section 1, general commands, periodt 💖🎀🦋