BlockBook User Guide

BlockBook is a desktop app built for Minecraft players to manage Minecraft gamer contacts, 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, BlockBook can get your contact management tasks done faster than traditional GUI apps.

BlockBook makes it easy to manage the contacts of other gamers you meet on servers, allowing you to manage contacts through not just names, but other gaming attributes too.

---

Quick start

1. Ensure you have Java 17 or above installed in your Computer.
   You can check what Java version you have by opening a command terminal in the same location you put BlockBook in, and then running the command java -version. Mac users: Ensure you have the precise JDK version prescribed here.

2. Download the latest blockbook.jar file from here.

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

4. Double click blockbook.jar file to open BlockBook. Alternatively, open a command terminal in the same location you put BlockBook in, and use the java -jar blockbook.jar command to run the application.
   A GUI similar to the below should appear in a few seconds.
   

5. Type the command in the command box and press Enter to execute it. e.g. typing ? or help and pressing Enter will open the built-in help menu, where you can view all the commands available.
   Some example commands you can try:

   • list : Lists all contacts.

   • add g/JD910 n/John Doe : Adds a contact named John Doe to BlockBook with the gamertag JD910.

   • d 3 : Deletes the 3rd contact shown in the current list. d is a shortcut for delete.

   • clear : Deletes all contacts.

   • exit : Exits the app.

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

---

Features

Viewing help : help

Opens a new window listing all available commands.

Format: help or ?

Adding a gamer: add

Adds a gamer to BlockBook with a required gamertag and optional details such as name, phone number, email address, server, region, country, and notes.

Format: (a)dd (g)amertag/GAMERTAG [(n)ame/NAME] [(p)hone/PHONE] [(e)mail/EMAIL] [(s)erver/SERVER] [(c)ountry/COUNTRY] [(r)egion/REGION] [note/NOTE]

Examples:

• a g/ilovesteve n/Herobrine p/99999 e/brine@gmail.com s/127.0.0.1:8080 c/Singapore r/ASIA note/I hate steve
• add gamertag/Notch name/Notch phone/+12345 email/notch@example.com server/mc.example.net:25565 country/Malaysia region/ASIA note/Usually plays survival

Common errors you may encounter:

• Duplicate gamertag You cannot add two gamers with the same gamertag. Gamertags are treated as case-insensitive, so banana, Banana, and BaNaNa are all treated as the same gamertag.

• Missing required gamertag The add command requires a gamertag/ or g/ field. Example: add n/Steve

• Repeated prefixes Each single-value field can only be entered once in the same add command. Example: add g/Steve123 g/Alex456

• Invalid gamertag format Gamertags cannot contain spaces or special characters other than underscores. Example: g/steve boy

Notes:

• Names and countries are automatically normalized by collapsing repeated spaces and standardizing capitalization. For example, n/jOhN doE will be stored as John Doe.
• Region input is case-insensitive, but will be stored and displayed in uppercase. For example, r/asia will be stored as ASIA.
• Notes are not auto-normalized in the same way, so they are stored more closely to how you entered them.
• Newly added gamers are not favourited by default.

Listing all gamers : list

Shows a list of all gamers stored in BlockBook.

Format: (l)ist

• Clears any active filter (e.g., from find) and any active sort, restoring original order.

Editing a gamer : edit

Edits an existing gamer stored in BlockBook.

Format: (e)dit GAMER_INDEX [(g)amertag/GAMERTAG] [(n)ame/NAME] [(p)hone/PHONE] [(e)mail/EMAIL] [(s)erver/SERVER] [(c)ountry/COUNTRY] [(r)egion/REGION] [note/NOTE]

• Edits the gamer at the specified GAMER_INDEX. The index refers to the index number shown in the displayed gamer 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.

Examples:

• edit 1 p/91234567 e/johndoe@example.com
• e 2 n/Betsy Crower r/ASIA
• edit 3 g/new_tag s/mc.example.com:25565 c/Singapore note/Alt account

Common errors you may encounter:

