User Guide

CLI-Tacts is a lightweight application to manage your CS2040S students! It is optimised for Command Line Interface usage (CLI), while having the benefits of a Graphical User Interface (GUI). The best of both worlds, quickness of a CLI and visualisation of a GUI! For fast typers, CLI-Tacts helps you optimise your workflow better than traditional GUI-only grading portals.

The primary users are CS2040S Teaching Assistants who:

• Quick start
• Features
  • Viewing help : help
  • Adding a person: add
  • Listing all persons : list
  • Editing a person : edit
  • Locating students by name, tutorial group, email, or telegram handle: find
    • Name (n/) filter
    • Tutorial group (t/) filter
    • Email (e/) filter
    • Telegram handle (th/) filter
    • Combined filters
  • Deleting a person : delete
  • Marking attendance : mark
    • Mark one student (by index)
    • Mark multiple students (by indices)
    • Mark all students in a tutorial group
    • Notes
    • Attendance tracking
  • Unmarking attendance : unmark
    • Important notes:
  • Clearing all entries : clear
  • Exiting the program : exit
  • Attendance Statistics Panel
    • What it shows
    • What to expect
  • Exporting student data : export
    • CSV file format
    • Notes
  • Saving the data
  • Editing the data file
  • Archiving data files [coming in v2.0]
• FAQ
• Known issues
• Command summary

Quick start

1. Ensure you have Java 17 or above installed in your Computer.
   Mac users: Ensure you have the precise JDK version prescribed here.

2. Download the latest CLI-Tacts .jar file from your module team or release page.

3. Copy the file to the folder you want to use as the home folder for CLI-Tacts.

4. Open a command terminal, cd into the folder you put the jar file in, and use the java -jar CLI-tacts.jar command to run the application.
   A GUI similar to the below should appear in a few seconds. Note how the app contains some sample data.
   

5. Type the command in the command box and press Enter to execute it. e.g. typing help and pressing Enter will open the help window.
   Some example commands you can try:

   • list : Lists all contacts.

   • add n/John Doe i/A0123456X e/johnd@u.nus.edu p/98765432 th/@johndoe t/T01 : Adds student John Doe to CLI-Tacts.

   • mark 1 w/1 : Marks the first student’s attedance for week 1.

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

   • clear : Deletes all contacts.

   • exit : Exits the app.

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

Features

Viewing help : help

Shows a message explaining how to access the help page.

Format: help

Adding a person: add

Adds a student to CLI-Tacts. Telegram handle is optional (useful for contacting students quickly, but not required).

Format:

add n/NAME i/STUDENT_ID e/EMAIL p/PHONE_NUMBER [th/TELE_HANDLE] t/TUTORIAL_GROUP

Where:

