coNnectUS User Guide

coNnectUS is a desktop Address Book application designed for NUS students to manage their contacts. It is optimized for use through a Command Line Interface (CLI) while retaining the benefits of a Graphical User Interface (GUI). If you type quickly, coNnectUS can help you manage contacts faster than traditional GUI applications.

Quick start

1. Ensure that Java 25 or later is installed on your computer.
   Mac users: Ensure you have the precise JDK version prescribed here.

2. Download the latest .jar file from here.

3. Copy the file to the folder you want to use as the home folder for your instance of coNnectUS.

4. Open a terminal, cd to the folder containing the JAR file, and run java -jar coNnectUS.jar.
   A GUI similar to the one below should appear in a few seconds. Note how the app contains some sample data.
   

5. Type a command in the command box and press Enter to execute it. For example, type help and press Enter to view the commands available.
   Some example commands you can try:

   • list : Lists all contacts.

   • add -n John Doe -p 98765432 -e johnd@example.com -a John street, block 123, #01-01 : Adds a contact named John Doe to the Address Book.

   • delete 3 : Deletes the 3rd contact shown in the current list.

   • clear : Deletes all contacts.

   • exit : Exits the app.

6. Refer to the Features section below for details of each command.

Features

Getting help: help

Displays a command reference in coNnectUS's result display area, including command formats, descriptions, examples where applicable, as well as a link to this User Guide.

• Scroll through the results area to view the built-in commands available for use.

Format: help

Sample Output (truncated):

Help Menu
========
help
    Displays this help menu.

add -n NAME -p PHONE_NUMBER -e EMAIL [-a ADDRESS] [-t TAG_CATEGORY TAG_NAME]...
    Adds a contact to the address book.
    Example: add -n John Doe -p 98765432 -e johnd@example.com -a 311, Clementi Ave 2, #02-25 -t others friends -t others owesMoney

list
    Displays all saved contacts.


... more commands ...

Alternative way getting help: the User Guide

Before we proceed with this step, ensure that you have a reliable internet connection.

An alternative to accessing this user guide is through the "User Guide" dialog, using the following steps:

1. With coNnectUS already open, click on User Guide on the top ribbon and select the button to trigger the User Guide dialog. Alternatively, you can press F1 on your keyboard.
   

2. Once the dialog appears, click on the Open User Guide button to open this User Guide with your configured default browser.
   

Note that if there are issues with your default browser, you would be prompted to click Copy URL instead and open it in a browser of your choosing.

Adding a contact: add

Adds a contact to the address book.

Format: add -n NAME -p PHONE_NUMBER -e EMAIL [-a ADDRESS] [-t TAG_CATEGORY TAG_NAME]...

Examples:

• add -n John Doe -p 98765432 -e johnd@example.com -a John street, block 123, #01-01
• add -n Betsy Crowe -t others friend -e betsycrowe@example.com -a Newgate Prison -p 1234567 -t others criminal
• add -n Jane Tan -p 87654321 -e janetan@example.com

Listing all contacts: list

Shows a list of all contacts in the address book.

Format: list

Editing a contact: edit

Edits an existing contact in the address book.

Format: edit INDEX [-n NAME] [-p PHONE_NUMBER] [-e EMAIL] [-a ADDRESS] [-t TAG_CATEGORY TAG_NAME]...

• Edits the contact at the specified INDEX. The index refers to the index number shown in the displayed contact list. The index must be a positive integer 1, 2, 3, ...
• At least one of the optional fields must be provided.
• Existing values will be updated to the input values.
• The new phone number or email address must not already be used by another contact.
• When editing tags, all of the contact's existing tags are removed; adding tags is not cumulative.
• To remove all of a contact's tags, enter -t without a tag after it.
• To remove a contact's address, enter -a without an address after it.
• Refer to Tagging a contact for more info on tags.

Examples:

• edit 1 -p 91234567 -e johndoe@example.com Edits the phone number and email address of the 1st contact to be 91234567 and johndoe@example.com respectively.
• edit 2 -n Betsy Crower -t Edits the name of the 2nd contact to be Betsy Crower and clears all existing tags.
• edit 3 -a Removes the address of the 3rd contact.

Locating contacts by criteria: find

