User Guide

DoctorWho is designed for clinic receptionists and administrative staff at single-doctor General Practitioner (GP) clinics. This guide assumes you are comfortable using a computer for everyday tasks, but no programming or technical experience is required.

Do you prefer typing information to having to click on multiple things? DoctorWho is for you!

DoctorWho is a desktop app for managing patient information and appointments, optimized for use via a Command Line Interface (CLI) while still having the benefits of a Graphical User Interface (GUI). If you can type fast, DoctorWho can get your patient management tasks done faster than traditional GUI apps.

Can DoctorWho help you?

Yes, if your clinic is still:

• Using paper filing to keep track of your patients and their appointments.
• Dealing with long search times in Excel.
• Paying exorbitant fees for enterprise grade software to only track a handful of patients.

Table of Contents

• Quick start
• Command Summary
• Features
• DoctorWho Operations
  • Adding a patient: add
  • Listing all patients: list
  • Editing a patient: edit
  • Locating patients by name: find
  • Deleting a patient: delete
  • Adding an appointment: apt
  • Deleting an appointment: dapt
  • Listing all appointments: lsapt
  • Clearing all entries: clear
  • Viewing help: help
  • Exiting the program: exit
  • Command parameters
    • For the add and edit commands:
    • For the apt command:
• Storage
  • Saving the data
  • Editing the data file
• FAQ
• Glossary
• Known issues
• Final word

Quick start

Don’t worry if you’re not tech-savvy — just follow these steps one by one, and you’ll be up and running in no time!

1. First, make sure you have Java 17 installed on your computer. Not sure if you have it? Open a terminal and type java -version — if you see the version number 17, you’re good to go!
   macOS users: Check out this guide to get the exact JDK version you need.

2. Next, download the latest doctorwho.jar file from here. You’ll find it under the Assets section of the latest release — just click on doctorwho.jar to download it.

3. Move the doctorwho.jar file to the folder where you’d like to store your patient data. We recommend creating a brand-new empty folder for this (e.g., a folder named DoctorWho on your Desktop), so everything stays neat and tidy.

   

4. Now, let’s launch the app! Open a command terminal in your DoctorWho folder:

   • Windows: Press Win + R, type cmd, and hit Enter.
   • macOS/Linux: Search for Terminal in Spotlight or your app menu.

   Then, navigate to your folder. For example, if you placed it on your Desktop in a folder called DoctorWho, type:

    cd Desktop/DoctorWho
   

   Finally, run the app with:

    java -jar doctorwho.jar
   

   

5. DoctorWho will launch with some sample data so you can explore right away — it should look something like this:

   

6. Type a command in the command box at the top and press Enter to run it. Here are a few to try out:

   • list — Lists all patients.
   • add n/John Doe ic/T0300001F x/M dob/01-04-2003 p/98765432 e/johnd@example.com a/John street, block 123, #01-01 — Adds a patient named John Doe.
   • delete 3 — Deletes the 3rd patient in the current list.
   • apt 3 d/01-04-2026 09:00 dur/60 note/Follow-up for diabetes review — Schedules an appointment for the 3rd patient.
   • lsapt d/12-03-2026 — Lists appointments for 12th March 2026.
   • dapt 1 — Removes the appointment from the 1st patient.

7. When you’re ready to explore more, check out the Features section for the full command details, or jump to the Command Summary for a quick cheatsheet!

Command Summary

Here is a quick reference list for the commands DoctorWho provides, more detailed information about all of the commands can be found in Features.

Features

DoctorWho Operations

Adding a patient: add

Adds a patient to DoctorWho.

Format: add n/NAME ic/NRIC x/SEX dob/DOB p/PHONE_NUMBER e/EMAIL a/ADDRESS [al/ALLERGY]…​ [mc/CONDITION]…​

• Will fail if there is an existing patient with the same NRIC, however other fields allow duplicates i.e., two patients may have the same name.
• The date of birth(dob) must be in the format dd-MM-yyyy and must be either the current date or earlier e.g., 12-03-2026 refers to 12th March 2026.
• All parameters are compulsory, except for those in square brackets.
• Refer to add command parameters

