KB8PMY
/
TermTCP
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from 'e36cff11d4'
${ noResults }
TermTCP/README_CLI.md

7.8 KiB
Raw Blame History

TermTCP - Command Line TCP Terminal Client

A lightweight, zero-dependency command-line TCP client for connecting to TCP servers and BBS systems.

Features

  • ✅ Minimal Dependencies - No GUI libraries, just standard C POSIX
  • ✅ Multiple Host Support - Store and quickly connect to configured hosts
  • ✅ Session Logging - Automatic timestamped logging of all traffic
  • ✅ Color Output - Optional ANSI color for better readability
  • ✅ Non-blocking I/O - Responsive input/output handling
  • ✅ Command System - Built-in commands for connection management
  • ✅ Configuration File - Easy setup via ~/.termtcprc
  • ✅ Lightweight - Single C file, ~400 lines

Quick Start

Build

make -f Makefile_CLI
./termtcp

First Run

The application will create ~/.termtcprc with default configuration.

Connect

> connect 0          # Connect to first configured host
> list               # Show all configured hosts
> status             # Show connection status

Send Data

> Type anything here (not starting with /) to send to server
> Hello, BBS!        # Sends "Hello, BBS!\r"

Disconnect

> disconnect         # Close connection
> quit               # Exit the application

Configuration

Edit ~/.termtcprc to add hosts:

# Format: host port name
# Comments start with #

localhost 8011 Local BBS
example.com 8011 Remote BBS
bbs.example.net 9000 Another System

Commands

Connection Commands

connect [N]      - Connect to host N (default: 0)
disconnect       - Close current connection
status           - Show connection status
list             - List all configured hosts

Session Commands

log on           - Enable session logging
log off          - Disable logging
color on         - Enable colored output
color off        - Disable colored output

Help & Exit

help             - Show command list
quit             - Disconnect and exit
exit             - Same as quit

Command-Line Options

termtcp [OPTIONS]

Options:
  -c, --connect N    Auto-connect to host N on startup
  -l, --log          Enable logging on startup
  -n, --no-color     Disable colored output
  -h, --help         Show help message

Examples

Connect and Log Automatically

termtcp -c 0 -l
# Connects to host 0 and starts logging

No Color Mode

termtcp -n
# Runs without ANSI colors

Standard Usage

termtcp
# Starts interactive, allows manual connection

Logging

When logging is enabled:

  • Creates timestamped log files in current directory
  • Format: hostname_port_YYYYMMDD_HHMMSS.log
  • Records both sent and received data with timestamps
  • Automatic log opening when connecting
  • Use log off to disable

Example log entry:

[14:35:22] SEND: Hello, World
[14:35:23] RECV: Welcome to the system!

Building

Dependencies

  • GCC or Clang
  • POSIX-compliant system (Linux, macOS, BSD)
  • Standard C library

Compilation

# Standard build
gcc -Wall -O2 -o termtcp termtcp_cli.c

# Or use Makefile
make -f Makefile_CLI

Make Targets

make -f Makefile_CLI build    # Build
make -f Makefile_CLI run      # Build and run
make -f Makefile_CLI debug    # Debug build
make -f Makefile_CLI install  # Install to /usr/local/bin/
make -f Makefile_CLI clean    # Remove artifacts

Usage Patterns

Simple Connection

$ termtcp
> list
Configured Hosts:
  [0] localhost:8011 - Local BBS
  [1] example.com:8011 - Remote BBS

> connect 0
Connecting to localhost:8011...
Connected to: Local BBS

[Status] Connected to localhost:8011

