User Guide

FAST • FLEXIBLE • FOOLPROOF

Purpose-built, clutter-free itinerary planner designed for digital nomads

AddressMe helps you plan and track your travel destinations, dates, and important details in one convenient platform, optimised for use entirely through a Command Line Interface (CLI) with the benefits of a Graphical User Interface (GUI).

It offers a minimalist, easy-to-learn experience designed for digital nomads who need their location data to be structured and always accessible. If you can type quickly and get frustrated by over-engineered itinerary planners, AddressMe is the app for you!

Do you:

• Move regularly and need to track multiple locations and visit plans?
• Need your data even with unreliable internet?
• Prefer typing over clicking through menus?
• Feel frustrated by overly complicated itinerary planners?

If so, AddressMe is built for you!

Table of Contents

• 1. Quick Start
  • Installation
  • Interface Overview
• 2. Starting to use Commands
  • Name Formats
  • Phone Formats
  • Tag Formats
  • Date Formats
  • Start Your First Commands
• 3. Features - Full Reference
  • help - Viewing help
  • add - Adding a location
  • list - Listing all locations
  • find - Filtering locations by attributes
  • edit - Editing a location
  • delete - Deleting a location
  • plan - Using the itinerary planner
  • note - Managing notes
  • undo - Reverting the last change
  • redo - Redoing the last undo
  • shortcut - Managing command shortcuts
  • theme - Customize your application
  • clear - Clearing all entries
  • exit - Exiting the program
• 4. Command summary
• 5. CLI Power Features
  • Command History
  • Autocomplete
• 6. Data Management
  • Automatic Saving
  • Editing the data file directly
  • Transferring Data to Another Device
• 7. FAQ & Known Issues
  • Frequently Asked Questions
  • Known Issues

1. Quick Start

Installation

1. Ensure you have Java 17 or above installed on your machine.
   You can do this by opening the Command Prompt app (for Windows users), or Terminal (for Mac/Linux users) and entering “java -version”.
   
2. Download the latest version of AddressMe.jar from the GitHub releases page here.
3. Place the AddressMe.jar file in a folder - this becomes your AddressMe home folder.
4. While in your home folder, right-click and select “Open in Terminal”
5. Enter the following command into the terminal: java -jar AddressMe.jar
6. That’s it! AddressMe launches with sample data, and you can plan your trip immediately.

Interface Overview

AddressMe has four main UI zones:

2. Starting to use Commands

Before we dive into each feature, here’s a tip to make everything smooth and easy.

Every command has a helpful guiding message:

A valid add command is shown below.

Name Formats

Location names can include letters, numbers, spaces, and common symbols such as & @ ( ) [ ] . , - '. The name must contain at least one letter or number (i.e. cannot consist only of symbols).

This allows realistic names such as AT&T Store or Raffles @ Marina.

These rules apply to all commands that use names (e.g. add, edit).

Phone Formats

Can start with + and may include spaces or hyphens between digits (e.g. 91231234, 9123 1234, +65 9124-1234).

Must contain at least 3 digits and be no longer than 15 characters.

Tag Formats

May include alphanumeric characters, spaces or hyphens.

Must contain at least one alphanumeric character.

All Tag inputs are translated and stored as lowercase.

Date Formats

AddressMe even accepts a large range of date inputs so you can type dates flexibly.

• Dates are separated with slashes (“/”) or hyphens (“-”).
• With day, month and year fully specified:

• With day and month (no year): AddressMe picks the next occurrence of that date. For edge cases like 29 Feb, if it does not exist in the year, AddressMe gracefully corrects it to 28 Feb.

• With day of the week (case-insensitive): AddressMe picks the upcoming date of that weekday.

Pro Tip - Fast Dates: If today is Tuesday, typing Tue matches today. Typing Wednesday or Wed matches tomorrow. Typing Mon matches next Monday!
Alternatively, typing today also works!

• Recurring Dates: You can mark locations with recurring dates by starting it with e- or every!
  DAY_MONTH and DAY_OF_WEEK accepts the formats specified above.

Start Your First Commands

Now that you’re familiar with commands, try typing these commands into AddressMe to get a feel for the application.

• list

Shows all saved locations.

• find Cafe

Searches for any location with ‘Cafe’ in its name.

• add n/Nomad Hub e/hello@nomadhub.com a/12 Tanjong Pagar t/coworking

Adds a new coworking space.

• plan 2026-04-01

Shows your itinerary plan for 1 April 2026.

• exit

Closes the application.

When you’re comfortable with sending commands, you’re ready to dive deeper into each feature!

3. Features - Full Reference

If you are already familiar with the commands, skip straight to the command summary to refresh your memory!

help - Viewing help

Shows you commands you can use, as well as how to use specific commands.

Formats:

help
help COMMAND_WORD
help -ug

• help displays a summary of all supported commands in AddressMe.
• help COMMAND_WORD displays detailed local guidance for that command.
  COMMAND_WORD must be an existing built-in command word.

