ttyd-client 0.1.4

A Python client library for connecting to TTYD (tty over WebSocket) servers with full terminal support, authentication, and cross-platform compatibility

🖥️ TTYD Client

A cross-platform terminal client for TTYD WebSocket connections

English | Indonesia | 中文

---

English

📖 Overview

TTYD Client is a powerful, cross-platform terminal client that enables seamless connections to ttyd servers via WebSocket. It provides a native terminal experience with full support for escape sequences, special keys, and terminal multiplexers like tmux/byobu.

✨ Features

• 🌍 Cross-Platform Support: Works seamlessly on Linux, macOS, and Windows
• 🔐 Secure Authentication: Supports basic authentication with token-based access
• ⌨️ Full Keyboard Support: Captures all escape sequences including arrow keys, function keys, and control characters
• 🎨 Terminal Query Filtering: Automatically filters device control sequences to prevent unwanted responses
• 📺 Terminal Multiplexer Compatible: Works perfectly with tmux, screen, and byobu
• 🔄 Auto-Resize: Automatically adjusts terminal size on window resize (Unix/Linux/macOS)
• 🚀 High Performance: Efficient input/output handling with minimal latency

📦 Installation

From PyPI

pip install ttyd-client

Requirements

• Python 3.7+
• websocket-client
• requests

🚀 Usage

Basic Connection

ttyd-client http://localhost:7681

With Authentication

ttyd-client https://example.com:7681 --credential "username:password"

Disable SSL Verification

ttyd-client https://example.com:7681 --no-verify

Execute Command on Connect

ttyd-client http://localhost:7681 --cmd "ls -la"

Pass Arguments to Remote Shell

ttyd-client http://localhost:7681 --args bash --login

🛠️ Command Line Options

Option	Description
url	TTYD server URL (required)
--credential	Authentication in format "username:password"
--no-verify	Disable SSL certificate verification
--cmd	Command to execute on connection
--args	Arguments to pass to remote shell

🏗️ Architecture

ttyd_cli/
├── __init__.py          # Package initialization
├── __main__.py          # CLI entry point
├── auth.py              # Authentication handler
├── client.py            # Main WebSocket client
├── exceptions.py        # Custom exceptions
├── utils.py             # Utility functions
└── platforms/           # Platform-specific implementations
    ├── __init__.py
    ├── base.py          # Base input handler
    ├── unix.py          # Unix/Linux/macOS handler
    └── windows.py       # Windows handler

🔧 Advanced Features

Terminal Query Filtering

The client automatically filters terminal device control sequences such as:

• Color queries (OSC 10, 11, 12, 4)
• Device attribute queries (CSI > c, CSI ? c)
• Cursor position reports
• DCS/APC sequences

This prevents terminal responses from being interpreted as keyboard input.

Platform-Specific Input Handling

• Unix/Linux/macOS: Uses termios and tty for raw mode terminal control
• Windows: Uses msvcrt with special key mapping to ANSI sequences

📝 Examples

Connect to Local TTYD Server

# Start ttyd server
ttyd -p 7681 bash

# Connect with client
ttyd-client --url http://localhost:7681

Secure Connection with SSL

ttyd-client --url https://secure-server.com:443 --credential "admin:secret"

Use with Byobu/Tmux

ttyd-client --url http://localhost:7681 --cmd byobu

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Indonesia

📖 Gambaran Umum

TTYD Client adalah klien terminal lintas platform yang kuat, memungkinkan koneksi yang mulus ke server ttyd melalui WebSocket. Ini menyediakan pengalaman terminal native dengan dukungan penuh untuk escape sequences, tombol khusus, dan terminal multiplexer seperti tmux/byobu.

✨ Fitur

• 🌍 Dukungan Lintas Platform: Berfungsi dengan baik di Linux, macOS, dan Windows
• 🔐 Autentikasi Aman: Mendukung autentikasi dasar dengan akses berbasis token
• ⌨️ Dukungan Keyboard Penuh: Menangkap semua escape sequences termasuk tombol panah, function keys, dan karakter kontrol
• 🎨 Filtering Query Terminal: Secara otomatis memfilter device control sequences untuk mencegah respons yang tidak diinginkan
• 📺 Kompatibel dengan Terminal Multiplexer: Bekerja sempurna dengan tmux, screen, dan byobu
• 🔄 Auto-Resize: Secara otomatis menyesuaikan ukuran terminal saat window di-resize (Unix/Linux/macOS)
• 🚀 Performa Tinggi: Penanganan input/output yang efisien dengan latensi minimal

📦 Instalasi

Install dari PyPI

pip install ttyd-client

Persyaratan

• Python 3.7+
• websocket-client
• requests

🚀 Penggunaan

Koneksi Dasar

ttyd-client --url http://localhost:7681

Dengan Autentikasi

ttyd-client --url https://example.com:7681 --credential "username:password"

Nonaktifkan Verifikasi SSL

ttyd-client --url https://example.com:7681 --no-verify

Jalankan Perintah Saat Koneksi

ttyd-client --url http://localhost:7681 --cmd "ls -la"

Kirim Argumen ke Remote Shell

ttyd-client --url http://localhost:7681 --args bash --login

🛠️ Opsi Command Line