• Invalid index The index must be a positive integer within the displayed list. Examples: edit 0 n/Alex, edit -1 n/Alex, edit 999 n/Alex

• No fields provided At least one field must be specified after the index. Example: edit 1

• Repeated prefixes Each single-value field can only be entered once in the same edit command. Example: edit 1 n/Alex n/Bob

• Duplicate gamertag You cannot change a gamertag to one that already exists. Example: edit 1 g/amy_tag (if another gamer already has amy_tag)

• Invalid field values Input must follow the constraints above (e.g., invalid email, region, or server).

Notes:

• Names and countries are automatically normalized by collapsing repeated spaces and standardizing capitalization.
• Region input is case-insensitive, but will be stored and displayed in uppercase.
• Notes are stored as entered (no auto-normalization).
• Favourite status cannot be changed using edit. Use favourite or unfavourite instead.

Editing a gamer's favourite status : favourite, unfavourite

Updates a gamer's favourite status via index.

Format: (fav)ourite GAMER_INDEX or (unfav)ourite GAMER_INDEX

• Updates the favourite status of the gamer at the specified GAMER_INDEX. The index refers to the index number shown in the current displayed list (after any find, sort, or list).

Examples:

• fav 1 Updates the favourite status of the first gamer to favourite.

• unfavourite 1 Removes the first gamer from favourites.

Common errors you may encounter:

• Invalid index The index must be a positive integer within the displayed list. Examples: favourite 0, unfavourite -1, favourite 999

• Already favourite / already not favourite The command will fail if the contact is already in the requested state. Examples: favourite 1 when the contact is already a favourite, unfavourite 1 when the contact is not a favourite.

Notes:

• This command only updates favourite status; it does not edit other fields.
• Star icon is shown next to the gamer name if the gamer is favourite.

Locating gamers: find

Finds gamers using either general keyword search or specific attribute prefixes. Has 2 formats.

Format 1: (f)ind KEYWORD

• The search is case-insensitive and uses partial (substring) matching.
• If you include spaces in KEYWORD, the full phrase is matched as a single substring.
• Each find replaces the current filter (it does not stack with previous find results).
• A match is found if the keyword appears in any attribute (except favourite).

Format 2: (f)ind [(g)amertag/GAMERTAG] [(n)ame/NAME] [(p)hone/PHONE] [(e)mail/EMAIL] [(gr)oup/GROUP] [(s)erver/SERVER] [(fav)ourite/] [(c)ountry/COUNTRY] [(r)egion/REGION] [note/NOTE]

• Prefixes can be stacked in one command.
• Prefixes use the same short-form notation, e.g. (n)ame/ means name/ or n/.
• When multiple prefixes are provided, a gamer must match all specified prefixes (AND).
• Each find replaces the current filter (it does not stack with previous find results).
• region/ must use a full region value (e.g., ASIA), not a partial substring. This is case-insensitive.

Examples:

• find steve
• f n/steve g/stevemaster
• find name/alex region/ASIA
  

Viewing gamers full details: view

Shows the full details of a gamer based on the index shown in the current list.

Format: (v)iew INDEX

• The INDEX refers to the index number shown in the currently displayed list.
• The index must be a positive integer.

Example:

• view 2
  Displays the full details of the 2nd gamer in the current list.

  

Sorting gamers : sort

Sorts gamers by one or more attributes.

Format: (s)ort [(g)amertag/] [(n)ame/] [(p)hone/] [(e)mail/] [(gr)oup/] [(s)erver/] [(fav)ourite/] [(c)ountry/] [(r)egion/] [note/]

• If no attributes are provided, gamers are sorted by gamertag by default.
• Attributes are applied in priority order from left to right (first attribute = primary sort key).
• Each attribute can only be specified once (e.g., g/ and gamertag/ count as the same attribute).
• Attribute tokens are case-sensitive and must be lowercase (e.g., name/, not NAME/).
• For optional attributes (name, phone, email, group, server, country, region, note), gamers without that value appear after gamers with a value.
• favourite/ places favourited gamers before non-favourited gamers.
• group/ sorts by a gamer's full group set (group names are alphabetically ordered before comparison).
• If a filter is active (e.g., after find), the filtered results are shown in the active sort order.
• Sorting is session-based and is not persisted to storage. A session lasts from when BlockBook is opened until it is closed. Closing the application (either via the exit command or by closing the window) ends the session and discards the current sort order. When BlockBook is reopened, gamers are displayed in their original insertion order.
• list resets sorting within the current session and returns to insertion order.

