termchat-client 💬🖼️

termchat-client is a lightweight, non-intrusive terminal chat client packaged for Python. It connects directly to an online chat server (running on Render or any cloud host), allowing you to chat seamlessly between your terminal and an online HTML web page viewed by others.

💡 How It Works

• Standard Terminal Interaction: It does not change or take over your terminal UI. No fullscreen ncurses/curses screens. Just a normal, standard prompt line where you type text and press Enter.
• Bi-Directional Messaging:
  • You type text in your terminal ➔ It appears instantly on the web page.
  • Web users type replies ➔ They print right into your terminal: [🌐 WebUser]: Hello from Chrome!
• Image Support to Terminal:
  • Web users can click the image picker, drag & drop images, or press Ctrl+V to paste screenshots directly from their clipboard!
  • When an image is sent from the web, your terminal automatically:
    1. Downloads the image locally into ./downloads/
    2. Prints the image URL and filename
    3. Renders a compact ANSI 24-bit color block thumbnail preview directly inside your terminal!
    4. Can auto-open the image in your OS default image viewer with --open or /open.
• Works on Any OS: Windows (PowerShell / CMD / Windows Terminal), Linux (Debian, Ubuntu, Arch), Raspberry Pi (ARMv7 / aarch64), and macOS.

🏛️ System Architecture

 ┌─────────────────────────────────────────────────────────────┐
 │                 Online Server on Render                     │
 │          (FastAPI + WebSockets + Image Upload API)          │
 │              https://my-chat.onrender.com                   │
 └──────────────▲───────────────────────────────▲──────────────┘
                │                               │
     WebSocket  │                    WebSocket  │  + HTTP Web UI
     Connection │                    Connection │  (HTML5 / CSS / JS)
                │                               │
  ┌─────────────┴──────────┐      ┌─────────────┴─────────────┐
  │  termchat-client (CLI) │      │      Web Client (HTML)    │
  │  • Linux / Raspberry Pi│      │  • Desktop Browsers       │
  │  • Windows CMD / PS    │      │  • Mobile Browsers (iOS)  │
  │  • macOS Terminal      │      │  • Paste Images (Ctrl+V)  │
  │  (Just text in & out)  │      │  • Drag & Drop Images     │
  └────────────────────────┘      └───────────────────────────┘

📦 Installation

Install the client package on any machine:

pip install termchat-client

🚀 Terminal Client Usage

1. Run via CLI

termchat --server https://my-chat.onrender.com --name Alice

Or via Python module:

python -m termchat --server https://my-chat.onrender.com --name Alice

2. Save Your Server Once

Save your online server URL so you never need to type it again:

termchat --set-server https://my-chat.onrender.com
termchat --set-name Alice

Once saved, simply run:

termchat

or:

python -m termchat

3. What It Looks Like in Your Terminal:

--- termchat connected ---
User:   Alice
Server: https://my-chat.onrender.com
Web UI: https://my-chat.onrender.com
Commands: /help, /open (view last image), /quit
---------------------------

Connected! Start typing text below (Press Enter to send):

> Hello from my Raspberry Pi terminal!

[🌐 Web] Bob: Hey Alice! Check out this screenshot:
[🌐 Web] Bob 📷 Sent an image: dashboard.png
  URL: https://my-chat.onrender.com/uploads/dashboard.png
  Saved locally: C:\projects\terminal-chat\downloads\dashboard.png

  [ANSI Image Thumbnail rendered here]

> 

In-Terminal Commands:

• /open — Opens the last received image in your OS default image viewer (Photos, Preview, or xdg-open).
• /web — Prints the Web UI link.
• /help — Lists available commands.
• /quit (or Ctrl+C) — Safely exits.

Optional Flags:

• --open: Automatically opens any received image in your OS default image viewer.
• --no-thumb: Disables terminal ANSI thumbnail previews (prints URL and saved path only).

🌐 Deploying the Server to Render (Free)

The server code lives in the server/ directory and can be deployed to Render in 2 minutes for free.

See DEPLOY_RENDER.md for full instructions:

1. Push this repository to GitHub.
2. In Render, click New + > Web Service and connect your GitHub repo.
3. Set Root Directory to server.
4. Set Start Command to uvicorn main:app --host 0.0.0.0 --port $PORT.
5. Deploy! Render gives you a live HTTPS and WebSocket URL like https://my-chat.onrender.com.

📤 Publishing to PyPI

The package is packaged using modern PEP 517 / PEP 621 (pyproject.toml).

1. Build distributions:

   python -m build
   

2. Verify with Twine:

   twine check dist/*
   

3. Upload to PyPI:

   twine upload dist/*
   

   (Or run the included interactive helper: python publish.py)

See PUBLISHING.md for step-by-step instructions.

🧪 Testing

Run the automated test suite:

python -m pytest -v

📄 License

MIT License. See LICENSE for details.