Metadata-Version: 2.4
Name: chatlan
Version: 0.1.1
Summary: a TUI program to chat with friends on a LAN
License-Expression: MIT
Keywords: Chat,LAN,TUI,CLI,terminal
Author: gitmobkab
Author-email: richmondaurel77@gmail.com
Requires-Python: >=3.13,<4.0
Classifier: Environment :: Console
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: textual (>=6.9.0,<7.0.0)
Requires-Dist: typer (>=0.20.0,<0.21.0)
Project-URL: Repository, https://github.com/gitmobkab/ChatLan
Description-Content-Type: text/markdown

# ChatLan

![preview image](images/preview.png)

## an easy to use chat app command line interface tool

**ChatLan** is a lightweight command-line interface (CLI) tool designed to facilitate peer-to-peer chatting over a Local Area Network (LAN). It allows users to easily spin up a chat server and connect to it from different machines on the same network without complex configuration.


# Table Of Contents
- [Install](#install)
- [Quick Overview](#quick-overview)
- [Commands](#commands)
    - [Initialize a Chatlan server (init)](#init)
    - [Connect To a ChatLan Server (connect)](#connect)
- [Examples](#examples)
- [Notes and Limitations](#notes-and-limitations)
- [Planned Features](#planned-features)


# Install
In order to use **ChatLan**, you must install it with the following command:

```bash
pip install chatlan
```

# Quick overview

In order to use **Chatlan** you have two options
- [Start a Chatlan server (init) ](#init) 
- [Connect to a ChatLan server](#connect)

the most common use flow being the following

1. First, let's start a ChatLan Server with the command:

```bash
$ chat init
```
this will show the following screen:
![server app TUI](images/server_startup.png)

- **At your left is a list of all the poeple connected to the server as a the table**

for example:

| username | address      |
-----------|--------------|
|    you   | 192.168.1.9  |
|    mobsy | 192.168.1.25 |
|    mob   | 192.168.1.11 |

> [!NOTE]
> The First row is always the server

- **At your right is the Chat View Were everything every events(New Connection/Disconnection,etc) /messages are displayed**

> [!NOTE]
> For now the server doesn't can't send it's own messages, will be implemented in the next update

2. In order for anyone to chat just need to use the following command:

```bash
$ chat connect ADDRESS 
```

for example if someone wants to connect to the server '192.168.1.9:8888' as 'Mobsy'
they must run
```bash
$ chat connect 192.168.1.9:8888 -u Mobsy
# or also
$ chat connect -u Mobsy 192.168.1.9:8888
```

Then the user can chat as Mob as long as the server is running:

![The Client App Interface](images/client_app.png)

> [!IMPORTANT]
> **The Users and The Server must be on the same network/wifi** 

# Commands

**chatlan** is in the first place a command line interface program (CLI)
the command name of the **ChatLan** is **chat**

the availvable commands are:
 - chat
 - [chat init](#init)
 - [chat connect](#connect)

the chat command doesn't do anythig by itself, except displaying a help menu

```bash
$ chat
```

this will show the following
![chat command help menu](images/chat_command.png)

- ## init

**Usage: chat init [options]** 

> **Initialize a chatlan server at the host ip address**

![init command help menu](images/init_command.png)

- options:
    - -p, --port \<PORT> [DEFAULT: 8888]: 
    
        \<PORT> must be an integer between 8000 and 9000

        **if ignored the default ChatLan PORT (8888) is used**
    
    - -- help:
        
        Display the help menu

- ## connect

**Usage: chat connect \<ADDRESS> [options]**

> **Connect to a ChatLan Server**

![connect command help menu](images/connect.png)

- arguments:
    - \<ADDRESS>:

        the address of the ChatLan Server.
        
        this argument is a string in the format IP:PORT

        i.e: 
            
            192.168.1.9:8888
            192.168.1.10:8888

    > [!NOTE]
    > The any ADDRESS with '127.0.0.1' as the IP are invalid

- options:
    - -u, --username [DEFAULT: your machine hostname]:

        this option is the name you wish to use for the chat session.

        by default your username is your machine hostname

        i.e: 'mob-hpprobook'

        > [!NOTE]
        > If your username contains spaces you must surround it with quotes or double quotes **(i.e: "Cool User")**
    

# Examples

In This section are snippets on actual use case of ChatLan

**Starting A ChatLan Server**

The most basic approach is to use

```bash
$ chat init
```

note that this running the above command will start a ChatLan Server on the **8888** port.

### Why is this important ? 
This is due to the fact that the server must be started on a port that's not used by any programm

for example the vscode extension Live server/Five Server runs on the 8000 port 

so if you have Live Server Running on and run `chat init -p 8000`

**ChatLan won't be able to start the server as Live Server is already using the 8000 port**

This also means that if you run `chat init` and see an error this is very likely because another service is already using the 8888 port

To solve this you must try to run The ChatLan server on another port 8815 for example

> [!IMPORTANT]
> In This Version ChatLan doesn't prevent you to start a server  on an 'unreachable address' an address is juged unreachable if the IP part of the ADDRESS is either 127.0.0.1 or 0.0.0.0


## Connecting to a ChatLan Server

**In order o connect to a ChatLan server you must check two thing**

1. your computer is connected to a LAN or WLAN (wifi for example)

2. A ChatLan Server is running

3. Your Computer and The ChatLan Server are on the same network

the most 'rough' use of the connect command is:

```bash
$ chat connect <ADDRESS>
```

> [!NOTE]
> When a ChatLan server is started it will display 'Server Started Successfully at ADDRESS' in the first line of the Chat View, the ADDRESS is what the clients must pass to chat connect

for example let's say i wanna connect to the ChatLan server 192.168.1.9:8888

i'll run
```bash
$ chat connect 192.168.1.9:8888
```

this will connect me to the server as 'mob-hpprobook' 

# why 'mob-hpprobook' ? that's oddly specific...

Well if you run `chat connect` without using the -u,--username option ChatLan is going to use your machine hostname as your username

In my case this is 'mob-hpprobook'

# What if i want to have a cool username ?

Simple, just add the -u or --username option followed by your USERNAME

for example if i prefer 'Mobsy' rather than 'mob-hpprobook'

i just need to run

```bash
$ chat connect <ADDRESS> -u Mobsy
# or
$ chat connect -u Mobsy <ADDRESS>
``` 

in our previous example this will be
```bash
$ chat connect 192.168.1.9:8888 -u Mobsy
# or
$ chat connect -u Mobsy 192.168.1.9:8888
```

> [!NOTE]
> If the username you wish to use contains Spaces like 'Cool User 2025' you must surround the USERNAME with quotes (') or double quotes (")

```bash
$ chat connect 192.168.1.9:8888 -u "Cool User 2025"
# or
$ Chat connect -u "Cool User 2025" 192.168.1.9:8888
```

# Notes & limitations

> [!IMPORTANT]
> No Secure Messaging System: **The message aren't actually encrypted, so don't use ChatLan for a professional/marketing context**

- Same network required: Clients and server must be on the same LAN/Wi-Fi network.

- No server-side chat input (yet): Server cannot send messages from the UI in this release — planned for the next update.

- User table: The server TUI shows connected users dynamically (username + IP). Disconnects are handled and reflected in the table.

-  Address validation: Addresses containing 127.0.0.1 are treated as invalid for client connections (client must reach server on LAN IP).

# Planned features: 

- [ ] server broadcast input
- [ ] message widget UI.
- [ ] user random colors.