Examples:

• sort sorts gamers by gamertag (default).
• sort name/ sorts gamers by name.
• s p/ g/ sorts gamers by phone number, then by gamertag.
• sort favourite/ name/ sorts favourites before non-favourites, then by name within each favourite-status group.

Before running sort favourite/ name/:

After running sort favourite/ name/:

In the after screenshot, verify:

• Favourited gamers appear before non-favourited gamers.
• Names are sorted alphabetically (case-insensitive) within the favourited group.
• Names are sorted alphabetically (case-insensitive) within the non-favourited group.

Common errors you may encounter:

• Duplicate attributes Each sort attribute can only be entered once. Short and long forms of the same attribute count as duplicates. Example: sort gamertag/ g/ Error shown: Duplicate attribute detected: gamertag. Each attribute can only be specified once.
• Invalid attribute name Unsupported attributes are rejected. Example: sort rank/ Error shown: Invalid attribute detected: rank. Please provide a valid sort attribute.
• Multiple invalid attributes If more than one invalid attribute is provided, all invalid attributes are reported together. Example: sort rank/ level/ Error shown: Invalid attributes detected: rank, level. Please provide only valid sort attributes.
• Invalid format Every attribute token must end with /. Example: sort name Error shown: Invalid command format! followed by the sort usage format.
• No gamers to sort sort cannot run when the gamer list is empty. Error shown: There are no contacts to sort!

Notes:

• You can mix long and short forms in one command. Example: sort name/ p/.
• note/ has no short alias.
• For whole-list sorting after find, run list, then run sort again.

Deleting a Gamer : delete

Deletes the specified gamers from BlockBook.

Format: (d)elete GAMER_INDEX [GAMER_INDEX]...

• Deletes the gamers at each specified GAMER_INDEX.
• Trying to delete the same index multiple times will only cause that index to be deleted once.
• The indexes refer to the index numbers shown in the displayed gamer list.
• The indexes do not have to be in any particular order. e.g. delete 2 1 is acceptable.
• Each index must be a positive integer 1, 2, 3, ...

Examples:

• list followed by delete 2 deletes the 2nd gamer shown in the list.
• find Betsy followed by delete 1 2 deletes the 1st and 2nd gamer in the results of the find command.
• d 2 1 deletes the 1st and 2nd gamer shown in the list.
• delete 1 2 2 deletes only the 1st and 2nd gamers shown in the list. The 2nd gamer is only deleted once.

Clearing all entries : clear

Clears all entries from BlockBook.

Format: clear [CONFIRMATION_CODE]

• Running clear without a confirmation code will display a warning and a confirmation code.
• To confirm, re-enter the command using the code shown (e.g., clear 2v8wua).
• If you enter the wrong code, BlockBook will show a new confirmation code.

Examples:

• clear shows a warning and a confirmation code (e.g., clear 2v8wua).

• clear 2v8wua clears all entries if the confirmation code is 2v8wua.

Creating a group : groupcreate

Creates a new group in BlockBook.

Format: groupcreate GROUP or gc GROUP

• Group names are case-insensitive and must be unique.
• Group names can contain only letters, spaces, hyphens, and apostrophes, and must be at most 50 characters.

Examples:

• groupcreate Raid Team
• gc Arena Team

Editing a group's name : groupedit

Renames an existing group by its index in the group list.

Format: groupedit BLOCKBOOK_GROUP_INDEX NEW_GROUP_NAME or ge BLOCKBOOK_GROUP_INDEX NEW_GROUP_NAME