Examples:

• help add shows the specific usage for the add command.

• help -ug opens the help window for the link to the online User Guide (see below).

Tip: If you minimise the Help window and run help again, the minimised window will not reappear automatically. Restore it manually from your taskbar.

add - Adding a location

Saves a new location to your address book, with optional visit dates and tags for easy retrieval later.

Format: add n/NAME [p/PHONE_NUMBER] [e/EMAIL] [a/ADDRESS] [c/POSTAL_CODE] [d/DATE]... [t/TAG]...

Examples:

• add n/Nomad Hub p/9876-5432 e/hello@nomadhub.com a/12 Tanjong Pagar d/every day t/coworking
  
• add n/Al-Azhar Restaurant p/+65 63910060 e/contact@alazhar.sg a/18 Arab St t/halal t/dinner d/Friday

Tip: A location can have any number of tags and visit dates - including none at all. You can always add them later using the edit command.

list - Listing all locations

Displays every saved location in the Location List. Use this to reset the view after a find command.

Format: list

find - Filtering locations by attributes

Your most powerful command. Searches across names, addresses, tags, phone numbers, emails, and visit dates. Multiple conditions are combined with AND logic - the more specific you are, the more precise your results.

Format: find [KEYWORD] [MORE_KEYWORDS] [n/NAME] [p/PHONE] [e/EMAIL] [a/ADDRESS] [c/POSTAL_CODE] [t/TAG] [d/DATE]

How Search Works

Examples:

• find Restaurant returns all locations with “Restaurant” in the name
• find Marina Beach returns Marina Park, Beach Resort (OR search for names).
• find n/Cafe e/gmail.com returns all cafes with a Gmail address.

edit - Editing a location

Updates one or more fields of a saved location.

Format: edit INDEX [n/NAME] [p/PHONE] [e/EMAIL] [a/ADDRESS] [c/POSTAL_CODE] [d/DATE]… [d+/DATE]… [d-/DATE]… [t/TAG]… [t+/TAG]… [t-/TAG]…

• Edits the location at the specified INDEX. The index refers to the index number shown in the displayed location list. The index must be a positive number 1, 2, 3, …
• At least one of the optional fields must be provided.
• Existing values will be updated to the input.
• To clear a field, provide the prefix without a value (e.g. p/ to clear phone).
• This applies to optional fields such as phone, email, postal code and address.

Tag and Date Editing Modes

Tags behave as a set (no duplicates, order does not matter).

• Duplicate tags provided in add or edit commands are ignored.
• When using t-/ or d-/, if a specified tag or date does not exist, it is ignored and the command still succeeds.

Examples:

• edit 1 p/91234567 e/contact@sundowncafe.com
  Edits the phone number and email address of the 1st location to be 91234567 and contact@sundowncafe.com respectively.
• edit 2 n/Happy Bistro t/ d+/2026-01-01
  Edits the name of the 2nd location to be Happy Bistro, clears all existing tags, and adds a visit date of 2026-01-01.
• edit 1 p/ e/
  Clears the phone number and email of the 1st location without changing anything else.

delete - Deleting a location

Removes one or more locations from your address book, keeping it clean and relevant throughout your journey.
Accepts multiple unique index numbers in a single command.

Format: delete INDEX [MORE_INDEXES]...

Examples:

• list followed by delete 2: Deletes the 2nd location in the current list.
• find Sentosa followed by delete 1: Finds locations matching ‘Sentosa’, then deletes the 1st result from filtered list.
• list followed by delete 1 3 5: Deletes the 1st, 3rd, and 5th locations in a single command.

plan - Using the itinerary planner

Displays all locations assigned to a given date in the Planner List, so you can view your day’s plan at a glance.

Formats:

• plan [DATE]: Displays all the locations with the matching dates for easy cross-referencing.
• plan: clears the Planner List

Examples:

• plan 12/3/26: Shows all locations planned for 12 March 2026.
• plan Friday: Shows locations planned for the upcoming Friday.
• plan: Clears the planner list.

note - Managing notes

Adds or deletes notes for specific or recurring dates. Use this together with the plan command to view your notes for a specific date.

Formats:

• note n/NOTE d/DATE : Adds or overwrites a note on a date
• note d-/DATE : Deletes the note for that date

Behaviour:

• Notes can be added to both one-time dates (e.g. 2026-04-12) and recurring dates (e.g. e-Sunday).
• One-time dates and recurring dates are treated as separate entries.
• It is possible for both a one-time note and a recurring note to apply to the same day.
  For example, 2026-04-12 (Sunday) may show a note for 2026-04-12 and a note for e-Sunday.
• When this happens, both notes will be displayed.
• To update a note, add a new note with the same date format (e.g. 2026-04-12). The existing note will be replaced.
• Deleting a note only affects the exact date format provided.
  For example, note d-/2026-04-12 removes only the one-time note, while note d-/e-Sunday removes only the recurring note.