> help
Available Commands:
  connect [host#]  - Connect to a host (default: 0)
  ...

> Hello there!

Scripted/Automated Connection

# Auto-connect and log
termtcp -c 0 -l

# Non-interactive, pipe commands
echo -e "connect 0\nQUERY\nquit" | termtcp

Session Logging for Support

> log on
> [do something that fails]
> log off

# Now you have a complete log to send to support

Configuration File Format

The ~/.termtcprc file is simple text format:

# Comments start with #
# Empty lines are ignored
# Format: hostname port shortname

# BBS Systems
bbs1.example.com 9000 BBS One
bbs2.example.com 9000 BBS Two

# Local Services
localhost 3000 Local Dev
192.168.1.10 8080 Lab Server

# Remote Services
production.example.com 443 Production

Notes:

  • Hostname: Can be IP or FQDN
  • Port: Numeric port number (1-65535)
  • Shortname: Display name, no spaces

Troubleshooting

"Connection timeout"

  • Check hostname/IP is correct
  • Check port number is correct
  • Verify the server is running
  • Check firewall settings

"Connection refused"

  • Server is not listening on that port
  • Check port number
  • Server may be down

"Failed to resolve hostname"

  • Check DNS configuration
  • Try using IP address instead
  • Check hostname spelling

Terminal appears frozen

  • Press Ctrl+C to interrupt
  • Type quit and Enter to exit gracefully

Characters not displaying

  • Try color off if color codes appear
  • Check terminal encoding (should be UTF-8)

Performance

  • Memory Usage: ~50KB
  • CPU Usage: Minimal (event-driven)
  • Binary Size: ~40KB (stripped)
  • Startup Time: <100ms
  • Max Line Length: 512 bytes

Technical Details

Implementation

  • Single-threaded event loop using select()
  • Non-blocking socket I/O
  • Raw terminal mode for responsive input
  • Efficient circular buffering for display

Compatibility

  • Linux: Full support
  • macOS: Full support
  • BSD: Full support
  • Windows: Possible with Cygwin/WSL

Signal Handling

  • SIGTERM: Graceful shutdown
  • SIGINT (Ctrl+C): Immediate exit

Limitations

  • Maximum line length: 512 characters
  • Maximum hosts in config: 5
  • Single connection at a time
  • No TLS/SSL support (use tools like openssl s_client for secure connections)
  • No proxy support (use SSH tunneling instead)

Future Enhancements

  • IPv6 support
  • Scripting/automation interface
  • Terminal scrollback buffer
  • Search in history
  • Aliases for commands
  • Custom prompt configuration
  • Binary mode (for file transfer)

Comparison: CLI vs GTK3 Version

Feature CLI GTK3
Dependencies None GTK3 dev files
Binary Size 40KB 500KB+
Memory 50KB 20MB+
Startup <100ms 500ms+
GUI No Yes
Multiple Connections No Yes (planned)
Port Monitoring No Yes
Scripting Yes No
Configuration .termtcprc GUI + ini file

Installation

From Source

git clone <repo>
cd termtcp
make -f Makefile_CLI install
termtcp

Pre-built (if available)

sudo apt install termtcp      # Ubuntu/Debian
sudo dnf install termtcp      # Fedora

Creating a Desktop Entry

On Linux, create ~/.local/share/applications/termtcp.desktop:

[Desktop Entry]
Type=Application
Name=TermTCP
Exec=gnome-terminal -- termtcp
Terminal=true
Categories=Utility;Network;

Examples & Use Cases

Connect to a BBS

# Edit ~/.termtcprc with BBS addresses
termtcp
> connect 0
> help

System Monitoring

# Check system metrics from a remote server
termtcp -c 0
> STATUS
> QUERY

Testing TCP Services

# Quick test of a TCP service
termtcp -c 0
> HELLO
> [see response]
> quit

Log Everything for Debugging

termtcp -l
> connect 0
> [do something]
> log on
> [reproduce issue]
> log off

Getting Help

  • Type help in the application
  • Check ~/.termtcprc for configuration examples
  • Review this README
  • Check application output for error messages

License

Same as TermTCP project.

Version History

  • v1.0.0 (2026-06-23) - Initial CLI release
    • Basic TCP connectivity
    • Command system
    • Session logging
    • Configuration file support

TermTCP CLI - Lightweight TCP terminal client for power users.

Start with: make -f Makefile_CLI && ./termtcp

Powered by TurnKey Linux.