User Guide

Mate is a desktop app that helps users quickly find the right hackathon teammates by surfacing peers based on skills and proficiency. With a simple CLI-first interface and color-coded skill tags, users can instantly discover, connect, and form balanced teams without wasting time on endless networking.

Mate is designed for hackathon participants across the technical spectrum — from developers, designers, and data scientists to product managers, domain experts, and non-technical contributors (e.g. UX, marketing, business). It serves students and professionals who value fast, pragmatic workflows.

• Quick start
• Features
  • Field constraints
  • Viewing help : help
  • Listing all persons : list
  • Clearing all entries : clear
  • Exiting the program : exit
  • Adding a person: add
  • Locating persons : find
  • Deleting a person : delete
  • Editing a person : edit
  • Adding skills to a person : addSkill
  • Removing a skill from a person : removeSkill
  • Adding an interested hackathon to a person : addHackathon
  • Removing an interested hackathon from a person : removeHackathon
  • Listing all teams : listTeam
  • Creating a team : createTeam
  • Deleting a team : deleteTeam
  • Adding a person to a team : addToTeam
  • Removing a person from a team : removeFromTeam
  • Saving the data
  • Editing the data file
• 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 .jar file from here.

3. Copy the file to the folder you want to use as the home folder for Mate.

4. Open a command terminal, cd into the folder you put the jar file in, and use the java -jar mate.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 persons.

   • listTeam : Lists all teams.

   • add n/John Doe e/johnd@example.com t/JohnTG g/JohnGH : Adds a contact named John Doe to Mate.

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

   • createTeam tn/Development Team h/Hackathon 2024 p/1 p/2 : Creates a team with the first two contacts as members.

   • exit : Exits the app.

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

Features

Field constraints

This table summarises the input restrictions for each field in Mate:

• All fields cannot be empty.
• Fields with leading or trailing spaces will have the spaces trimmed automatically.
• Fields are case-insensitive unless otherwise specified.

Viewing help : help

Shows a message explaining how to access the help page.

Format: help

Listing all persons : list

Shows a list of all persons in Mate.

Format: list

Clearing all entries : clear

Clears all entries from Mate.

Format: clear

Warning: This action is irreversible! All persons and teams will be permanently deleted. Make sure to back up your data file before clearing if you might need it later.

Exiting the program : exit

Exits the program.

Format: exit

Adding a person: add

Adds a person to Mate.

Format: add n/NAME e/EMAIL t/TELEGRAM_NAME g/GITHUB_NAME [sk/SKILL[:LEVEL]]…​ [h/HACKATHON]…​

• Skills are displayed with color-coded backgrounds: Beginner (Green), Intermediate (Blue), Advanced (Purple).
• Skills are sorted by level (Advanced → Intermediate → Beginner), then alphabetically.
• HACKATHON entries are added to the person’s interested hackathons.
• Duplicate skills or hackathons are not allowed.
• See Field Constraints for input requirements.

Examples:

• add n/John Doe e/johnd@example.com t/JohnTG g/JohnGH
• add n/Alice e/alice@example.com t/alice_tg g/alice123 sk/docker h/TechChallenge
• add n/Betsy Crowe e/betsycrowe@example.com t/Betsygram g/Betsy03 sk/c#:Intermediate sk/java:Advanced h/NUSHack h/iNTUition

Locating persons : find

Finds persons who match all the given keywords.

Format: find k/KEYWORD [k/MORE_KEYWORDS]…​

• Searches across name, email, Telegram, GitHub, skills, and hackathons.
• Returns persons matching all keywords (AND search).
• Partial matching is supported (e.g. NUS matches NUSHack and NUS TechJam).
• See Field Constraints for input requirements.

Examples:

• find k/John returns persons with name john or John Doe, or email john@example.com, or Telegram john123
• find k/java k/python returns persons that have both java AND python as skills.
• find k/AI Hackathon 2024 returns persons interested in or participating in hackathons containing AI Hackathon 2024

Deleting a person : delete

Deletes the specified person from Mate.

Format: delete p/INDEX

• Deletes the person at the specified INDEX.
• See Field Constraints for index requirements.

Examples:

• list followed by delete p/2 deletes the 2nd person in the displayed list.
• find k/Betsy followed by delete p/1 deletes the 1st person in the results of the find command.

Editing a person : edit

Edits an existing person’s contact details in Mate.

Format: edit p/INDEX [n/NAME] [e/EMAIL] [t/TELEGRAM_NAME] [g/GITHUB_NAME]

• At least one of the optional fields must be provided.
• Existing values will be updated to the input values.
• See Field Constraints for input requirements.

Tip: Use dedicated commands to manage skills (addSkill, removeSkill) and hackathons (addHackathon, removeHackathon).

Examples:

• edit p/2 n/Betsy Crower edits the name of the 2nd person in the displayed list to Betsy Crower.
• edit p/1 e/johndoe@example.com t/johndoe_tg edits the email address and Telegram name of the 1st person in the displayed list.

Adding skills to a person : addSkill

Adds one or more skills (with optional levels) to a person.