Finds contacts in the address book matching the supplied criteria.

Format: find [-n NAME] [-p PHONE_NUMBER] [-e EMAIL] [-a ADDRESS] [-t TAG_CATEGORY TAG_NAME]...

• At least one criterion must be specified.
• Multiple tags can be supplied, but other parameters (name, phone, email, address) may only be specified once.
• Every criterion supplied must match to find a contact.
• Search criteria are case-insensitive. For example, -n hans matches -n Hans.
• Contacts are matched if the search criterion is a substring of the actual field; for example -n John matches John and Johnny.
• For tag criteria, both a valid category (i.e. module, faculty or others) and the tag name must be supplied.
• Refer to Tagging a contact for a list of valid tag categories.

Examples:

• find -n john returns John, Johnny.
• find -e alice returns alice@example.com, alicelow@gmail.com
• find -p 92 returns 92005000, 88922301
• find -t others Friend -t faculty Computing returns contacts who have both tags.
  

Deleting a contact or multiple contacts: delete

Deletes either the specified contact (based on list index), or removes all instances of the specified tags and deletes contacts with no remaining tags.

Format: delete INDEX | delete -t TAG_CATEGORY TAG_NAME...

Index-based deletion:

• Deletes the contact at the specified INDEX.
• The index refers to the index number shown in the displayed contact list.
• The index must be a positive integer 1, 2, 3, ...

Tag-based deletion:

• Removes matching tags from each tagged contact. Retains the contact if any tags remain; otherwise, deletes it.
• One or more tags can be specified.
• Matching contacts not displayed in the active filter can still be deleted, or have their tags removed.
• Tag categories and tag names are compared case-insensitively.

Examples:

• list followed by delete 2 deletes the 2nd contact in the address book.
• find -n Betsy followed by delete 1 deletes the 1st contact in the results of the find command.
• delete -t faculty Science removes the faculty tag Science from all contacts that have it. Contacts that have only faculty tag Science originally are deleted.
• delete -t module TJ3000 -t others Badminton removes the module tag TJ3000 and the others tag Badminton from all contacts that have it. Only contacts that originally had either or both of the following tags, will be deleted.
  • TJ3000 tag of the "module" category.
  • Badminton tag of the "others" category.

Pinning and unpinning a contact

Contacts can be pinned to be displayed on top of unpinned contacts, and unpinned to be displayed amongst unpinned contacts.

Format: pin INDEX, unpin INDEX

• Pins the contact at the specified INDEX.
• The index refers to the index number specified in the displayed contact list (either using find or list).
• Regardless of sort order, a pinned contact will always appear on top of an unpinned contact.
• The index must be a positive integer.
  • If using pin, the contact specified at INDEX must be an unpinned contact.
  • If using unpin, the contact specified at INDEX must be a pinned contact.

Examples:

• list followed by pin 3 pins the 3rd contact in the address book.
• find -n Bob followed by pin 5 pins the 5th contact in the results of the find command.
• find -e mary@gmail.com followed by unpin 1 unpins the 1st contact in the results of the find command.

Sorting contacts

Contacts can be sorted according to some attributes, such as their name.

Format: sort (name | email | phone) (asc | desc)

• Attribute for sorting and sorting order are not case-sensitive (sort nAmE dEsC has the same effect as sort name desc).
• The specified sorting order is retained after contacts are added/edited - the sort will be automatically reapplied.
• Currently supported attributes for sorting:
  • Name (Ascending = A-Z, Descending = Z-A).
  • Email (Ascending = A-Z, Descending = Z-A).
  • Phone (Ascending = Smaller numbers first, Descending = Larger numbers first).

Examples:

• sort name desc sorts the contacts by their name, in reverse alphabetical order (Z-A).
• sort phone asc sorts the contacts by their phone number, displaying smaller phone numbers first

Tagging a contact

Tags can be added to a contact through the Edit or the Add commands.

The following tag categories are supported, with each category being assigned a unique color code:

• module
• faculty
• others

Tag categories are not case-sensitive.

• add ... -t OTHERS friend has the same effect as add ... -t oThErS friend.

A contact can only have a maximum of 5 unique tags.

