Configuration¶

The configuration files are located on $HOME/.turses directory.

There is one mayor configuration file in turses:

config

contains user preferences: colors, bindings, etc.

An one default token file:

token

contains authentication token for the default user account

Each user account that is no the default one needs to be aliased and has its own token file alias.token.

To create an aliased account:

$ turses -a work

And, after authorizing turses to use that account, a token file named work.token will be created. Optionally you can create a work.config file for a configuration specific to that account.

Now, when you execute again:

$ turses -a work

you will be logged in with the previously stored credentials.

Here is an example with two accounts apart from the default one, aliased to alice and bob.

~
|+.turses/
| |-config
| |-alice.config
| |-token
| |-alice.token
| `-bob.token
|+...
|-...
`

If you want to generate a configuration file, you can do so executing:

$ turses -g /path/to/file

The configuration file is divided into sections, each of which is described below these lines.

Warning

The timelines section of the configuration has been deprecated, use sessions instead.

Sessions¶

The file with the session declarations is located on $HOME/.turses/sessions.

sessions is a ini-style configuration file in which each section represents the layout of a session. The defaults session is loaded when no other section is present.

Each section has only two options:

visible

contains the timelines that will be visible stacked in columns

buffers

contains the timelines that won’t be visible but will be loaded

Warning

The visible option must be present for any session but buffers is optional.

For each option, you will define the timelines as a comma-separated list of their names. Here is a list with the valid names:

home for the home timeline

mentions for the mentions timeline

favorites for the favorites timeline

messages for the direct message timeline

own_tweets for the timeline with your tweets

search:<query> for searching timelines

hashtag:<query> for searching a hashtag

user:<screen_name> for a user’s timeline

retweets_of_me for the timeline with your retweeted tweets

Declaring a custom session is as easy as defining a section on the sessions file. As an example, let’s define a session called interactions, in which we would only like to view our mentions, messages and what people are saying about turses; and load the home timeline in background:

[interactions]
visible = mentions, messages, search:turses, hashtag:turses
buffer = home

If you would like to load a session when starting turses, you must provide the name of the session as a command-line argument. You can start the session named interactions by executing:

$ turses -s interactions
# or, alternatively
$ turses --session interactions

Twitter¶

This section allows you to configure the settings related to the Twitter API.

turses communicates with Twitter over HTTPS by default but you can switch it off if you set it to false:

[twitter]
use_https = false

However, we recommend you to use HTTPS, especially in open WiFi networks where anybody could be sniffing packages and reading your personal information and communications.

The other available option is update_frequency which controls how often (in seconds) the timelines should be automatically updated.

An example configuration that updates the timelines every minute:

[twitter]
update_frequency = 60

Bindings¶

Almost every action within turses is configurable. The defaults resemble some of the bindings from the vi editor. To see an up-to-date description of all the available actions open the help buffer pressing ?.

An example configuration with the motion keys assigned to the arrow keys:

[bindings]
up = up
down = down
left = left
right = right

turses uses the representation of keystrokes provided by urwid to map the bindings to actions.

Colors¶

You can change the colors of different elements of the UI in turses. The legal values for colors are listed in the urwid wiki.

An example configuration that sets a magenta background and white foreground in the editor:

[colors]
editor = white
editor_bg = dark magenta

Styles¶

This section allows you to onfigure the styles for some of the UI elements in turses. Below is a description of all the configuration options in the section.

Templates¶

The templates allow you to configure how certain text is rendered in turses. The following templates are available:

header_template: The header of a tweet.
dm_template: The header of a direct message.
tab_template: The text in a tab.

This templates contain variables enclosed between braces that are replaced by their corresponding value. Let’s look at the defaults to see all the available variables within the templates:

[styles]
reply_indicator = ✉
retweet_indicator = ♻
header_template =  {username}{retweeted}{retweeter} - {time}{reply} {retweet_count}

username: The author of the tweet.
retweeted: The value of retweet_indicator if the status is a retweet.
retweeter: The name of the retweeter (if any).
time: Relative time of the tweet.
reply: The value of reply_indicator if the status is a reply.
retweet_count: The number of retweets.

Warning

The reply_indicator and retweet_indicator values will be surrounded with spaces.

[styles]
dm_template =  {sender_screen_name} => {recipient_screen_name} - {time}

sender_screen_name: The sender of the message.
recipient_screen_name: The recipient of the message.
time: Relative time of the message.

[styles]
tab_template = {unread} {timeline_name}

unread: Unread tweet count.
timeline_name: The name of the timeline.

Tweets¶

You can configure how tweets are rendered. By default the statuses are enclosed in a box, but you can use a divider instead.

Here’s how the default configuration for status styles looks like:

[styles]
box_around_status = true

If box_around_status is set to true, the tweets will be rendered as follows:

When setting box_around_status to false you can specify a divider character that will be printed below the statuses.

Warning

The box_around_status option has precedence over status_divider

[styles]
box_around_status = false
status_divider = false
status_divider_char = ─

This is how it looks like using ─ as a status divider:

Editor¶

You can also configure the position of the editor in the screen modifyng the editor_horizontal_align and editor_vertical_align options. The accepted values for this options are the following:

editor_horizontal_align: left, center or right
editor_vertical_align: top, middle or bottom

An example configuration with the editor positioned in the center of the screen:

[styles]
editor_horizontal_align = center
editor_vertical_align = middle

Here’s how it looks like:

Url format¶

You can choose how URLs are rendered tweaking the url_format option in the styles section. The following formats are available:

shortened: URL shortened by Twitter (e.g. t.co/foo)
original: Full original URL (e.g. http://example.com/)
display: Original URL with an ellipsis if it’s too long and trimming the

protocol prefix (e.g. example.com/a-very-long-⋯)

The default option is display. Here’s an example of a configuration option to display the full original URLs:

[styles]
url_format = original

User info window¶

When you are focusing a status and press i, turses will show a popup with information about the author of the status. At the bottom of the information widget the last statuses posted by the user are shown.

The number of statuses to display is configurable via the statuses_in_user_info parameter. By default, it shows three statuses but we can easily change that to show the last five:

[styles]
statuses_in_user_info = 5

Debug¶

The last section of the configuration is debug, which is intended for developers.

[debug]
logging_level = 3