Before using IdentiCurse, you can manually configure it with your
account login credentials. Alternatively, since 0.6, you can simply
start IdentiCurse, and let it walk you through a few questions to set
up a basic config for you. This will be saved in your home directory
If you would still rather do it manually (for example, if you would
like to configure some of the more advanced settings that the
automatic config doesn't touch), you can do so as follows:
Edit your config file in your favourite editor, changing
"username": "user" and "password": "test" to appropriate values.
To choose an instance of GNU Social change "api_path" to the API
home for the instance you wish to use.
IdentiCurse looks for your config file in two locations. First it
looks for config.json in .identicurse (a directory which is in your
home directory), and then it checks config.json in its installed
location. It is highly recommended, if you intend to manually edit
it, that you copy the supplied config.json (found in conf/ in the
tarball) to $HOME/.identicurse/ (create the directory first if it
doesn't exist yet) before modifying this copy, as that way future
updates (which *will* overwrite the original config.json with the
newest version) will not erase any customisation you have made.
Prior to version 0.8, config was stored in a file called .identicurse
in the home directory. This is no longer the case. However, you do not
have to do anything about this, as IdentiCurse will move the config
to the correct place automatically the first time you run it after
updating. This note is just so that you're aware that there has been
a change. If you have not used any versions prior to 0.8, you don't
need to worry about this section, it doesn't affect you.
Once you've configured IdentiCurse for your account, start it by
running the 'identicurse' command. You will see a message, "Welcome to
IdentiCurse!", and then after a short while, IdentiCurse itself will
load. Once you are at this screen, you can press various keys to do
1 Switch to tab 1 (initial tab: Personal Timeline).
2 Switch to tab 2 (initial tab: Mentions).
3 Switch to tab 3 (initial tab: DM Inbox).
4 Switch to tab 4 (initial tab: Public Timeline).
5 Switch to tab 5 (no initial tab).
6 Switch to tab 6 (no initial tab).
7 Switch to tab 7 (no initial tab).
8 Switch to tab 8 (no initial tab).
9 Switch to tab 9 (no initial tab).
< Switch to the previous tab.
> Switch to the next tab.
, Move the current tab one place to the left.
. Move the current tab one place to the right.
x Close the currently visible tab.
q Quit IdentiCurse.
h Open a tab that displays this README.
i Switch to input mode.
/ Do an in-page search.
: Go into insert mode with an initial / already present.
n Move to the next match for latest in-page search.
N Move to the previous match for latest in-page search.
l Followed by a number between 1 and 9,
quickly reply to that notice on the timeline.
d Reply to currently selected dent, full reply editable.
D Reply to currently selected dent, name of the user whose
dent you are replying to is added before posting.
f Favourite currently selected dent.
F Unfavourite currently selected dent.
e Repeat currently selected dent.
E Quote currently selected dent.
c View context for currently selected dent.
v View timeline of the user who posted the currently selected dent.
# Attempt to delete the currently selected dent.
s Move dent selection down (indicated by * character).
a Move dent selection up (indicated by * character).
z Move dent selection to the 1st in the tab (indicated by *).
Z Move dent selection to the last in the tab (indicated by *).
p Toggle the current tab's pause state.
P Toggle all tabs' pause states.
m Mute the entire conversation which the currently selected
dent is a part of.
M Unmute the entire conversation which the currently selected
dent is a part of.
L Toggle display of notice links (the URLs to the notices).
TAB or + Move to the next tab, or to the first if on the last.
Shift-TAB or - Move to the previous tab, or to the last if on the first.
UP or k Scroll up one line (in the current tab).
DOWN or j Scroll down one line (in the current tab).
PgUp or b Scroll up one screen (in the current tab).
PgDn or SPACE Scroll down one screen (in the current tab).
HOME or g Scroll to the top of the current page.
END or G Scroll to the bottom of the current page.
= Move to the newest page (in current timeline tab).
LEFT Move to a newer page (in current timeline tab).
RIGHT Move to an older page (in current timeline tab).
The secondary keys listed above are configurable, and the choices
listed are only the defaults. See the 'ADVANCED CONFIGURATION, Key
shortcuts' section for information on how to change them. Also note
that key shortcuts are case-sensitive - g indicates a press of the G
key without shift, G a press of it with shift.
In text entry mode, the above key shortcuts are not available.
Instead, you type a message directly into the text entry field, and
then press enter to submit. A plain message will simply be posted as a
normal dent, but you can also use various commands by starting the
message with a / (for example "/reply 1 Hello!" would trigger the
/reply command rather than post "/reply 1 Hello!" as a dent).
As of 0.7, there are multiple text entry modes. The standard one is
Input Mode, and this is the only one where commands work. Commands
will *not* work in Reply Mode and Quote Mode, and will instead be
posted exactly as entered. Reply Mode and Quote Mode both create
dents that are in context of their target dents, the only difference
is what text is initially present in the text entry.
Available commands are as follows:
/reply [notice number] [message] (aliases: /r)
This will create a reply to the notice in your current view with
the notice number specified. If your current tab is Directs or
Sent Directs, the reply will be sent as a DM.
/reply [(@)username] [message] (aliases: /r)
This will create a mention of the user specified. The username can
be entered with or without a @ at the beginning, either will work.
If your current tab is Directs or Sent Directs, the reply will be
sent as a DM.
/reply [notice number] (aliases: /r)
This will enter Reply Mode, with the notice indicated by your notice
number as its target notice.
/favourite [notice number] (aliases: /favorite, /fav, /f)
This will add the notice with the notice number specified to your
/unfavourite [notice number] (aliases: /unfavorite, /unfav, /unf)
This will remove the notice with the notice number specified
from your favourites.
/repeat [notice number] (aliases: /rt)
This will create a repeat of the notice with the notice number
/quote [notice number]
This will enter Quote Mode, with the notice indicated by your notice
number as its target notice.
/direct [(@)username] [message] (aliases: /dm, /d)
This will send a direct message to the user specified. As with
/reply, the username will work with or without the @.
/direct [post number] [message] (aliases: /dm, /d)
This will send a direct message to the user who sent the notice
or DM with the post number specified.
/delete [notice number] (aliases: /del)
This will delete the notice with the notice number specified. It
will only work for your notices, not those created by other users.
/user [notice number] (aliases: /u)
This will open a new tab showing the timeline of the user who
created the notice with the notice number specified.
/user [(@)username] (aliases: /u)
This will open a new tab showing the timeline of the user
specified. As with /reply and /direct, the @ is optional.
/context [notice number] (aliases: /c)
This will open a new tab showing the context of the notice with the
notice number specified. You can identify notices which have
context by the fact that their "from X" message has a [+] after it.
/subscribe [notice number] (aliases: /sub)
This will subscribe you to the user who created the notice with the
notice number specified.
/subscribe [(@)username] (aliases: /sub)
This will subscribe you to the user specified. The @ is optional.
/unsubscribe [notice number] (aliases: /unsub)
This will unsubscribe you from the user who created the notice with
the notice number specified.
/unsubscribe [(@)username] (aliases: /unsub)
This will unsubscribe you from the user specified. The @ is
/group [(!)group] (aliases: /g)
This will open a new tab showing the timeline of the group
specified. Much like the @ in username-based commands, the ! is
/groupjoin [(!)group] (aliases: /gjoin, /gj)
This will add you as a member of the group specified. The ! is
/groupleave [(!)group] (aliases: /gleave, /gl)
This will remove you from membership of the group specified. The !
/groupmember [(!)group] (aliases: /gmember, /gm)
This will check whether or not you are a member of the group
specified. The ! is optional.
/tag [(#)tag] (aliases: /t)
This will open a new tab showing the timeline of the tag
specified. Like the @ or ! in username-/group-based commands, the #
/home (aliases: /personal)
This will open a new tab showing your Home (a.k.a., Personal)
timeline: that is, notices only from you and people/groups
/mentions (aliases: /replies)
This will open a new tab showing notices that mention you.
This will open a new tab showing the public timeline, which
contains the 20 most recent notices from anyone on GNU Social.
/directs (aliases: /inbox)
This will open a new tab showing the direct messages other users
have sent to you.
/sentdirects (aliases: /outbox)
This will open a new tab showing the direct messages you have sent
to other users.
/favourites (aliases: /favorites, /favs, /fs)
This will open a new tab showing the direct messages you have added
to your favourites.
/search [query string] (aliases: /find, /?, /s)
This will open a new tab showing notices that contain the query
/block [notice number] (aliases: /b)
This will create a block against the user who created the notice
with the notice number specified. You can also add additional
notice numbers to block the users who created all of them.
/block [(@)username] (aliases: /b)
This will create a block against of the user specified. As usual,
the @ is optional. You can also add additional usernames to block
all of them.
/unblock [notice number] (aliases: /unb)
This will remove a block against the user who created the notice
with the notice number specified. You can also add additional
notice numbers to unblock the users who created all of them.
/unblock [(@)username] (aliases: /unb)
This will remove a block against of the user specified. As usual,
the @ is optional. You can also add additional usernames to
unblock all of them.
/spamreport [notice number] [reason] (aliases: /sr, /nuke)
This will submit a spam report dent in support's preferred format
and also create a block against the user who created the notice
with the notice number specified.
/spamreport [(@)username] [reason] (aliases: /sr, /nuke)
This will submit a spam report dent in support's preferred format
and also create a block against the user specified.
/link [link number] [notice number]
This will open the specified link (numbered starting from 1) from
the specified notice in your preferred browser, set in the config
file, falling back to xdg-open (which should open your default
browser) if you haven't got one specified in the config. You can
also use * as the link number to open all links in the notice.
There is also an alias for this: "/links [notice number]".
(See also 'ADVANCED CONFIGURATION, Link opening' section below.)
/link [notice number]
As above, but the first link in the notice is selected.
/mute [notice number]
Mutes the entire conversation to which the chosen notice belongs.
This means that any notice in the same conversation will never be
shown to you until/unless you unmute the conversation.
/unmute [notice number]
Removes muting from the entire conversation to which the chosen
notice belongs. The exact reverse of the above command.
/alias [alias] [command]
This will create the alias given as an alias for the command
given. For example:
/alias /me /user @psquid
This would make "/me" an alias for "/user @psquid"
The / before both the alias and the resultant command is optional,
as it will be added if it is not present. Therefore,
"/alias rpt repeat" and "/alias /rpt /repeat" do exactly the same.
/config [key] [value] (aliases: /set)
This will set the config item with the specified key to the
specified value. The key can also contain .s to indicate subkeys,
though so far only aliases require subkeys to configure.
Since this isn't such an intuitive command, here are some simple
/config aliases./x /delete
This would make /x an alias for the /delete command.
/config username test
This would set your logon username to "test". Note that this
particular key is only read in on startup, so changing
credentials this way would require a restart of IdentiCurse.
This will cause IdentiCurse to quit, exactly the same as if it
were quit using the q keybinding.
While in text entry mode, you can press tab to attempt to auto-complete the
word before the cursor, if it matches any of the following:
BEGINS WITH IDENTICURSE WILL TRY TO COMPLETE IT AS A
@ or no symbol username, unless it's a URL (see below)
For commands, all commands are known to IdentiCurse, so if it exists, it
can be tab-completed. For usernames, groups and tags, IdentiCurse keeps a
cache of all those that it has seen, so any that have not yet been used
during the current session will not be available. However, for usernames,
the "prefill_user_cache" setting can be set to true (it defaults to false),
which will have IdentiCurse, on start-up, fill the username cache with the
usernames of everyone you follow. This is somewhat slow, so it is not
recommended on slow connections.
The exception to this is that if the word before the cursor looks like a URL,
IdentiCurse will instead use the ur1.ca service to get a shortened version of
the URL, and replace it with that shorter URL.
There are two different matching modes for tab-completion, see the "Tab
Completion Modes" section of Advanced Configuration for more detail.
After submitting your message/command, you will be back in non-text
entry mode until you next press i. You can submit an empty text field
or press ESC to leave text entry mode without performing any action.
The "update_interval" config setting sets how long, in whole seconds,
IdentiCurse should wait after an automatic refresh before starting the
next automatic refresh.
The "notice_limit" config setting sets how many notices should be
fetched per page, on timeline types where the API allows choosing how
many notices to send (at the time of writing, most except public do).
The "length_override" config setting sets the minimum number of characters
that should be able to fit in the text entry box. So for example,
would always give a text entry box that can hold 280 characters or more.
In practice, it may well give, for example, 300 or so, since the last line
will still fill the entire available width, but it cannot give _less than_
280, so you will be guaranteed the amount you want.
This setting is mainly of use on unlimited-length instances, where the text
entry box would otherwise be set to 3 lines high, which may be far more or
far less than desired.
Tab completion modes:
The "tab_complete_mode" config setting is used to switch between two
tab completion modes. These are:
"exact", which will match only possibilities which start with exactly the
characters given. For example, "win" would match "wind", but not "gwin".
This is the default if the setting is not given.
"fuzzy", which will match anything where the characters given all appear in
the same order. For example, "wgo" would match "windigo", even though other
letters do appear. It would also match "mightywargod", since that still has
all the letters, even though it doesn't start with w.
The "filter_mode" config setting is used to switch between two filtering
modes. These are:
"plain", which will match occurences of exactly the strings present in
the "filters" config key.
"regex", which will match any notice whose text is matched by the strings
present in filters, interpreted as regular expressions.
To use colours, the config setting "enable_colours" must be set to
true. This will already be the case if you first started with version
0.6 or later. With only this setting set, a default set of colours
will be used. If you want to configure individual colours, you will
need to configure the "colours" setting, which uses this format:
"fieldname": ["fg_colour", "bg_colour"],
"fieldname": ["fg_colour", "bg_colour"],
"fieldname": ["fg_colour", "bg_colour"],
The possible field names are:
"statusbar" The status bar.
"tabbar" The tab bar, except the active tab.
"tabbar_active" The active tab.
"timelines" Any part of the timeline view not already dealt
with by the fields below.
"selector" The '*' current notice indicator.
"username" Usernames, both in notice details and within
"group" Groups within notices.
"tag" Tags within notices.
"time" Notice timestamps.
"source" Notice sources (e.g. 'from foo').
"notice_count" Notice numbers.
"notice" Notice text.
"profile_fields" Fields in user/group profiles.
"profile_values" Values in user/group profiles.
"search_highlight" Anything on the line of the currently
highlighted search result.
"notice_link" The links added when show_notice_links is enabled.
"warning" Any error/warning messages.
"pause_line" The line(s) indicating which dents come before/after
The possible colours differ depending on whether your system's curses
library can access 16-colour support or not. You can check by running
identicurse with the --colour-check command-line option.
For a sizable proportion of terminals, setting your TERM environment
variable to "xterm-256color" will give you full colour support.
As long as colour is supported at all, the following are usable:
"black", "red", "green", "brown", "blue", "magenta", "cyan",
"white", and "none" ("none" means that default terminal colours
should be used.)
If all 16 colours *are* supported, the following are also usable:
"grey", "light_red", "light_green", "yellow", "light_blue",
"light_magenta", "light_cyan", "light_white"
The "border" setting controls whether a border is drawn around the UI.
The default is false (no border).
The "ui_order" config setting allows you to place the various sections
of the UI in a different vertical order to default. It is in the format of
an array of strings, like so:
The valid UI elements you can use in this setting are as follows:
entry The text entry field, height determined by notice length.
notices The notice window. This will expand to fill all vertical
space not taken by other elements.
statusbar The status bar. One line high.
tabbar The tab bar. One line high.
divider An empty line, used for spacing. One line high.
Any duplicate elements (except dividers) or unrecognised element names will be
ignored, and any element types omitted entirely (again, except dividers) will
be added to the bottom. So for example, the example setting given above would
produce the same layout with or without the tabbar line, since the tab bar
would simply be added there since it was missing.
The "enumerate_tabs" config setting controls whether tabs are numbered. The
default is true (do display numbers). The numbers for tabs 1-9 correspond to
the keys that switch to those tabs (clarification: the keys still work
regardless of whether numbers are shown in the tab titles).
The tabs that are automatically loaded on startup can be configured by
editing the initial_tabs key. This key should contain tab names,
separated by vertical bars (|). The valid tab names are as follows:
home The personal timeline tab.
mentions The mentions tab.
direct The received direct messages tab.
sentdirect The sent direct messages tab.
public The public timeline tab.
favourites The favourites tab.
user:NAME A user timeline tab for the user with
@NAME Same as user:NAME.
tag:TAG A tag timeline tab for the #TAG tag.
#TAG Same as tag:TAG.
group:GROUP A group timeline tab for the !GROUP group.
!GROUP Same as group:GROUP.
help A help tab, the same as is opened when h
is pressed during use.
search:QUERY A search tab with results from searching
?QUERY Same as search:QUERY.
context:ID A context tab for the notice with id of ID.
In addition to the preset aliases, it is possible to add your own
custom aliases by editing the "aliases" record in your config
file. The preset aliases are stored in this way. and they are good
examples of how to correctly format an alias. It is not recommended
that you edit this section without a basic understanding of JSON
syntax (for a good basic introduction, we recommend CouchDB's JSON
Primer: < http://guide.couchdb.org/editions/1/en/json.html >).
Long notice handling:
When IdentiCurse encounters a notice that is too long to send to the
current instance, there are three paths it can take, based on the
current value of the long_dent config key:
1 - It simply does not send the notice, instead giving an
error indicating how many characters the maximum length
was exceeded by. This option is not recommended, as it
discards the original message, which must therefore be
rewritten from scratch. This will be chosen if long_dent
is set to "drop".
2 - The notice is semi-intelligently split into 2 or more
notices of sendable length. This will be chosen if
long_dent is set to "split".
3 - The notice is truncated, stopping immediately after the
last character that fits into the sendable length. This
will be chosen if long_dent is set to "truncate".
When you press a key, IdentiCurse first checks it against its built-in
keybindings, then against the bindings set in the config file (falling
back to the defaults if you don't have them set). The values to set
are all in the "keys" config key, and an example of the format
"refresh": ["l", "m"]
This would make k and j keybindings for scrolling up and
scrolling down, respectively, and make *both* l and m keybindings
The full range of keys you can set custom bindings for is as follows:
scrollup Scroll up one line.
scrolldown Scroll down one line.
pageup Scroll up one screen.
pagedown Scroll down one screen.
scrolltop Scroll right to the top of the current page.
scrollbottom Scroll right to the bottom of the current page.
firstpage Move to the newest page.
newerpage Move to a newer page.
olderpage Move to an older page.
input Go into input mode.
commandinput Go into input mode with an initial / already present.
quit Quit IdentiCurse.
closetab Close the current tab.
nexttab Move to the next tab.
prevtab Move to the previous tab.
tabswapleft Swap the current tab's place with the one to its left.
tabswapright Swap the current tab's place with the one to its right.
help Show the help.
search Start an in-page search.
qreply Start a reply to the notice with notice number
entered immediately after this key.
cfirst Move selected notice to first on current page.
clast Move selected notice to last on current page.
cnext Move selected notice down.
cprev Move selected notice up.
creply Reply to selected notice.
cfav Favourite selected notice.
cunfav Unfavourite selected notice.
crepeat Repeat selected notice.
ccontext View context for selected notice.
cuser View profile of user who posted selected notice.
creplymode Go into Reply Mode, with selected notice as target.
cquote Go into Quote Mode, with selected notice as target.
cdelete Delete selected notice.
nextmatch Move to next match for in-page search.
prevmatch Move to previous match for in-page search.
When opening a link, IdentiCurse will attempt to use your choice of
browser. This is set in the "browser" config key, and should be set as
the command to open a URL in the chosen browser, with '%s' instead of
the URL, for example:
"browser": "firefox '%s'"
(which would open URLs in Firefox)
GNU Screen users: If you are running IdentiCurse within GNU Screen,
the following sample configuration may prove useful. Suppose for
example that you want to open URLs/links using the Elinks text
browser. In this case the following configuration line should work:
"browser": "screen elinks %s"
The "show_notice_links" config setting, if set to true (default false),
adds the web UI link for each notice below it.
The "compact_notices" config setting determines whether to display
notices in a compact, single-line style (if set to true), or a slightly
less compact style (if set to false; this is the default).
The "show_source" config setting, which can be either true or false
(true by default), determines whether or not to show which client was
used to post each notice. The main use of this is to free up additional
screen space in compact mode.
If you'd rather use your own slogans instead of the built-in ones,
you'll need to create a file called .identicurse_slogans in your home
directory. In this file, you should place slogans, one per line. These
will then be displayed on starting IdentiCurse. The default slogans
will not be used in this case, so if there are any you want to keep,
you will need to add them to your slogans file.
Status bar slogans:
As of 0.9, slogans are displayed in the status bar when IdentiCurse is
idle. This is controlled by the "status_slogans" config setting, with
true (the default) setting them to be shown, and false setting them
not to be shown - the traditional "Doing nothing." status will be shown
If not enabled on first run, OAuth can be enabled at a later date using
the "use_oauth" config setting, which can be either true or false.
Additionally, the "oauth_token" and "oauth_token_secret" settings hold your
OAuth connection details if/when you have successfully used OAuth to connect.
To use OAuth with any instance, IdentiCurse should be registered with that
instance as an app, which will give it a consumer key/secret that identify
it to that instance as being IdentiCurse. As of version 0.10, IdentiCurse
will attempt to fall back to the OAuth "anonymous app" profile where
supported, allowing it to operate when no consumer key/secret is available.
If you are using a public instance not already added to that list, please
contact @psquid with the name of the instance, and IdentiCurse will be added
to it as a valid app, and the consumer key/secret added to the online store at
If you are using a private/single-user instance, we will not be able to
access it to register IdentiCurse as an app, so you will need to do so
yourself, and add the consumer key/secret to your config file manually,
in the "consumer_key" and "consumer_secret" settings, as listed above.
IdentiCurse takes the following command-line options:
-h, --help show the list of available options and exit
-c FILE, --config=FILE specify an alternative config file to use
-s FILE, --slogans=FILE specify an alternative slogans file to use
--colour-check check if system curses library can aceess colours,
and how many