• A tag is unique if the contact does not have another tag with the same category and case-insensitive tag name
• For example: add ... -t others FrIenD -t others friend adds a contact with only 1 tag, while add ... -t others friend -t module friend adds a contact with 2 tags.

Clearing all entries: clear

Clears all entries from the address book.

Format: clear

Undoing a change: undo

Reverses the most recent command that changed your contact list.

Format: undo

• Commands that can be undone: add, edit, delete, clear, pin, unpin, import, sort.
• Other commands, such as list, find, theme and alias, are skipped. undo reverses the most recent command that changed your contact list.
  • Using undo after a sort restores the previous sorting criteria, even if the contact list itself was unchanged.
• You can use undo several times in a row to reverse earlier changes one at a time.
• After an undo, all contacts are shown, with pinned contacts at the top.
• The undo history is cleared when you close coNnectUS.

Examples:

• delete 2 followed by undo brings back the deleted contact.
• pin 1, edit 3 -n John Doe, then undo twice reverses the edit and then the pin.

Redoing an undone change: redo

Reapplies the most recent change that was reversed by undo.

Format: redo

• You can use redo several times in a row to reapply undone changes one at a time, in the order they were made.
• Making a new change after an undo (e.g. add, edit or delete) clears the redo history, so the undone changes can no longer be redone.
• Commands that do not change your contact list, such as list and find, do not clear the redo history.
• After a redo, all contacts are shown, with pinned contacts at the top.

Examples:

• delete 2, undo, then redo deletes the contact again.
• delete 2, undo, add -n Jane Tan -p 87654321 -e janetan@example.com, then redo shows an error, because adding Jane Tan cleared the redo history.

Importing contacts: import

Imports contacts from a JSON address book file and merges them into the current address book.

Format: import -f FILE_PATH

• FILE_PATH is the path to a JSON address book file.
• If FILE_PATH contains a word starting with - (e.g. contacts -backup.json), wrap the whole path in double quotes.
• FILE_PATH must not contain double quotes other than the surrounding pair.
• Contacts with the same phone number or email address as an existing contact are skipped.
• Imported contacts are added to the current address book; existing contacts are not replaced.
• The command displays the number of imported and skipped contacts.
• The imported contacts can be removed using undo.

Example:

• import -f data/exports/contacts.json
• import -f "data/exports/contacts -backup.json"

Exporting contacts: export

Exports contacts that match the specified criteria to a JSON file.

The exported file is saved in the data/exports folder. The .json file extension is added automatically.

Format: export -f FILENAME [-n NAME] [-p PHONE_NUMBER] [-e EMAIL] [-a ADDRESS] [-t TAG_CATEGORY TAG_NAME]...

• FILENAME must contain only alphanumeric characters and spaces.
• FILENAME must begin with an alphanumeric character and cannot exceed 100 characters.
• Do not include the .json file extension in FILENAME.
• If no filtering criteria is provided, all contacts present in coNnectUS at that point of time are exported by default.
• Multiple criteria can be specified. A contact must match every specified criterion to be included in the export.
• If a file with the same name already exists, it will be overwritten.
• Exporting contacts does not modify the contacts in coNnectUS and cannot be undone.

Examples:

• export -f contacts exports all contacts to data/exports/contacts.json.
• export -f filtered-contacts -n Alice -e example.com exports contacts whose names contain Alice and whose email addresses contain example.com.

Changing the theme: theme

Switches coNnectUS between a dark theme (true black, which saves power on OLED screens) and a light theme (white).

Format: theme dark | theme light

• The theme name is not case-sensitive. For example, theme LIGHT works the same as theme light.
• You can also click the Dark / Light button at the right end of the menu bar to switch to the other theme.
• The User Guide window changes to the same theme.
• coNnectUS remembers your theme and opens with it the next time you start the app. The first time you start the app, it opens in the dark theme.

Examples:

• theme light switches to the light theme.
• theme dark switches back to the dark theme.

Adding an alias: alias

Creates an alternative command word for a built-in command, allowing you to customize and use more memorable and intuitive commands.

Format: alias COMMAND_WORD ALIAS_TO_SET

• COMMAND_WORD must be an existing built-in command, written in lowercase, such as find, add or list.

