terminordle

multiplayer wordle clone in your terminal

terminordle (pronounced "terminalordle") is inspired by the popular online game wordle made for your terminal. You can play a pretty close replica of the original locally or multiplayer over the network. Now available through brew.

changelog

• v0.1.14
  • bump deps

• install
  • homebrew
    • fixing alias
  • dependencies
  • yarn & npm
  • or clone this repo
• HELP
• PLAY
  • local single player
  • remote multiplayer
    • new session
      • user ids
    • join existing session
• SERVE
  • wss support
  • overview
• gameplay
• data privacy
  • possible data collection exceptions

install

homebrew

If you are on a mac, you can use homebrew.

# tap repo
brew tap --force-auto-update hp4k1h5/terminordle https://github.com/hp4k1h5/terminordle.git
# install
brew install terminordle

fixing alias

• If you installed with brew but without the --force-update flag, you can simply run the two above commands again and that should provide an automatically updateable install.

dependencies

• nodeJs
  • tested with node v17.5.0
• yarn or npm

yarn & npm

yarn global add @hp4k1h5/terminordle
# OR
npm -g install @hp4k1h5/terminordle

or clone this repo

# clone this repo

git clone https://github.com/hp4k1h5/terminordle.git

# build the app

cd terminordle
yarn # or # npm i
yarn build # or # npm run build
# optional
yarn link # or # npm link

HELP

terminordle help

PLAY

if you installed globally (npm -g install @hp4k1h5/terminordle / yarn global add @hp4k1h5/terminordle) then you should have a global alias terminordle. You can also cd to this repo and run yarn link.

local single player

terminordle play

remote multiplayer

To start or join a multiplayer session you must know the address of a running terminordle server. See #serve. I currently have one running at wss://terminordle.fun. If the server is up and not overloaded, you can use it for your multiplayer sessions, or you can host your own. See data policy below.

The key command is join.

new session

To start a new multiplayer session include only the address of the server. If no address is provided, you will be connected to the default server at terminordle.fun. The following commands are functionally equivalent:

terminordle join 

terminordle join terminordle.fun

terminordle join wss://terminordle.fun

terminordle join wss://174.138.46.61:443

The server should respond with your user id and session name. These are both randomly chosen and cannot be changed. They are ephemeral. Share the session id with a friend so they can use it as shown below.

example response

welcome to terminordle
session id: session-name
user id: Yong
>>                      <<
abcdefghijklmnopqrstuvwxyz
▓ 

If you git cloned the app and haven't yarn linked you can cd into the repo and replace terminordle in the previous commands with npx terminordle.

user ids

The user id is chosen from the top one thousand most common names on Earth. The session-name is composed of two words chosen randomly from the word list. Share it with your friends and they can use it as shown below

join existing session

If you know the two-word name of a session, you can use a command like the following to join that session, replacing "session-name" with the actual name of the session you wish you join. Someone will have to share this with you, or you will have to run the above command to generate a valid session id, and then share that with your friends.

Replace "session-name" with the session name provided to another player when they created a session:

terminordle join -s session-name 

# or if you are joining another server
terminordle join 192.168.1.164 -s random-words
terminordle join 192.168.1.164:8080 -s random-words

If the url you provide does not include a protocol, ws:// is used as the default. Prefix your address with wss:// in order to communicate with a secure websocket connection. As of v0.1.3, terminordle.fun traffic is encrypted by letsencrypt.

terminordle join wss://secure.server:443
terminordle join wss://secure.server -s session-name

SERVE

Host your own terminordle server. The default host is '::', or 'localhost' and the default port is 8080. See data policy below. The app will create a logfile by default so as to enable some monitoring of the app by default. You can disable logs by setting --logfile /dev/null.

Examples:

terminordle serve

# change the port (default 8080)
terminordle serve 7357

# change the host (default 0.0.0.0 or ::)
terminordle serve -h 192.168.1.164 7357

# change the logfile path
terminordle serve -l /tmp/logfile.jsonl 80

wss support

1. Set the following env vars or add a .env file to the root directory of this repository, wherever that is found on your system. Use terminordle whereami to find a path. The .env should resemble the following with the paths changed to your own:

SSL_KEY_PATH="./path/to/key.key"
SSL_FULLCHAIN_PATH="./path/to/fullchain.pem"
NODE_ENV=production # optional if you prefix the serve command

2. run with env prefix or add this to your .env

NODE_ENV=production terminordle serve 443
NODE_ENV=production terminordle serve -h 0.0.0.0 443

This blog is a helpful guide to self-signed keys. And letsencrypt can provide you with externally signed certificates.

overview

The terminordle server is based on WebSockets and implements a standard websockets/ws message broker. This server is implemented on a "trust-free" model and tries to restrict user interaction to the barest minimum necessary for multiplayer wordle play.

This means that there are no accounts or long-lived users at all and the players are essentially limited to broadcasting guesses to their session. There is currently no authorization since there is virtually no user data at all, and nothing is being stored or tracked anywhere by this app. See data privacy.

This application uses no external database and manages all user and session data in the node runtime memory. It currently limits concurrent connections to 1,000, and has other sensible settings for the WebSocketServer that restrict its memory and cpu footprint to (hopefully) the minimum necessary to serve hundreds of clients simultaneously. To be determined. Currently the security model of the app is to limit user input to session requests, join requests and guesses. That's all. Outgoing includes session metadata, guesses and error/info messages.

Client input is validated client side and again server side before being processed. The risk of injection exists, but the only user input that should be able to be printed is a five-letter [a-zA-Z] guess. This is checked against wordlists and must meet other criteria limiting its ability to contain malicious strings. Please submit an issue or pr if you find security problems.

gameplay

Standard wordle rules mostly apply (mostly, submit an issue if there are discrepancies). Some deviations include the use of different sets of word lists, both for answers and guesses, more allowed guesses (currently 20), and multiplayer free-for-all mode.

data privacy

This application makes no attempts to log or store or analyze any user data with the non-exclusive list of exceptions below. These exceptions should only apply if you are using the application in network (multiplayer) mode, and you are connecting to a server managed by @hp4k1h5. If you are using it locally, this app collects no data. In other cases, this software and its contributing authors make NO claims as to the reliability of service, or safety of connecting to any server not managed by @hp4k1h5, or the integrity of data privacy guarantees offered by those providers. Other servers may be running modified or corrupted versions of this software or may have other data privacy policies that are not in alignment with those expressed here.

possible data collection exceptions

• hosting providers (e.g. digital ocean) may track and store your connection info, including ip addresses and other metadata associated with your connection. The server listed in the README is currently hosted by Digital Ocean (See digital ocean privacy policies).

• in the course of operating the server, logging of various game related data (guesses, session_ids, etc) may occur and may be stored somewhere on a server for a limited time. This is used to debug the game, and should not include client metadata.

• the guesses themselves and their associated fully-pseudonymous guesser and session may, at some point, be logged and retained as a data source. This is not currently happening and every effort would be made to warn users of associated changes. Currently all names are pseudonyms and there are no accounts of any kind, and any attempt to collect or use this type of data would be fully anonymized and would contain only the slightest risk of bearing actual user data (i.e. in the event that someone could post a series of guesses that was undesirable from a privacy or security standpoint. This data would never be associated to anything like an i.p. or other piece of personally identifying information.