Tip: A patient can have any number of allergies or medical conditions (including 0)

Examples:

• add n/John Doe ic/T0300003B x/M dob/01-04-2003 p/98765432 e/johnd@example.com a/John street, block 123, #01-01
• add n/Betsy Crowe ic/T0300004J x/F dob/02-04-2003 e/bcrowe@example.com a/Newgate Prison p/1234567 al/Penicillin mc/cold
• add n/Tim Chal ic/T0300005I x/M dob/03-04-2003 e/betsycrowe@example.com a/Newgate Prison p/1234567 al/Morphine

Listing all patients: list

Shows a list of all patients in DoctorWho.

Format: list

Editing a patient: edit

Edits an existing patient in DoctorWho.

Format: edit PATIENT_NUMBER [n/NAME] [ic/NRIC] [x/SEX] [dob/DOB] [p/PHONE_NUMBER] [e/EMAIL] [a/ADDRESS] [al/ALLERGY]…​ [mc/CONDITION]…​

• Edits the patient at the specified PATIENT_NUMBER. The index refers to the index number shown in the displayed patient 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.
• When editing conditions and allergies, the existing ones of the patient will be removed i.e., adding is not cumulative.
• You can remove all the patient’s allergies or medical conditions by typing al/ or mc/ respectively, without any other entries.
  e.g., al/ al/Ibuprofen and mc/IBS mc/ will not work.
• Refer to edit command parameters

Examples:

• edit 1 x/F p/91234567 e/johndoe@example.com Edits the sex, phone number, and email address of the 1st patient to be F, 91234567, and johndoe@example.com respectively.
• edit 2 n/Betsy Crower al/ mc/ Edits the name of the 2nd patient to be Betsy Crower and clears all existing allergies and medical conditions.

Locating patients by name: find

Finds patients whose names contain any of the given keywords.

Format: find KEYWORD [MORE_KEYWORDS]…​

• The search is case-insensitive. e.g., hans will match Hans
• The order of the keywords does not matter. e.g., Hans Bo will match Bo Hans
• Only the name is searched.
• Only full words will be matched e.g., Han will not match Hans
• Patients matching at least one keyword will be returned (i.e., OR search). e.g., Hans Bo will return Hans Gruber, Bo Yang

Tip: Use find before delete or edit to locate the right patient first. This reduces the risk of accidentally modifying the wrong patient’s records.

Examples:

• find John returns john and John Doe
• find alex david returns Alex Yeoh, David Li
  

Deleting a patient: delete

Deletes the specified patient from DoctorWho.

Format: delete PATIENT_NUMBER

• Deletes the patient at the specified PATIENT_NUMBER.
• The PATIENT_NUMBER must be a positive integer 1, 2, 3, …​

Caution: This action is irreversible. Once a patient is deleted, all their information and appointments cannot be recovered. Use find first to confirm you have the right patient before deleting.

Examples:

• list followed by delete 2 deletes the 2nd patient in DoctorWho.
• find Betsy followed by delete 1 deletes the 1st patient in the results of the find command.

Adding an appointment: apt

Adds an appointment to the patient identified by the index number used in the displayed patient list. Supply the start date and time, duration, and an optional note.

Format: apt PATIENT_NUMBER d/DATETIME dur/DURATION [note/NOTE]

• Creates and adds an appointment for the patient at the specified PATIENT_NUMBER.
• The PATIENT_NUMBER must be a positive integer 1, 2, 3, …​
• The date and time must be in the format dd-MM-yyyy HH:mm e.g., 12-03-2026 14:00 refers to 12th March 2026, 14:00.
• The duration must be between 1 and 600 minutes inclusive.
• The note is optional.
• Refer to apt command parameters

Caution: If the patient already has an existing appointment, it will be silently overwritten with no confirmation prompt. Check the patient’s current appointment before using this command.

Examples:

• apt 1 d/12-03-2026 14:00 dur/30 note/Routine Checkup adds an appointment to the 1st patient, from the top, of the patient list, scheduled for 12th March 2026, at 14:00. A note will be indicated with Note | Routine Checkup

Deleting an appointment: dapt

