Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
App::Twirc::Manual(3) User Contributed Perl DocumentationApp::Twirc::Manual(3)

       App::Twirc::Manual - User guide and reference for Twirc

       "Twirc" is a twitter client.  More precisely, it	is an IRC/Twitter
       gateway that makes your favorite	IRC client a twitter client.

       Follow friends timelines
       Receive replies from friends and	non-friends
       Post status updates
       Send and	receive	direct messages
       Follow, un-follow, block, unblock, and use most other twitter commands

       You can install "twirc" just as you would any other CPAN	distribution:

	   cpanm POE::Component::Server::Twirc

       Or, you can download and	unpack "twirc",	then run it from a directory
       of your choice without running "make install".  That's the way the
       author runs it.	If you choose this option, run "make" to install
       "twirc"'s dependencies.

       If you'd	like to	contribute to "twirc" or just want to build the
       distribution for	some other reason, you must have the following Perl


       "Twirc" uses Config::Any, so you	can configure "twirc" using XML, YAML,
       JSON, Apache-style configuration, Windows INI file format, or even Perl

       A configuration file is not necessary, but is recommended.

       Here's an example configuration in YAML:

	   state_file: twirc.state
	   log_level: INFO

	   The name of the IRC server. Defaults	to "twitter.irc".  Every IRC
	   server has a	name.  The IRC server included with "twirc" isn't
	   intended to be accessed publicly.  It is for	your own personal use.
	   So, the name	is not significant.

	   The port number the IRC server binds	to. Defaults to	6667.

	   The local address to	bind to. Defaults to all to prevent
	   others from connecting to your "twirc" IRC server. If you run
	   "twirc" on a	different system than your IRC client, you will	need
	   to provide this configuration option	with a suitable	address.

	   The IRC user/host mask used to restrict connecting users.  Defaults
	   to "*@".  If you run "twirc" on a different	system than
	   your	IRC client, you	will need to provide this configuration	option
	   with	a suitable mask.

	   Password used to authenticate to the	IRC server.  If	you don't
	   provide this	option,	no password will be required.  It adds a bit
	   of security.	 You may want to set this option if other users	have
	   access to your system.

	   The name of the channel operator bot.  Defaults to "tweeter".
	   Select a name that does not conflict	with friends, followers, or
	   your	own IRC	nick.

	   When	running	"twirc", you interact with a bot in the	channel.  The
	   bot carries out commands on your behalf and provides	feedback,
	   particularly	when there are errors.

	   Text	to be used as the channel operator bot's IRC full name.
	   Defaults to "Your Friendly Twitter Agent".  This is the name	that
	   will	appear in response to an IRC "/whois" command.

	   The name of the channel where your twitter friends' timelines
	   appear.  This is the	channel	where most of your interaction with
	   "twirc" occurs.  It defaults	to &twitter.  The IRC convention for
	   channels names is channels local to a single	server begin with "&".
	   Network channels begin with "#".  You can use either	to name,
	   however "&" is more appropriate.

	   An alias to use for displaying incoming status updates from the
	   owning user.	 This is necessary if the user's IRC nickname and
	   Twitter screen name are the same.  Defaults to "me".

	   With	the default value "me",	when "twirc" reads a status message in
	   your	timeline from your Twitter screen name,	it will	use "me" in
	   place of your Twitter screen	name in	the channel.

	   How many status messages to display for selection when favoriting,
	   replying, or	retweeting. Defaults to	3.

	   When	displaying a list tweets for selection,	for example, in
	   response to the "favorite" command, they will be truncated to this
	   length to avoid cluttering the screen with long messages that wrap.
	   Defaults to 60.

	   If specified, twirc will post log messages to this channel.	If you
	   set this option to &log, then you can join the &log channel and see
	   the copious debug messages that "twirc" generates.  This may	be
	   useful for trouble shooting or problem reporting.

	   Twirc supports "log_level" values OFF, FATAL, ERROR,	WARN, INFO,
	   DEBUG, and TRACE.  The default is WARN.

	   File	used to	store state information	between	sessions, including
	   Twitter OAuth access	tokens,	friends, and followers_ids.

       To use "twirc" you first	need to	start the server:

	   bin/twirc -b	--state_file=twirc.state

       The "-b"	option runs "twirc" in the background.	Drop the "-b" to see
       log messages to STDERR. (The author runs	twirc and his irc client in
       screen, <>, to monitor log messages
       to STDERR.)

       Next, connect to	the server from	your IRC client.  I use	"irssi"
       (<>)	and my examples	will use "irssi" commands:

	   /connect localhost

       On connection, "twirc" will automatically join you to the configured
       channel.	 The default &twitter will be assumed, here.

       Your friends will be automatically joined to the	channel.  Friends who
       are also	followers are given voice as a visual clue.  In	"irssi"	they
       appear with plus	sign (+) in front of their names.

       To post a new status update, use	the "post" command:

	   post	My first tweet from twirc!

       In general, you enter a command followed	by its arguments, if any, as a
       public message in the channel.  There's a handy exception to that rule
       for sending replies.  An	entry that begins with a nick name, followed
       by a colon is treated as	a reply.  E.g.:

	   twirc: you make twitter usable!

       Is a shortcut for:

	   post	@twirc you make	twitter	usable!

       "twirc" uses the	Twitter	User Streams API to receive updates in real-

       Use IRC private messaging to send direct	messages.  In "irssi":

	   /msg	friend Watch out, I'm right behind you!

       The "twirc" server stops	when you disconnect.  This isn't normal	IRC
       behavior, but "twirc" isn't a normal IRC	server.	 Its only purpose is
       to interface with Twitter on your behalf	and server no useful purpose
       when you're not connected.

       post status
	   Post	a status update.  E.g.,

	       post Now	cooking	tweets with twirc!

       follow twitter_screen_name
	   Follow a new	Twitter	user.  This creates a friend relationship and
	   adds	the friend to the channel.

       unfollow	twitter_screen_name
	   Stop	following a Twitter friend. This destroys the friend
	   relationship	and removes the	friend from the	channel.

       block twitter_screen_name
	   Blocks the Twitter user from	receiving your Twitter feed.

       unblock twitter_screen_name
	   Stop	blocking a Twitter user.

       whois twitter_user
	   Displays information	about Twitter user. "twitter_user" can be
	   either a screen name	or email address.

       notify on|off twitter_screen_name...
	   Turns device	notifications on or off	for the	list of	one or more
	   Twitter friends.  The list is space separated.

       retweets	on|off twitter_screen_name...
	   Turns retweet display on your timeline on or	off for	the list of
	   one or more Twitter friends.	 The list is space separated.

       favorite	friend [ count ]
	   Mark	a friend's tweet as a favorite.	 Optionally, specify the
	   number of tweets to display for selection with "count". ("count"
	   defaults to 3. The default can be changed with the
	   "favorites_count" option.)

	   Displays information	about the remaining number of API requests
	   available in	the current hour. The "rate_limit_status" command does
	   not count against the limit,	itself.

	   Display a simple help message listing the available command names.

       If you're following a particularly noisy	friend,	you can	of course
       "unfollow" her.	Alternatively, you can use your	IRC client's features
       to ignore the user.  In "irssi":

	   /ignore LoudMouth ALL
	   /ignore -except -pattern @YourName LoudMouth	ALL

       Now, you	won't hear from	LoudMouth unless she @replies you, and she
       won't know you're ignoring her (unless she reads	this tip!).

   Multiple accounts
       Although	"twirc"	doesn't	currently support multiple accounts, there's
       nothing stopping	you from running multiple instances of "twirc",	one
       for each	account.

       Here's how I do it for accounts "semifor" (my personal account) and
       "twirc" ("twirc"'s feed for update notices, etc.).

       First, the pertinent sections of	the configuration files	(in YAML

	   # File: semifor.yml
	   irc_server_port: 6667
	   irc_password: secret
	   irc_channel:	'&twitter'

	   # File: twirc.yml
	   irc_server_port: 6668
	   irc_password: secret
	   irc_channel:	'&twirc'

       Next, start an instance for each	account:

	   bin/twirc -c	semifor.yml -b
	   bin/twirc -c	twirc.yml -b

       In your IRC client, connect to both instances ("irssi" here):

	   /connect localhost 6667 secret semifor
	   /connect localhost 6668 secret twirc

       Now you've got 2	channels, one for each account---in my case, &twitter
       for "semifor" and &twirc	for "twirc".

       Plugins are modules that	are optionally included	by specifying them in
       user configuration file in the "plugins"	section.  Some of the plugins
       included	in the distribution are:

	   Squashes whitespace in tweets to a single space. See

	   Commands are	prefixed with a	bang (i.e., exclamation	point "!").
	   Text	entered	without	a bang prefix is posted	as a status update.
	   See App::Twirc::Plugin::BangCommands.

       "Twirc" is free open source software with no warranty of	any kind.
       That said, it's used by some competent perl coders who may be able to
       help if you have	trouble.  Try the "#net-twitter" channel at

       The code	repository with	the development	branch is located at
       <>.  New features, and bug fixes appear
       there before they hit CPAN, so check the	commit log there to see	if a
       problem you've found has	been addressed.	 And feel free to use the
       development branch.

       Peter Roberts <>

       Marc Mims <>

       I'm "semifor" on	twitter	and IRC.

perl v5.32.1			  2015-03-31		 App::Twirc::Manual(3)


Want to link to this manual page? Use this URL:

home | help