• NAME should only contain alphanumeric characters, spaces, hyphens (-), commas (,), and apostrophes (')
• STUDENT_ID must start with an a or A, followed by 7 digits and end with 1 letter. (e.g. A0123456X).
• EMAIL must be a valid NUS email ending with @u.nus.edu (e.g. alice@u.nus.edu)
• PHONE_NUMBER must be exactly 8 digits
• TELE_HANDLE (optional) must be a valid Telegram handle that starts with @ and has 5 to 32 characters.
• TUTORIAL_GROUP follows a strict format that starts with T followed by exactly 2 digits (e.g. T01, T12)
• TUTORIAL_GROUP is case-sensitive (T01 is valid, t01 is invalid)

Notes for add arguments:

• EMAIL matching/validation is case-insensitive for the local-part and domain (same behavior as find e/)
• TELE_HANDLE matching/validation is case-insensitive and handles are stored in lowercase (same behavior as find th/)

Examples:

• add n/Amy Bee i/A0123456X e/amy@u.nus.edu p/11111111 th/@amy_bee t/T01
• add n/Bob Chan i/A0765432Y e/bobchan@u.nus.edu p/99998888 th/@bobchan t/T02

Listing all persons : list

Shows a list of all students currently in CLI-Tacts.

Format: list

Editing a person : edit

Edits an existing student in CLI-Tacts.

Format:

edit INDEX [n/NAME] [i/STUDENT_ID] [e/EMAIL] [p/PHONE] [th/TELE_HANDLE] [t/TUTORIAL_GROUP]

• Edits the student at the specified INDEX. The index refers to the index number shown in the displayed student 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.
• STUDENT_ID, EMAIL, PHONE, TELE_HANDLE and TUTORIAL_GROUP are validated with the same rules as in add.

Examples:

• edit 1 p/91234567 e/alice_new@u.nus.edu Edits the phone number and email address of the 1st student.
• edit 2 t/T03 Moves the 2nd student to tutorial group T03.

Locating students by name, tutorial group, email, or telegram handle: find

Allows a TA to filter the student list to find specific individuals based on their name, tutorial group, NUS email, or Telegram handle. This is useful when the matric number (student ID) is not immediately known.

Formats:

• find n/NAME_KEYWORD [MORE_KEYWORDS]...
• find t/TUTORIAL_GROUP
• find e/EMAIL
• find th/TELE_HANDLE
• You can combine any of the above prefixes in one command (e.g. find n/john t/T01 e/alice@u.nus.edu th/@alice_bot).

At least one of n/, t/, e/, or th/ must be present.

Name (n/) filter

• Words after n/: you can type one or more words separated by spaces. Each word is a prefix checked against the student’s full name (first name, last name, etc.); every word you type must match some name part. Letter case does not matter.
• With tutorial group: use t/ in the same command when you also want to filter by group (e.g. find n/John t/T01).

If an invalid name keyword is supplied, CLI-Tacts shows an error similar to:

Invalid name! Search terms should only contain alphanumeric characters, spaces, hyphens (-), commas (,), and apostrophes (‘) only.

Example after applying find n/Ale:

Tutorial group (t/) filter

• Input restrictions: same format and case-sensitivity rules as TUTORIAL_GROUP in add / edit.

If an invalid tutorial group is supplied, CLI-Tacts shows an error similar to:

Invalid tutorial group. Format should be T followed by two digits (e.g., T01).

Example after applying find t/T02:

Email (e/) filter

• Input restrictions: same format and case-sensitivity rules as EMAIL in add / edit.
• Prefix matching: the value after e/ is treated as a prefix match on email (case-insensitive).
  For example, find e/Cha can match charlotte@u.nus.edu.

Example after applying find e/Cha:

Telegram handle (th/) filter

• Input restrictions: same format and case-sensitivity rules as TELE_HANDLE in add / edit.
• Prefix matching: the value after th/ is treated as a prefix match on Telegram handle (case-insensitive).
  For example, find th/@ro can match @roybala.

Example after applying find th/@ro:

Combined filters

• When multiple filters are present, CLI-Tacts returns students who match all specified filter categories (AND across n/, t/, e/, th/).
• On success, the status bar shows e.g. 5 persons listed! and the list shows only matching students.
• If no students match, the list becomes empty and the status shows 0 persons listed!.

Examples:

• find n/j — finds students whose name has a part starting with j.
• find n/John — finds students whose name has a part starting with John.
• find n/John Do — finds students whose name has a part starting with John and a part starting with Do.
• find t/T01 — finds all students from tutorial group T01.
• find e/alice@u.nus.edu — finds the student with that email (if present).
• find th/@benson_meier — finds the student with that Telegram handle (if present).
• find n/Tan — finds students whose name has a part starting with Tan.
• find n/john t/T01 — finds students whose name matches john and who are in tutorial group T01.

Deleting a person : delete

Deletes the specified student from CLI-Tacts.

Format: delete INDEX

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

Examples:

• list followed by delete 2 deletes the 2nd person in the address book.
• find n/Betsy followed by delete 1 deletes the 1st person in the results of the find command.

Marking attendance : mark

CLI-Tacts supports three ways to mark attendance for a given week (positive integer, typically 1–13):

Mark one student (by index)

Format: mark INDEX w/WEEK

• INDEX is the position in the currently displayed student list (list, find, …).
• Use this when you want to mark a specific row. Running mark again for the same student and same week will show an error.

After a successful mark, the list filter resets to show everyone again.

Mark multiple students (by indices)

Format: mark INDEX1 INDEX2 ... w/WEEK

• Provide two or more space-separated indices from the currently displayed student list.
• Students already marked for that week are skipped (no error). The result message states how many were updated and how many were already recorded.
• Duplicate indices are counted only once (the duplicate is treated as already-recorded).
• If any index is out of bounds, CLI-Tacts shows an error and no attendance is changed.

Mark all students in a tutorial group

Format: mark t/TUTORIAL_GROUP w/WEEK

• TUTORIAL_GROUP uses the same T + two digits rule as in add / edit / find (e.g. T01, T12).
• Applies to every student stored with that tutorial group, not only those visible after a find.
• Students already marked for that week are skipped (no error). The result message states how many were updated and how many were already recorded.
• If no student has that tutorial group, CLI-Tacts shows an error.

Notes

• Attendance updates and saving happen immediately after the command succeeds.
• For the index forms, use find (or list) first if you need a smaller list before choosing indices.

Examples (single student):

• mark 1 w/2 — marks the 1st student in the displayed list for week 2.
• find n/John followed by mark 1 w/1 — among students named “John” in the filtered list, marks the 1st for week 1.
• find t/T01 followed by mark 3 w/4 — in the T01-only list, marks the 3rd student for week 4.

Examples (multiple students):

• mark 1 2 3 w/5 — marks students at positions 1, 2, and 3 in the displayed list for week 5.
• find t/T01 followed by mark 1 2 w/3 — in the T01-filtered list, marks the 1st and 2nd students for week 3.

Example (whole group):

• mark t/T02 w/2 — marks all students in tutorial group T02 for week 2.

Attendance tracking

Attendance is stored per week. Each week can be marked at most once per student. The single-index form shows an error if you repeat the same week for the same student. The multiple-index and group forms skip already-marked students and report counts instead.

Unmarking attendance : unmark

Unmarks a student’s attendance for a specific week during a tutorial session.

Formats:

• unmark INDEX w/WEEK
• unmark t/TUTORIAL_GROUP w/WEEK

Where:

• INDEX refers to the index number shown in the displayed student list and must be a positive integer 1, 2, 3, …​
• WEEK is the week number to unmark attendance for and must be a positive integer
• TUTORIAL_GROUP must be T followed by exactly 2 digits (e.g., T01, T12)

Important notes:

• If the student is already unmarked for the specified week, CLI-Tacts will show an error.
• For group unmark, t/ is required (e.g., unmark t/T01 w/2).
• Group unmark errors if there are no students in the specified tutorial group, or if all students are already unmarked for that week.

Examples:

• unmark 1 w/2 — unmarks the 1st student in the displayed list for week 2.
• unmark t/T01 w/4 — unmarks attendance for all marked students in tutorial group T01 for week 4.

Clearing all entries : clear

Clears all entries from CLI-Tacts.

Format: clear

Exiting the program : exit

Exits the program.

Format: exit

Attendance Statistics Panel

The Attendance Statistics Panel is displayed at the bottom of the main window and updates automatically whenever the student list changes (e.g. after a mark, unmark, add, delete, or find command).

What it shows

What to expect

• A value of 0% for a week means no student in that group has been marked present yet — this is the default before any mark command is run.
• The panel reflects the currently filtered list. If you use find to narrow down to a subset of students, the statistics will update to reflect only those students.
• The panel scrolls horizontally if the window is too narrow to show all 13 weeks at once.

Exporting student data : export

Exports all student data to a CSV file named export.csv in the same folder as the JAR file.

Format: export

CSV file format

The file contains one header row followed by one row per student:

Notes

• The export always includes all students in the address book, regardless of any active find filter.
• If export.csv already exists in the folder, it will be overwritten.
• All string fields are wrapped in double quotes in the CSV output.

Example output (export.csv):

Student,StudentID,Email,Tutorial,Week1,Week2,...,Week13
"Alice Pauline","A0123456A","alice@u.nus.edu","T01",1,0,0,0,0,0,0,0,0,0,0,0,0
"Benson Meier","A0123456B","johnd@u.nus.edu","T02",0,0,0,0,0,0,0,0,0,0,0,0,0

Saving the data

CLI-Tacts data are saved in the hard disk automatically after any command that changes the data. There is no need to save manually.

Editing the data file

CLI-Tacts data are 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.

Caution: If your changes to the data file make its format invalid, CLI-Tacts will discard all data and start with an empty data file at the next run. Hence, it is recommended to take a backup of the file before editing it.
Furthermore, certain edits can cause CLI-Tacts to behave in unexpected ways (e.g., if a value entered is outside of the acceptable range). Therefore, edit the data file only if you are confident that you can update it correctly.

Archiving data files [coming in v2.0]

Details coming soon …

FAQ

Q: How do I transfer my data to another Computer?
A: Install the app in the other computer and overwrite the empty data file it creates with the file that contains the data of your previous CLI-Tacts 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 Help Window and then run the help command (or use the Help menu, or the keyboard shortcut F1) again, the original Help Window will remain minimized, and no new Help Window will appear. The remedy is to manually restore the minimized Help Window.

Command summary