Deletes the appointment of the patient identified by the index number used in the displayed patient list.

Format: dapt PATIENT_NUMBER

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

Examples:

• list followed by dapt 1 deletes the appointment for the 1st patient in the displayed patient list.

Listing all appointments: lsapt

Shows all appointments across all patients, sorted by date-time in ascending order, to give a daily schedule view.

Format: lsapt [d/DATE]

• Lists all scheduled appointments when no date is provided.
• If d/DATE is provided, only appointments on that date will be shown, and listed from earliest to latest.
• DATE must be in the format dd-MM-yyyy e.g., 14-03-2026 refers to 14th March 2026.

Tip: Run lsapt d/TODAY'S DATE at the start of your shift to get a quick overview of all appointments for the day, sorted from earliest to latest.

Examples:

• lsapt returns all appointments across all patients, sorted by date-time ascending.
• lsapt d/14-03-2026 returns all appointments on 14th March 2026.

Clearing all entries: clear

Clears all entries from DoctorWho.

Format: clear

Caution: This action is irreversible and will delete all patient data.

Viewing help: help

Opens a window that provides a summary of available commands and explains how to access the help page. (Pressing the F1 key will also open this window)

Format: help

Exiting the program: exit

Exits the program.

Format: exit

Command parameters

Storage

Saving the data

DoctorWho 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

DoctorWho data is saved automatically as a JSON file [JAR file location]/data/doctorwho.json. Advanced users are welcome to update data directly by editing that data file, which follows the following format.

{
  "patients" : [ {
    "name" : "Alex Yeoh",
    "nric" : "S1234567D",
    "sex" : "F",
    "dob" : "01-04-2003",
    "phone" : "87438807",
    "email" : "alexyeoh@example.com",
    "address" : "Blk 30 Geylang Street 29, #06-40",
    "tags" : [ "allergy:Penicillin", "condition:Diabetes" ],
    "appointmentStart" : "12-03-2026 14:00",
    "appointmentDuration" : 30,
    "appointmentNote" : "Initial Consultation"
  }, {
    "name" : "Bernice Yu",
    "nric" : "S2345678H",
    "sex" : "F",
    "dob" : "02-04-2003",
    "phone" : "99272758",
    "email" : "berniceyu@example.com",
    "address" : "Blk 30 Lorong 3 Serangoon Gardens, #07-18",
    "tags" : [ "condition:Hypertension", "allergy:Aspirin" ],
    "appointmentStart" : null,
    "appointmentDuration" : null,
    "appointmentNote" : null
  } ]
}

Caution: If your changes to the data file makes its format invalid, DoctorWho 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 DoctorWho 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.

FAQ

Q: What happens if I accidentally delete a patient?
A: When a patient is deleted, their details are shown in the GUI, therefore it is possible to re-add the patient before another command is run. Subsequently, deletion is irreversible and the patient’s data cannot be recovered from within the app. To further safeguard against accidental deletion, we recommend periodically making a manual copy of your data file located at [JAR file location]/data/doctorwho.json and storing it in a separate folder. If you have a copy, you can restore it by replacing the current data file with your backup.

Q: Can I schedule multiple appointments for one patient?
A: Currently, DoctorWho supports one active appointment per patient at a time. To schedule a new appointment, use the apt command which will replace the existing one. Support for multiple appointments per patient is planned for a future version.

Q: How do I transfer my data to another computer?
A: Install the app on the other computer and overwrite the empty data file it creates with the file from your previous DoctorWho folder, located at [JAR file location]/data/doctorwho.json.

Glossary

• CLI: Command Line Interface. A text-based interface where users interact with a program by typing commands.
• Command: An instruction given to a computer program to perform a specific task.
• GUI: Graphical User Interface. A visual-based interface where users interact with a program by interacting with windows, icons and menus.
• JSON: JavaScript Object Notation. A lightweight, text-based data interchange format, easily parsable by machines.

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.

Final word

Thank you once again for using DoctorWho! We hope that you will find our product beneficial to managing your patients seamlessly! For your reference here is a link to the Command Summary. Should you have any queries, please do not hesitate to reach out to any of us! Our details can be found in our About Us Page.