Tip: If both a one-time note and a recurring note apply to the same day, both will be shown in the planner, even if they refer to the same calendar date.

Examples:

• note n/Bring passport d/2026-04-12
• note n/Weekly reminder d/e-Sunday
• note d-/2026-04-12
• note d-/e-Sunday

undo - Reverting the last change

Reverts the most recent successful undoable change.

Format: undo

• undo currently supports only one level of history.
• If there is nothing to undo, AddressMe shows an error message.

Examples:

• delete 3 followed by undo restores the deleted location.
• note n/Involves lots of walking. Bring extra water bottles. d/2026-03-24 followed by undo removes the note again.
• shortcut set a add followed by undo removes the shortcut again.

redo - Redoing the last undo

Reapplies the most recent undone change.

Format: redo

• redo is available after a successful undo until another successful undoable command happens.
• A new successful undoable command clears the redo state.
• If there is nothing to redo, AddressMe shows an error message.

Examples:

• add n/McDonalds followed by undo and redo adds the same location back.
• delete 1 followed by undo and redo deletes the same location.

shortcut - Managing command shortcuts

Creates, removes, and lists custom aliases for built-in commands. Shave seconds off your most frequent actions.

Format:

shortcut set ALIAS COMMAND_WORD
shortcut remove ALIAS
shortcut list

• Shortcuts are case-insensitive and stored in lowercase.
• Shortcuts must start with a letter and contain only alphanumeric characters.
• You cannot reuse an alias that is already assigned to another command.
• You cannot reuse an existing command word as an alias (e.g. you cannot set add as an alias for edit).
• COMMAND_WORD must be a default command word.

Examples:

• shortcut set a add: Now typing a n/... behaves exactly like add n/...
• shortcut list: Displays all current shortcuts.
• shortcut remove a: Removes alias ‘a’.

theme - Customize your application

Switches the application between light and dark modes.

Format: theme THEME_NAME

• Use theme light and theme dark to switch to light and dark mode respectively.
• The selected theme is saved and restored the next time the app starts.

clear - Clearing all entries

Clears all data from the AddressMe, including all locations and notes.

Format: clear

Caution:
If you need to start fresh, consider backing up your data file first (see Data Management).
Always remember you can undo!

exit - Exiting the program

Closes AddressMe. Your data is saved after relevant commands; no need to manually save.

Format: exit

4. Command summary

5. CLI Power Features

Command History

All commands you type during a session are stored. While clicked into the command box:

• Press the UP arrow to scroll back through previous commands.
• Press the DOWN arrow to move forward in history.

Example: After entering list and find Cafe into the CLI, pressing UP recalls find Cafe. Pressing UP again recalls list.

This makes repeating your most-used commands extremely fast.

Autocomplete

Press Tab while typing a command to autocomplete it.

• Autocomplete is case-insensitive.
• If multiple commands match (e.g. e matches both edit and exit), AddressMe fills to the longest common starting letters.

Examples:

• a + [Tab] → add

• e + [Tab] → e (ambiguous: edit / exit)

• ex + [Tab] → exit

6. Data Management

Automatic Saving

Your data is saved to disk automatically after every command that changes it. You do not need to save manually.

Location data is stored at: [home folder]/data/addressbook.json
Shortcuts are stored at: [home folder]/data/shortcut.json

Editing the data file directly

Advanced users may edit the JSON file directly using any text editor. This can be useful for bulk imports when relocating to a new city.

Edit with Care:
If the file format becomes invalid, AddressMe will discard all data and start fresh on the next launch. Always make a backup copy before editing the file. Values outside acceptable ranges may cause unexpected behaviour.

Transferring Data to Another Device

Install AddressMe on the new device, run it once to generate the data folder, exit the application, then replace any .json files with your existing data files from the old device.

7. FAQ & Known Issues

Frequently Asked Questions

Q: How do I move my data to a new laptop?

A: Install AddressMe on the new device, run it once, then copy all the .json files (found in the folder labelled “ data”) from the old device into the new device’s data folder, replacing the files that were created.

Q: Will my shortcuts and themes persist after I close AddressMe?

A: Yes. Your shortcuts are saved in shortcut.json in the data folder, and your theme is saved in preferences.json, all of which will be restored the next time you launch the app.

Q: Can I have the same location listed multiple times?

A: No. Duplicates are checked when you add or edit a location. Locations are considered the same by the following:

• Postal code and address if both locations have these fields
• Address if both locations have addresses, but either does not have a postal code
• Name if either location has no address

Known Issues

Multiple Monitors: If you move AddressMe to a secondary screen and later disconnect that monitor, the application window may open off-screen.
Fix: delete preferences.json in your home folder before relaunching.

Help Window: If the Help window is minimised and you run help -ug again, no new window will appear.
Fix: manually restore the minimised Help window from your taskbar. ——————————————————————————————————————–