• ALIAS_TO_SET must contain only English/ASCII lowercase and uppercase letters (a-z, A-Z). Numbers, spaces and special characters are not allowed.

• There is no maximum length imposed for aliases, giving you the flexibility to choose alias names that suit your needs. For convenience's sake, we recommend choosing an alias that is:

  • shorter than the original command such as f or fd for find; or
  • easy to associate with the command, such as search for find.
    
    

• Aliases are case-sensitive. For example, f and F are different aliases and associating each of them with distinct commands is allowed.

• An alias cannot conflict with an existing built-in command, regardless of letter case. For example, neither list nor LIST, which exists as a registered command word can be used as an alias.

• An alias must not already be registered. To reassign an existing alias to a new command word, delete it first using delete_alias.

• You can register multiple aliases for the same built-in command.

• An alias only replaces the command word. The command word's associated parameter(s) and parameter value(s) are still necessary. E.g.,

  alias find f                   # registers "f" as an alias for the "find" command
  f -n James -t others friend    # runs the find command with the relevant search criteria
  

• The original command word remains usable after an alias is added.

• The list of aliases is viewable using the list_alias command.

Examples:

• alias find f allows you to use f -n James instead of find -n James.
• alias list ls allows you to use ls instead of list.
• alias delete del allows you to use del 3 instead of delete 3.

List all available aliases: list_alias

Displays all registered aliases, grouped by corresponding built-in command.

Format: list_alias

• If no aliases have been registered, a message indicating this will be displayed.

Example:

• After running alias find f, alias list l and alias list ls, entering list_alias displays the following mappings. Their order may vary.

  Registered alias(es):
  find: f
  list: l, ls
  

Deleting an alias: delete_alias

Removes a registered alias.

Format: delete_alias ALIAS_TO_DELETE

• ALIAS_TO_DELETE must be an existing alias, with the same letter-case used when it was registered.

• Deleting an alias does not remove its corresponding built-in command or any other aliases corresponding to that command.

• To change the command associated with an alias (as shown in the example below), or edit an alias corresponding to a particular command, delete the alias and then re-register it again.

  alias edit e        # registers "e" as an alias for the "edit" command
  e 1 -n John Cena    # use "e" to rename first contact in the current displayed list
  delete_alias e      # removes the alias "e", so that it can be reassigned
  alias exit e        # registers "e" as an alias for a different command, "exit"
  e                   # exits coNnectUS
  

Examples: Assume that the alias f is registered to the built-in command, find.

• delete_alias f removes the alias f. You can still use the original find command thereafter.
• delete_alias f followed by alias list f reassigns f to the list command.

Transferring aliases to another computer

The alias data file is located at data/aliases.json, relative to coNnectUS's home folder.

To transfer your saved aliases to a new computer:

1. Close the coNnectUS application on your old computer.
2. On your old computer, open the data folder inside your coNnectUS home folder and copy aliases.json.
3. On your new computer, download coNnectUS and place the JAR file in your preferred folder. This is known as your coNnectUS home folder.
4. Create a data folder within the home folder and then paste the copied aliases.json into the data folder.
5. Start coNnectUS on your new computer and enter list_alias to verify that your aliases have been transferred successfully.

Exiting the program: exit

Exits the program.

Format: exit

Saving the data

Data is saved automatically by coNnectUS after every successful command that modifies the contact list. You do not need to save manually.

Your window size, window position and theme are saved in [JAR file location]/preferences.json when you close the app.

Editing the data file

The address book application data is saved automatically as a JSON file [JAR file location]/data/addressbook.json. Advanced users are welcome to update data directly by editing that data file.

FAQ

Q: How do I transfer my data to another computer?
A: Install the app on the other computer and overwrite the data file it creates with the data file from your previous coNnectUS home folder.

Known issues

1. When using multiple screens, if you move the application to a secondary screen, and later switch to using only the primary screen, the GUI will open off-screen. The remedy is to delete the preferences.json file created by the application before running the application again.
2. If you minimize the User Guide Window and then use the User Guide menu, or the keyboard shortcut F1 again, the original User Guide Window may remain minimized, and no new User Guide Window will appear. The remedy is to manually restore the minimized User Guide Window.

Command summary