• The BLOCKBOOK_GROUP_INDEX refers to the index shown in the group list.
• The new group name follows the same constraints as group creation.
• Group names are unique case-insensitively across different groups, so only one instance of a group name can exist
• (e.g. if a group named Raid Team exists, another group cannot be named raid team).
• Changing the letter casing of the same group name (e.g., Raid Team → raid team) is allowed which is an exception to the rule above.

Examples:

• groupedit 1 iloveAlex
• ge 2 Arena Team

Deleting a group : groupnuke

Deletes a group from BlockBook and removes that group from all gamers associated to it.

Format: groupnuke BLOCKBOOK_GROUP_INDEX [CONFIRMATION_CODE] or gn BLOCKBOOK_GROUP_INDEX [CONFIRMATION_CODE]

• This is a destructive command and requires confirmation.
• BlockBook will show a warning message with a confirmation code and the affected gamertags.
• Re-run the command with the confirmation code appended to proceed.
• If you enter the wrong code, BlockBook will show a new confirmation code.

Example:

• groupnuke 1 BlockBook will prompt you with a confirmation code.

• groupnuke 1 j5n0w3 Deletes the group and removes it from all gamers.

Adding a gamer to a group : groupadd

Adds a specific gamer to a specific group in a single command, by providing the gamer’s index in the current list and the group’s index in the group list.

Format: groupadd GAMER_INDEX BLOCKBOOK_GROUP_INDEX or ga GAMER_INDEX BLOCKBOOK_GROUP_INDEX

• GAMER_INDEX refers to the index shown in the current gamer list.
• BLOCKBOOK_GROUP_INDEX refers to the index shown in the group list.
• If the gamer index is invalid, BlockBook will indicate the gamer index is out of bounds.
• If the group index is invalid, BlockBook will indicate the group index is out of bounds.
• If both indexes are non-positive (e.g., 0 0), BlockBook will report both as invalid.

Example:

• groupadd 2 1 adds the 2nd gamer in the current list to the 1st group in the group list.

Removing a gamer from a group : groupremove

Removes a specific group from a specific gamer in a single command, by providing the gamer’s index in the current list and the group’s index in that gamer’s group list.

Format: groupremove GAMER_INDEX GAMER_GROUP_INDEX or gr GAMER_INDEX GAMER_GROUP_INDEX

• GAMER_INDEX refers to the index shown in the current gamer list.
• GAMER_GROUP_INDEX refers to the index shown in that gamer’s group list (not the global group list).
• If the gamer index is invalid, BlockBook will indicate the gamer index is out of bounds and will not validate the gamer’s group index.
• If the gamer’s group index is invalid, BlockBook will indicate the gamer’s group index is out of bounds.
• If both indexes are non-positive (e.g., 0 0), BlockBook will report both as invalid.

Example:

• groupremove 2 1 removes the 1st group from the 2nd gamer in the current list.

Listing all groups : grouplist

Lists all groups stored in BlockBook.

Format: grouplist or gl

• Groups are shown with their index (e.g., 1. Explorers, 2. Raid Team).
• If there are no groups, BlockBook will indicate that no groups were found.

Example:

• grouplist

Viewing a group : groupview

Shows all gamers that belong to a specific group, and filters the list to those gamers.

Format: groupview BLOCKBOOK_GROUP_INDEX or gv BLOCKBOOK_GROUP_INDEX

• BLOCKBOOK_GROUP_INDEX refers to the index shown in the group list.
• The displayed gamer list is filtered to show only members of the selected group.
• If no gamers belong to the group, BlockBook will show a message and keep the current list unchanged.

Example:

• groupview 1 shows all gamers in the 1st group.

Exiting the program : exit

Exits the program.

Format: exit

Saving the data

BlockBook data is saved to primary storage automatically after any command that changes the data. There is no need to save manually.

Editing the data file

BlockBook data is saved automatically as a JSON file [JAR file location]/BlockBook/contacts.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 in the other computer and overwrite the empty data file it creates with the file that contains the data of your previous BlockBook 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.

---

Command summary