Opsi	Deskripsi
url	URL server TTYD (wajib)
--credential	Autentikasi dengan format "username:password"
--no-verify	Nonaktifkan verifikasi sertifikat SSL
--cmd	Perintah yang dijalankan saat koneksi
--args	Argumen untuk dikirim ke remote shell

🏗️ Arsitektur

ttyd_cli/
├── __init__.py          # Inisialisasi package
├── __main__.py          # Entry point CLI
├── auth.py              # Handler autentikasi
├── client.py            # WebSocket client utama
├── exceptions.py        # Exception kustom
├── utils.py             # Fungsi utilitas
└── platforms/           # Implementasi spesifik platform
    ├── __init__.py
    ├── base.py          # Base input handler
    ├── unix.py          # Handler Unix/Linux/macOS
    └── windows.py       # Handler Windows

🔧 Fitur Lanjutan

Filtering Query Terminal

Klien secara otomatis memfilter device control sequences terminal seperti:

• Query warna (OSC 10, 11, 12, 4)
• Query atribut perangkat (CSI > c, CSI ? c)
• Laporan posisi kursor
• Sequences DCS/APC

Ini mencegah respons terminal ditafsirkan sebagai input keyboard.

Penanganan Input Spesifik Platform

• Unix/Linux/macOS: Menggunakan termios dan tty untuk kontrol terminal mode raw
• Windows: Menggunakan msvcrt dengan pemetaan tombol khusus ke sequences ANSI

📝 Contoh

Koneksi ke Server TTYD Lokal

# Jalankan ttyd server
ttyd -p 7681 bash

# Koneksi dengan client
ttyd-client --url http://localhost:7681

Koneksi Aman dengan SSL

ttyd-client --url https://secure-server.com:443 --credential "admin:secret"

Gunakan dengan Byobu/Tmux

ttyd-client --url http://localhost:7681 --cmd byobu

🤝 Kontribusi

Kontribusi sangat diterima! Silakan kirimkan Pull Request.

📄 Lisensi

Proyek ini dilisensikan di bawah MIT License - lihat file LICENSE untuk detail.

---

中文

📖 概述

TTYD Client 是一个强大的跨平台终端客户端，可通过 WebSocket 无缝连接到 ttyd 服务器。它提供原生终端体验，完全支持转义序列、特殊键和终端复用器（如 tmux/byobu）。

✨ 特性

• 🌍 跨平台支持：在 Linux、macOS 和 Windows 上无缝运行
• 🔐 安全认证：支持基于令牌访问的基本身份验证
• ⌨️ 完整键盘支持：捕获所有转义序列，包括方向键、功能键和控制字符
• 🎨 终端查询过滤：自动过滤设备控制序列以防止不需要的响应
• 📺 终端复用器兼容：与 tmux、screen 和 byobu 完美配合
• 🔄 自动调整大小：窗口调整大小时自动调整终端大小（Unix/Linux/macOS）
• 🚀 高性能：高效的输入/输出处理，延迟最小

📦 安装

从 PyPI 安装

pip install ttyd-client

要求

• Python 3.7+
• websocket-client
• requests

🚀 使用方法

基本连接

ttyd-client --url http://localhost:7681

使用身份验证

ttyd-client --url https://example.com:7681 --credential "username:password"

禁用 SSL 验证

ttyd-client --url https://example.com:7681 --no-verify

连接时执行命令

ttyd-client --url http://localhost:7681 --cmd "ls -la"

向远程 Shell 传递参数

ttyd-client --url http://localhost:7681 --args bash --login

🛠️ 命令行选项

选项	描述
url	TTYD 服务器 URL（必需）
--credential	格式为 "username:password" 的身份验证
--no-verify	禁用 SSL 证书验证
--cmd	连接时执行的命令
--args	传递给远程 shell 的参数

🏗️ 架构

ttyd_cli/
├── __init__.py          # 包初始化
├── __main__.py          # CLI 入口点
├── auth.py              # 身份验证处理器
├── client.py            # 主 WebSocket 客户端
├── exceptions.py        # 自定义异常
├── utils.py             # 实用函数
└── platforms/           # 平台特定实现
    ├── __init__.py
    ├── base.py          # 基础输入处理器
    ├── unix.py          # Unix/Linux/macOS 处理器
    └── windows.py       # Windows 处理器

🔧 高级功能

终端查询过滤

客户端自动过滤终端设备控制序列，例如：

• 颜色查询（OSC 10、11、12、4）
• 设备属性查询（CSI > c、CSI ? c）
• 光标位置报告
• DCS/APC 序列

这可以防止终端响应被解释为键盘输入。

平台特定输入处理

• Unix/Linux/macOS：使用 termios 和 tty 进行原始模式终端控制
• Windows：使用 msvcrt，将特殊键映射到 ANSI 序列

📝 示例

连接到本地 TTYD 服务器

# 启动 ttyd 服务器
ttyd -p 7681 bash

# 使用客户端连接
ttyd-client --url http://localhost:7681

使用 SSL 的安全连接

ttyd-client --url https://secure-server.com:443 --credential "admin:secret"

与 Byobu/Tmux 一起使用

ttyd-client --url http://localhost:7681 --cmd byobu

🤝 贡献

欢迎贡献！请随时提交 Pull Request。

📄 许可证

该项目根据 MIT 许可证授权 - 有关详细信息，请参阅 LICENSE 文件。

---

🌟 Star History

Made with ❤️ by krypton-byte