BASIC CONFIGURATION 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 as .identicurse/config.json. 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. Important note: 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. Further note: 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. USING IDENTICURSE 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 the following: KEY ACTION 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. r Refresh. 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 favourites. /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 specified. /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 optional. /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 optional. /groupjoin [(!)group] (aliases: /gjoin, /gj) This will add you as a member of the group specified. The ! is optional. /groupleave [(!)group] (aliases: /gleave, /gl) This will remove you from membership of the group specified. The ! is optional. /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 # is optional. /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 you follow. /mentions (aliases: /replies) This will open a new tab showing notices that mention you. /public 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 string specified. /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 examples: /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. /quit 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 / command @ or no symbol username, unless it's a URL (see below) # tag ! group 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. ADVANCED CONFIGURATION Update interval: The "update_interval" config setting sets how long, in whole seconds, IdentiCurse should wait after an automatic refresh before starting the next automatic refresh. Notice limit: 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). Length override: 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, "length_override": 280 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. Filtering modes: 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. Colours: 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: "colours": { "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 notices themselves. "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 a pause. 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" Border: The "border" setting controls whether a border is drawn around the UI. The default is false (no border). UI order: 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: "ui_order": [ "divider", "entry", "divider", "notices", "statusbar", "tabbar" ] The valid UI elements you can use in this setting are as follows: ELEMENT DESCRIPTION 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. Tab enumeration: 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). Initial tabs: 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 username @NAME. @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 for QUERY. ?QUERY Same as search:QUERY. context:ID A context tab for the notice with id of ID. Aliases: 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". Key shortcuts: 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 follows: "keys": { "scrollup": ["k"], "scrolldown": ["j"], "refresh": ["l", "m"] } This would make k and j keybindings for scrolling up and scrolling down, respectively, and make *both* l and m keybindings for refreshing. The full range of keys you can set custom bindings for is as follows: KEYNAME ACTION 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. refresh Refresh. 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. Link opening: 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" Notice links: The "show_notice_links" config setting, if set to true (default false), adds the web UI link for each notice below it. Compact mode: 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). Show source: 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. Personalised slogans: 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 instead. OAuth: 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 http://identicurse.net/api_keys.json 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. COMMAND-LINE OPTIONS 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