Format: addSkill p/INDEX sk/SKILL[:LEVEL] [sk/SKILL[:LEVEL]]...

• If the skill already exists, it will be upgraded/downgraded to the new level.
• Duplicate skills in the parameters with different levels will cause the command to fail (no partial addition).
• See Field Constraints for input requirements.

Examples:

• addSkill p/1 sk/java:Advanced adds Java (Advanced) to the 1st person in the displayed list (or upgrades it if a lower level existed).
• addSkill p/2 sk/python sk/docker:Intermediate adds Python (Beginner) and Docker (Intermediate) to the 2nd person in the displayed list.

Removing a skill from a person : removeSkill

Removes one or more skills from a person in Mate.

Format: removeSkill p/INDEX sk/SKILL [sk/SKILL]...

• If the person doesn’t have any of the specified skills, the command fails (no partial removal).
• See Field Constraints for input requirements.

Examples:

• removeSkill p/1 sk/python removes the Python skill from the 1st person in the displayed list.

Adding an interested hackathon to a person : addHackathon

Adds one or more hackathons to a person’s interested list.

Format: addHackathon p/INDEX h/HACKATHON_NAME [h/HACKATHON_NAME]...

• A hackathon cannot be added to the interested list if the person is already participating in it via a team.
• If a hackathon is already in the interested list, the other hackathons are added (partial addition).
• See Field Constraints for input requirements.

Examples:

• addHackathon p/1 h/NUSHack adds NUSHack to the 1st person’s interested list.
• addHackathon p/2 h/NUSHack h/iNTUition adds both hackathons to the 2nd person’s interested list.

Removing an interested hackathon from a person : removeHackathon

Removes one or more hackathons from a person’s interested hackathon list.

Format: removeHackathon p/INDEX h/HACKATHON_NAME [h/HACKATHON_NAME]...

• Cannot remove a hackathon the person is currently participating in (they must be removed from the team first).
• See Field Constraints for input requirements.

Examples:

• removeHackathon p/2 h/TechChallenge removes TechChallenge from 2nd person’s interested list.
• removeHackathon p/4 h/NUSHack h/iNTUition removes both hackathons from 4th person’s interested list.

Listing all teams : listTeam

Shows a list of all teams in Mate.

Format: listTeam

Creating a team : createTeam

Creates a new team in Mate with the specified team members.

Format: createTeam tn/TEAM_NAME h/HACKATHON_NAME p/INDEX [p/INDEX]…​

• A team can be created with zero or more members.
• Team members cannot be in multiple teams for the same hackathon.
• The hackathon is automatically moved from interested to participating hackathons for all members.
• See Field Constraints for input requirements.

Tip: Make sure to use the list command first to see the current index numbers of persons before creating a team.

Note: If you provide the same person index multiple times (for example p/1 p/1 p/1), Mate will de-duplicate indices when creating a team — the team will contain that single person only. To add multiple different members, pass each member’s index once.

Examples:

• createTeam tn/Alpha Squad h/AI Challenge p/2 p/4 p/5 creates a team called “Alpha Squad” for the “AI Challenge” hackathon with the 2nd, 4th, and 5th persons as members.

Deleting a team : deleteTeam

Deletes a team from Mate and removes all members from that team.

Format: deleteTeam tn/TEAM_NAME

• All team members are automatically removed from the team.
• The team’s hackathon is removed from all members’ participating hackathons (but NOT added back to interested hackathons).
• See Field Constraints for input requirements.

Tip: Use the listTeam command first to see the team names before deleting one.

Examples:

• deleteTeam tn/Alpha Squad deletes the team named “Alpha Squad”.

Adding a person to a team : addToTeam

Adds an existing person to an existing team in Mate.

Format: addToTeam p/INDEX tn/TEAM_NAME

• The team must already exist.
• A person can be in multiple teams for different hackathons, but not multiple teams for the same hackathon.
• The team’s hackathon is automatically moved from interested to participating hackathons for the person.
• See Field Constraints for input requirements.

Examples:

• addToTeam p/1 tn/Alpha Squad adds the 1st person to the “Alpha Squad” team.

Removing a person from a team : removeFromTeam

Removes an existing person from an existing team in Mate.

Format: removeFromTeam p/INDEX tn/TEAM_NAME

• The team must already exist and the person must be a member.
• The team’s hackathon is automatically moved from participating to interested hackathons for the person.
• See Field Constraints for input requirements.

Examples:

• removeFromTeam p/1 tn/Alpha Squad removes the 1st person in the displayed list from the “Alpha Squad” team.

Saving the data

Mate’s data is saved in the hard disk automatically after any command that changes the data. There is no need to save manually.

Editing the data file

Mate’s data is saved automatically as a JSON file [JAR file location]/data/mate.json. Advanced users are welcome to update data directly by editing that data file.

Caution: If your changes to the data file makes its format invalid, Mate 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 Mate to behave in unexpected ways (e.g., if a value entered is outside the acceptable range). Therefore, edit the data file only if you are confident that you can update it correctly.

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 Mate 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 minimise 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 minimised, and no new Help Window will appear. The remedy is to manually restore the minimised Help Window.

Command summary