🚀 ctty - Connection Manager

A lightweight, all-in-one connection manager — SSH, serial, and SFTP in a single TUI 🔥

ctty is a fast, native terminal tool for managing all your connections — SSH hosts, serial devices, and SFTP file transfers — without the overhead of Electron apps. Built with Go and featuring an intuitive TUI interface, it brings the convenience of GUI connection managers like Tabby to the terminal, with zero bloat.

Why ctty?

Tabby too heavy? ctty is a single ~5MB binary, no Electron, no browser engine — just pure Go
Need serial + SSH + SFTP in one tool? Most terminal emulators only do SSH; ctty covers all three
Want to stay in the terminal? No context switching between apps — everything is keyboard-driven

🖱️ Click on the image to view in full size

✨ Features

🚀 Core Capabilities

🎨 Beautiful TUI Interface - Navigate your SSH hosts with an elegant, interactive terminal UI
⚡ Quick Connect - Connect to any host instantly through the TUI or the CLI with ctty <host>
🔄 Port Forwarding - Easy setup for Local, Remote, and Dynamic (SOCKS) forwarding with history persistence
📝 Easy Management - Add, edit, move, and manage SSH configurations seamlessly
🏷️ Tag Support - Organize your hosts with custom tags with automatic color-coding (e.g., #prod in red, #dev in green, #db in purple) and custom color configuration; use the special hidden tag to exclude hosts from the list while keeping them connectable
🔍 Smart Search - Find hosts quickly with built-in filtering and search
📝 Real-time Status - Live SSH connectivity indicators with asynchronous ping checks and color-coded status
🔌 Serial Connections - Manage and connect to serial devices (console, switch, router) with configurable baud rate, data bits, parity, and stop bits; auto-detected ports appear in the list instantly
🔑 Password Storage & Zero-Touch Auto-Login - Save SSH passwords securely in a local AES-256-GCM encrypted vault (~/.config/ctty/credentials.json, 0600 permissions) with native OpenSSH SSH_ASKPASS protocol bridge (zero third-party dependencies, works on macOS, Linux, Windows, and Termux)
🖥️ Split-Pane & Small Terminal Friendly - All forms and dialogs (Add/Edit Host, Port Forwarding, Host Info, Help Menu) feature focus-following dynamic viewport scrolling with fixed headers/footers. Works flawlessly in tmux/Zellij splits, VS Code/JetBrains embedded terminals, and tiling WMs (i3/Sway) down to 8~12 lines with zero height blocking or truncation
🌐 Bilingual i18n & Settings UI - Full English and Simplified Chinese support with automatic OS detection (macOS, Windows, Linux, Termux) and interactive in-TUI Settings menu (S key) to configure language, updates, and keybindings

🛠️ Technical Features

🔒 Secure - Works directly with your existing ~/.ssh/config file (credentials stored separately, never pollutes standard SSH configs)
📁 Custom Config Support - Use any SSH configuration file with the -c flag
📂 SSH Include Support - Full support for SSH Include directives to organize configurations across multiple files
⚙️ SSH Options Support - Add any SSH configuration option through intuitive forms
🔄 Automatic Conversion - Seamlessly converts between command-line and config formats
🔄 Automatic Backups - Backup configurations automatically before changes
✅ Validation - Prevent configuration errors with built-in validation
🔗 ProxyJump/ProxyCommand Support - Secure connection tunneling through bastion hosts
⌨️ Keyboard Shortcuts - Power user navigation with vim-like shortcuts and universal Tab/Shift+Tab focus cycling
🌐 Cross-platform - Supports Linux, macOS (Intel & Apple Silicon), Windows, and Android (Termux)
⚡ Lightweight - Single binary with no dependencies, zero configuration required

🚀 Quick Start

Installation

Homebrew (Recommended for macOS):

brew install zsuroy/ctty/ctty

Unix/Linux/macOS (One-line install):

curl -sSL https://raw.githubusercontent.com/zsuroy/ctty/master/install/unix.sh | bash

Termux (Android):

curl -sSL https://raw.githubusercontent.com/zsuroy/ctty/master/install/unix.sh | bash

The installer auto-detects Termux (via $PREFIX/$TERMUX_VERSION) and installs to $PREFIX/bin without sudo.

Windows (PowerShell):

irm https://raw.githubusercontent.com/zsuroy/ctty/master/install/windows.ps1 | iex

Alternative methods:

Linux/macOS:

# Download specific release
wget https://github.com/zsuroy/ctty/releases/latest/download/ctty-linux-amd64.tar.gz

# Extract and install
tar -xzf ctty-linux-amd64.tar.gz
sudo mv ctty-linux-amd64 /usr/local/bin/ctty

Windows:

# Download and extract
Invoke-WebRequest -Uri "https://github.com/zsuroy/ctty/releases/latest/download/ctty-windows-amd64.zip" -OutFile "ctty-windows-amd64.zip"
Expand-Archive ctty-windows-amd64.zip -DestinationPath C:\tools\
# Add C:\tools to your PATH environment variable

From source (requires Go 1.23+):

git clone https://github.com/zsuroy/ctty.git
cd ctty
go build -o ctty .
sudo mv ctty /usr/local/bin/

📖 Usage

Interactive Mode

Launch ctty without arguments to enter the beautiful TUI interface:

ctty

Navigation:

↑/↓ or j/k - Navigate hosts
Enter - Connect to selected host
a - Add new host
e - Edit selected host
d - Delete selected host
m - Move host to another config file (requires SSH Include directives)
i - Show host configuration info
p - Ping all hosts to check connectivity
f - Setup port forwarding
t - Open serial device manager
o - Open SFTP file browser for selected host
S - Open Settings & Preferences (Language, Updates, ESC behavior)
H - Toggle hidden hosts visibility
h - Open help screen
q - Quit
/ - Search/filter hosts

Real-time Status Indicators:

🟢 Online - Host is reachable via SSH
🟡 Connecting - Currently checking host connectivity
🔴 Offline - Host is unreachable or SSH connection failed
⚫ Unknown - Connectivity status not yet determined

Sorting & Filtering:

s - Cycle through all sort modes (Name ➔ Hostname ➔ Tags ➔ Last Login)
n - Sort by name (alphabetical)
r - Sort by recent (last login time)
Tab - Switch focus between search input and table
Type to search - Real-time filtering across name, hostname, and #tags

The interactive forms will guide you through configuration:

Hostname/IP - Server address
Username - SSH user
Port - SSH port (default: 22)
Identity File - Private key path
ProxyJump - Jump server for connection tunneling
ProxyCommand - Jump command for connection tunneling
SSH Options - Additional SSH options in -o format (e.g., -o Compression=yes -o ServerAliveInterval=60)
Tags - Comma-separated tags for organization

Serial Connections

Press t from the main TUI to enter the serial device manager. Available serial ports are auto-detected and listed immediately — no manual setup required for quick access.

Serial device list:

Detected ports appear automatically with default settings (115200 8N1)
Saved devices (with custom names and settings) appear at the top
Enter - Connect to selected serial device
i - Show device info (name, port, baud, parity, etc.)
a - Add a new serial device with custom settings
d - Delete a saved serial device
/ - Search/filter devices by name or port path
Esc/q - Return to SSH host list

Device info view:

e or Enter - Edit parameters (baud rate, data bits, parity, stop bits) before connecting
Esc/i - Back to device list

Adding a serial device:

Name - Friendly alias (e.g., Switch-Console)
Device - Port path (e.g., /dev/cu.usbserial-1420); use ←/→ to pick from detected ports
Baud Rate - Default: 115200
Data Bits - 5, 6, 7, or 8 (default: 8)
Parity - none, even, or odd (default: none)
Stop Bits - 1 or 2 (default: 1)

Editing parameters before connect:

Baud rate can be typed directly or cycled via ←/→ through presets (9600/19200/38400/57600/115200/230400/460800/921600)
Press Enter to connect with the modified parameters

Connecting: The TUI suspends and bridges your terminal directly to the serial port. Press Ctrl+] or Ctrl+C to disconnect and return to the TUI.

You can also launch the serial manager directly:

ctty serial    # Skip the SSH host list, go straight to serial devices

SFTP File Transfer

While selected an SSH host, press o to open the SFTP file browser. The SFTP interface provides a full-featured file transfer experience directly in your terminal:

SFTP Browser Features:

Remote and local file browsing
Upload/download with progress and cancel
Search functionality (/ key) for both remote and local files
Two-line help for better readability
Clear [LOCAL] and [REMOTE] labels (no confusing emoji)
Error handling with friendly messages

SFTP Navigation:

↑/↓ or j/k - Navigate files
→/l or Enter - Enter directory / download file (remote) / upload file (local)
←/h or Backspace - Go to parent directory
u - Switch to local file browser for upload
d - Delete selected file (remote only)
n - Create new directory (remote only)
r - Refresh file list
/ - Search/filter files
Esc - Cancel current operation / return to SSH session

Uploading Files:

Press u to switch to local file browser
Navigate to the file you want to upload
Press Enter to upload to the current remote directory
Monitor progress in the status bar
Press Esc to cancel upload (returns to remote file list)

Downloading Files:

Navigate to the file you want to download
Press Enter to download to your local download directory (~/Downloads/ctty)
Monitor progress in the status bar
Press Esc to cancel download (returns to remote file list)

Searching Files:

Press / to enter search mode
Type to filter files by name (real-time filtering)
Press Enter or Tab to confirm selection
Press Esc to cancel search and restore full file list

Error Handling:

If SFTP fails to start, you'll see a friendly error message: ❌ SFTP Error: failed to start SFTP session.
Press Esc to return to the SSH session
Your SSH connection remains active for other operations

You can also launch the SFTP file browser directly from the command line:

ctty sftp prod-server    # Open SFTP browser directly for a host

Port Forwarding

ctty provides an intuitive interface for setting up SSH port forwarding. Press f while selecting a host to open the port forwarding setup:

Forward Types:

Local (-L) - Forward a local port to a remote host/port through the SSH connection
- Example: Access a remote database on localhost:5432 via local port 15432
- Use case: ssh -L 15432:localhost:5432 server → Database accessible on localhost:15432
Remote (-R) - Forward a remote port back to a local host/port
- Example: Expose local web server on remote host's port 8080
- Use case: ssh -R 8080:localhost:3000 server → Local app accessible from remote host's port 8080
- ⚠️ Requirements for external access:
  - SSH Server Config: Add GatewayPorts yes to /etc/ssh/sshd_config and restart SSH service
  - Firewall: Open the remote port in the server's firewall (ufw allow 8080 or equivalent)
  - Port Availability: Ensure the remote port is not already in use
  - Bind Address: Use 0.0.0.0 for external access, 127.0.0.1 for local-only
Dynamic (-D) - Create a SOCKS proxy for secure browsing
- Example: Route web traffic through the SSH connection
- Use case: ssh -D 1080 server → Configure browser to use localhost:1080 as SOCKS proxy
- ⚠️ Configuration requirements:
  - Browser Setup: Configure SOCKS v5 proxy in browser settings
  - DNS: Enable "Proxy DNS when using SOCKS v5" for full privacy
  - Applications: Only SOCKS-aware applications will use the proxy
  - Bind Address: Use 127.0.0.1 for security (local access only)

Port Forwarding Interface:

Choose forward type with ←/→ arrow keys
Configure ports and addresses with guided forms
Optional bind address configuration (defaults to 127.0.0.1)
Real-time validation of port numbers and addresses
Port forwarding history - Save frequently used configurations for quick reuse
Connect automatically with configured forwarding options

Troubleshooting Port Forwarding:

Remote Forwarding Issues:

# Error: "remote port forwarding failed for listen port X"
# Solutions:
1. Check if port is already in use: ssh server "netstat -tln | grep :X"
2. Use a different port that's available
3. Enable GatewayPorts in SSH config for external access

SSH Server Configuration for Remote Forwarding:

# Edit SSH daemon config on the server:
sudo nano /etc/ssh/sshd_config

# Add or uncomment:
GatewayPorts yes

# Restart SSH service:
sudo systemctl restart sshd  # Ubuntu/Debian/CentOS 7+
# OR
sudo service ssh restart     # Older systems

Firewall Configuration:

# Ubuntu/Debian (UFW):
sudo ufw allow [port_number]

# CentOS/RHEL/Rocky (firewalld):
sudo firewall-cmd --add-port=[port_number]/tcp --permanent
sudo firewall-cmd --reload

# Check if port is accessible:
telnet [server_ip] [port_number]

Dynamic Forwarding (SOCKS) Browser Setup:

Firefox: about:preferences → Network Settings
- Manual proxy configuration
- SOCKS Host: localhost, Port: [your_port]
- SOCKS v5: ✓
- Proxy DNS when using SOCKS v5: ✓

Chrome: Launch with proxy
chrome --proxy-server="socks5://localhost:[your_port]"

CLI Usage

ctty provides both command-line operations and an interactive TUI interface:

# Launch interactive TUI mode for browsing and connecting to hosts
ctty

# Connect directly to a specific host (with history tracking)
ctty my-server

# Execute a command on a remote host
ctty my-server uptime

# Execute command with arguments
ctty my-server ls -la /var/log

# Force TTY allocation for interactive commands
ctty -t my-server sudo systemctl restart nginx

# Launch TUI with custom SSH config file
ctty -c /path/to/custom/ssh_config

# Connect directly with custom SSH config file
ctty my-server -c /path/to/custom/ssh_config

# Add a new host using interactive form
ctty add

# Add a new host with pre-filled hostname
ctty add hostname

# Add a new host with custom SSH config file
ctty add hostname -c /path/to/custom/ssh_config

# Edit an existing host configuration
ctty edit my-server

# Edit host with custom SSH config file
ctty edit my-server -c /path/to/custom/ssh_config

# Move a host to another SSH config file (requires Include directives)
ctty move my-server

# Move host with custom SSH config file (requires Include directives)
ctty move my-server -c /path/to/custom/ssh_config

# Search for hosts (interactive filter or keyword/tag query)
ctty search
ctty search prod
ctty search "#web"

# Open SFTP file browser directly for a host
ctty sftp prod-server

# Open Serial device manager directly
ctty serial

# Override interface language (auto, zh, en)
ctty --lang zh
ctty search prod --lang en

# Print machine-readable info (JSON) for scripting
ctty info prod-server
ctty info prod-server --pretty

# With a custom SSH config file
ctty -c /path/to/custom/ssh_config info prod-server

# Pipe to jq
ctty info prod-server | jq -r '.result.target.hostname'
ctty info prod-server | jq -r '.result.target.user'

# Show version information
ctty --version

# Disable automatic update check (useful on air-gapped machines)
ctty --no-update-check

# Show help and available commands
ctty --help

Host Info (JSON)

ctty info <hostname> prints a single JSON object to stdout so you can script against it with jq.

# Extract fields
ctty info prod-server | jq -r '.result.target.hostname'
ctty info prod-server | jq -r '.result.target.port'

# Check not-found (exit code 2)
ctty info does-not-exist | jq -r '.error.code'

Shell Completion

ctty supports shell completion for host names, making it easy to connect to hosts without typing full names:

ctty <TAB>           # Lists all available hosts
ctty pro<TAB>        # Completes to hosts starting with "pro" (e.g., prod-server)

Setup Instructions:

Bash:

# Enable for current session
source <(ctty completion bash)

# Enable permanently (add to ~/.bashrc)
echo 'source <(ctty completion bash)' >> ~/.bashrc

Zsh:

# Enable for current session
source <(ctty completion zsh)

# Enable permanently (add to ~/.zshrc)
echo 'source <(ctty completion zsh)' >> ~/.zshrc

Fish:

# Enable for current session
ctty completion fish | source

# Enable permanently
ctty completion fish > ~/.config/fish/completions/ctty.fish

PowerShell:

# Enable for current session
ctty completion powershell | Out-String | Invoke-Expression

# Enable permanently (add to your PowerShell profile)
Add-Content $PROFILE 'ctty completion powershell | Out-String | Invoke-Expression'

Direct Host Connection

ctty supports direct connection to hosts via the command line, making it easy to integrate into your existing workflow:

# Connect directly to any configured host
ctty production-server
ctty db-staging
ctty web-01

# All direct connections are tracked in your history
# Use the TUI to see your most recently connected hosts

Features of Direct Connection:

Instant connection - No TUI navigation required
History tracking - All connections are recorded with timestamps
Error handling - Clear messages if host doesn't exist or configuration issues
Config file support - Works with custom config files using -c flag

Remote Command Execution

Execute commands on remote hosts without opening an interactive shell:

# Execute a single command
ctty prod-server uptime

# Execute command with arguments
ctty prod-server ls -la /var/log

# Check disk usage
ctty prod-server df -h

# View logs (pipe to local commands)
ctty prod-server 'cat /var/log/nginx/access.log' | grep 404

# Force TTY allocation for interactive commands (sudo, vim, etc.)
ctty -t prod-server sudo systemctl restart nginx

Features:

Exit code propagation - Remote command exit codes are passed through
TTY support - Use -t flag for commands requiring terminal interaction
Pipe-friendly - Output can be piped to local commands for processing
History tracking - Command executions are recorded in connection history

Backup Configuration

ctty automatically creates backups of your SSH configuration files before making any changes to ensure your configurations are safe.

Backup Location:

Unix/Linux/macOS: ~/.config/ctty/backups/ (or $XDG_CONFIG_HOME/ctty/backups/ if set)
Windows: %APPDATA%\ctty\backups\ (fallback: %USERPROFILE%\.config\ctty\backups\)

Key Features:

Automatic backup before any modification
One backup per file (overwrites previous backup)
Stored separately to avoid SSH Include conflicts
Easy manual recovery if needed

Additional Storage:

Connection History: Stored in the same config directory for persistent tracking
Port Forwarding History: Saved configurations for quick reuse of common forwarding setups

Quick Recovery:

# Unix/Linux/macOS
cp ~/.config/ctty/backups/config.backup ~/.ssh/config

# Windows
copy "%APPDATA%\ctty\backups\config.backup" "%USERPROFILE%\.ssh\config"

Configuration File Options

By default, ctty uses the standard SSH configuration file at ~/.ssh/config. You can specify a different configuration file using the -c flag:

# Use custom config file in TUI mode
ctty -c /path/to/custom/ssh_config

# Use custom config file with commands
ctty add hostname -c /path/to/custom/ssh_config
ctty edit hostname -c /path/to/custom/ssh_config
ctty move hostname -c /path/to/custom/ssh_config

Advanced Features

Host Movement Between Config Files

ctty provides a powerful move command to relocate SSH hosts between different configuration files. This feature requires SSH Include directives to be present in your SSH configuration.

# Move a host to another config file (requires Include directives)
ctty move my-server

# Move with custom config file (requires Include directives)
ctty move my-server -c /path/to/custom/ssh_config

⚠️ Important Requirements:

SSH Include directives must be present in your SSH config file (either ~/.ssh/config or the file specified with -c)
The config file must contain Include statements referencing other SSH configuration files
Without Include directives, the move command will display an error message

Features:

Interactive file selector - Choose destination config file from Include directives
Include support - Works seamlessly with SSH Include directives structure
Atomic operations - Safe host movement with automatic backups
Validation - Prevents conflicts and ensures configuration integrity
Error handling - Clear messages when Include files are needed but not found

Use Cases:

Reorganize hosts from main config to specialized include files
Move development hosts to separate environment-specific configs
Consolidate configurations for better organization

Example Setup Required: Your main SSH config file must contain Include directives like:

# ~/.ssh/config
Include ~/.ssh/config.d/*
Include work-servers.conf
Include projects/*.conf

Host personal-server
    HostName personal.example.com
    User myuser

Real-time Connectivity Status

ctty features asynchronous SSH connectivity checking that provides visual indicators of host availability:

Status Indicators:

🟢 Online - SSH connection successful (shows response time)
🟡 Connecting - Currently testing connectivity
🔴 Offline - SSH connection failed or host unreachable
⚫ Unknown - Status not yet determined

Features:

Non-blocking checks - Status updates happen in the background
Response time tracking - See connection latency for online hosts
Automatic refresh - Status indicators update continuously
Error details - Detailed error information for failed connections

Automatic Update Checking

ctty includes built-in version checking that notifies you of available updates:

Features:

Background checking - Version check happens asynchronously, never blocking startup
Release notifications - Clear indicators when updates are available
Pre-release detection - Identifies beta and development versions
GitHub integration - Direct links to release pages
Non-intrusive - Updates don't interrupt your workflow
Configurable - Can be disabled for air-gapped or offline environments

Update notifications appear:

In the main TUI interface as a subtle notification
Only when a newer stable version is available

Disabling update checks:

Via the CLI flag (one-time):

ctty --no-update-check

Via ~/.config/ctty/config.json (persistent):

{
  "check_for_updates": false
}

Port Forwarding History

ctty remembers your port forwarding configurations for easy reuse:

Features:

Automatic saving - Successful forwarding setups are saved automatically
Quick reuse - Previously used configurations appear as suggestions
Per-host history - Forwarding history is tracked per SSH host
All forward types - Supports Local (-L), Remote (-R), and Dynamic (-D) forwarding history
Persistent storage - History survives application restarts

Platform-Specific Notes

Windows:

ctty works with the built-in OpenSSH client (Windows 10/11)
Configuration file location: %USERPROFILE%\.ssh\config
Compatible with WSL SSH configurations
Supports the same SSH options as Unix systems

Unix/Linux/macOS:

Standard SSH configuration file: ~/.ssh/config
Full compatibility with OpenSSH features
Preserves file permissions automatically

Termux (Android):

Detected automatically by the install/unix.sh installer
Installs to $PREFIX/bin (e.g. ~/termux/files/usr/bin), not /usr/local/bin
No sudo — runs with the Termux user permissions
Architecture detection (aarch64 → arm64, armv7* → armv7) works unchanged, so the standard release artifacts install correctly

🏗️ Configuration

ctty works directly with your standard SSH configuration file (~/.ssh/config). It adds special comment tags for enhanced functionality while maintaining full compatibility with standard SSH tools.

SSH Include Support

ctty fully supports SSH Include directives, allowing you to organize your SSH configurations across multiple files. This is particularly useful for managing large numbers of hosts or organizing configurations by environment, project, or team.

Include Examples:

# Main ~/.ssh/config file
Host personal-server
    HostName personal.example.com
    User myuser

# Include work-related configurations
Include work-servers.conf

# Include all configurations from a directory
Include projects/*

# Include with relative paths
Include ~/.ssh/configs/production.conf

Organization Examples:

work-servers.conf:

# Tags: work, production
Host prod-web-01
    HostName 10.0.1.10
    User deploy
    ProxyJump bastion.company.com

# Tags: work, staging  
Host staging-api
    HostName staging-api.company.com
    User developer

projects/client-alpha.conf:

# Tags: client, development
Host client-alpha-dev
    HostName dev.client-alpha.com
    User admin
    Port 2222

Example configuration: Include ~/.ssh/conf.d/*

# Tags: production, web, frontend
Host web-prod-01
    HostName 192.168.1.10
    User deploy
    Port 22
    IdentityFile ~/.ssh/production_key
    Compression yes
    ServerAliveInterval 60

# Tags: development, database
Host db-dev
    HostName dev-db.company.com
    User admin
    Port 2222
    IdentityFile ~/.ssh/dev_key
    StrictHostKeyChecking no
    UserKnownHostsFile /dev/null

# Tags: production, backend
Host backend-prod
    HostName 10.0.1.50
    User app
    Port 22
    ProxyJump bastion.company.com
    ProxyCommand ssh -W %h:%p Jumphost
    IdentityFile ~/.ssh/production_key
    Compression yes
    ServerAliveInterval 300
    BatchMode yes

Supported SSH Options

ctty supports all standard SSH configuration options:

Built-in Fields:

HostName - Server hostname or IP address
User - Username for SSH connection
Port - SSH port number
IdentityFile - Path to private key file
ProxyJump - Jump server for connection tunneling (e.g., user@jumphost:port)
ProxyCommand - Jump command for connection tunneling (e.g, ssh -W %h:%p Jumphost)
Tags - Custom tags (ctty extension); the special tag hidden hides the host from the TUI and ctty search while keeping it connectable via ctty <host>

Additional SSH Options: You can add any valid SSH option using the "SSH Options" field in the interactive forms. Enter them in command-line format (e.g., -o Compression=yes -o ServerAliveInterval=60) and ctty will automatically convert them to the proper SSH config format.

Common SSH Options:

Compression - Enable/disable compression (yes/no)
ServerAliveInterval - Interval in seconds for keepalive messages
ServerAliveCountMax - Maximum number of keepalive messages
StrictHostKeyChecking - Host key verification (yes/no/ask)
UserKnownHostsFile - Path to known hosts file
BatchMode - Disable interactive prompts (yes/no)
ConnectTimeout - Connection timeout in seconds
ControlMaster - Connection multiplexing (yes/no/auto)
ControlPath - Path for control socket
ControlPersist - Keep connection alive duration
ForwardAgent - Forward SSH agent (yes/no)
LocalForward - Local port forwarding (e.g., 8080:localhost:80)
RemoteForward - Remote port forwarding
DynamicForward - SOCKS proxy port forwarding

Example usage in forms:

SSH Options: -o Compression=yes -o ServerAliveInterval=60 -o StrictHostKeyChecking=no

This will be automatically converted to:

    Compression yes
    ServerAliveInterval 60
    StrictHostKeyChecking no

Application Configuration

ctty supports a configuration file to customize its behavior, including language, key bindings, update checking, and custom tag colors. You can also configure these interactively in the TUI by pressing S.

Configuration File Location:

Linux/macOS: ~/.config/ctty/config.json (respects $XDG_CONFIG_HOME)
Windows: %APPDATA%\ctty\config.json

Example Configuration:

{
  "language": "zh_CN",
  "check_for_updates": true,
  "key_bindings": {
    "quit_keys": ["q", "ctrl+c"],
    "disable_esc_quit": false
  },
  "tag_colors": {
    "prod": "#FF0055",
    "staging": "#FFAA00",
    "k8s": "#326CE5",
    "mine": "#00DDFF"
  }
}

Available Options:

language: Interface language: "auto" (follow OS locale), "zh_CN" (Simplified Chinese), or "en" (English). Default: "auto".
check_for_updates: Boolean to enable or disable the automatic update check at startup. Default: true. Set to false on air-gapped or offline machines to avoid connection delays.
key_bindings.quit_keys: Array of keys that will quit the application. Default: ["q", "ctrl+c"]
key_bindings.disable_esc_quit: Boolean flag to disable ESC key from quitting the application. Default: false. Useful for Vim users.
tag_colors: Map of custom hex color codes for specific tags (e.g. {"prod": "#FF0055"}). Overrides built-in semantic colors and hash palette.

For Vim Users: If you frequently press ESC accidentally causing the application to quit, set disable_esc_quit to true. This will disable ESC as a quit key while preserving all other functionality.

For Air-gapped Machines: If ctty is slow to start due to DNS timeouts when reaching GitHub, set check_for_updates to false. You can also use the --no-update-check CLI flag for a one-time override without editing the config file.

Default Configuration: If no configuration file exists, ctty will automatically create one with default settings that maintain backward compatibility.

🛠️ Development

Prerequisites

Go 1.23+
Git

Build from Source

# Clone the repository
git clone https://github.com/zsuroy/ctty.git
cd ctty

# Build the binary
go build -o ctty .

# Run
./ctty

Project Structure

ctty/
├── main.go             # Application entry point
├── cmd/                # CLI commands (Cobra)
│   ├── root.go         # Root command, CLI flags, and interactive mode
│   ├── add.go          # Add host command
│   ├── edit.go         # Edit host command
│   ├── move.go         # Move host command
│   ├── search.go       # Search command
│   ├── serial.go       # Serial device manager command
│   ├── sftp.go         # SFTP file browser command
│   ├── info.go         # Machine-readable JSON host info
│   └── completion.go   # Shell tab completion script generator
├── internal/
│   ├── config/         # SSH & App configuration management
│   │   ├── ssh.go      # SSH config parsing, manipulation, and include support
│   │   └── appconfig.go# App settings (~/.config/ctty/config.json)
│   ├── connectivity/   # SSH connectivity checking
│   │   └── ping.go     # Asynchronous SSH ping functionality
│   ├── history/        # Connection history tracking
│   │   └── history.go  # History management and last login tracking
│   ├── i18n/           # Internationalization & locale auto-detection
│   │   ├── i18n.go     # Core translation lookup & state
│   │   ├── locales.go  # Translation dictionaries (English & Chinese)
│   │   ├── detect_darwin.go  # macOS AppleLocale/AppleLanguages detector
│   │   ├── detect_windows.go # Windows Win32 API GetUserDefaultLocaleName
│   │   └── detect_other.go   # Linux POSIX locale & Android getprop
│   ├── serialconfig/   # Serial device configuration and connection
│   │   ├── serial.go   # Device config storage (~/.config/ctty/serial.json)
│   │   ├── ports.go    # Port enumeration and helpers
│   │   ├── connect.go  # Serial connection bridge (ExecCommand)
│   │   ├── raw_unix.go # POSIX raw terminal mode
│   │   └── raw_windows.go # Windows stub
│   ├── sftpconfig/     # SFTP client engine & file transfer
│   │   └── client.go   # SFTP session, upload, download, and listing
│   ├── version/        # Version checking and updates
│   │   ├── version.go  # GitHub release checking and version comparison
│   │   └── version_test.go # Version parsing and comparison tests
│   ├── ui/             # Terminal UI components (Bubble Tea)
│   │   ├── tui.go      # Main TUI interface and program setup
│   │   ├── model.go    # Core TUI model and state
│   │   ├── update.go   # Message handling and state updates
│   │   ├── view.go     # UI rendering and layout
│   │   ├── table.go    # Host list table component with status indicators & tag colors
│   │   ├── tag_color.go# Semantic & hash-based tag color mapping
│   │   ├── add_form.go # Add host form interface
│   │   ├── edit_form.go# Edit host form interface
│   │   ├── move_form.go# Move host form interface
│   │   ├── info_form.go# Host details modal
│   │   ├── help_form.go# Keyboard shortcut help modal
│   │   ├── settings_form.go # Settings & preferences modal
│   │   ├── port_forward_form.go # Port forwarding setup with history
│   │   ├── styles.go   # Lip Gloss styling definitions
│   │   ├── sort.go     # Sorting and filtering logic
│   │   ├── serial_form.go         # Serial device list UI
│   │   ├── serial_add_form.go     # Add serial device form
│   │   ├── serial_connect_form.go # Edit serial parameters form
│   │   └── sftp_view.go           # SFTP remote & local browser UI
│   └── validation/     # Input validation
│       └── ssh.go      # SSH config validation
├── images/             # Documentation assets
│   ├── logo.png        # Project logo
│   └── ctty.gif        # Demo animation
├── install/            # Installation scripts
│   ├── unix.sh         # Unix/Linux/macOS installer
│   └── README.md       # Installation guide
├── .github/            # GitHub configuration
│   ├── copilot-instructions.md # Development guidelines
│   └── workflows/      # CI/CD pipelines
│       └── build.yml   # Multi-platform builds
├── go.mod              # Go module definition
├── go.sum              # Go module checksums
├── LICENSE             # MIT license
└── README.md           # Project documentation

Dependencies

Cobra - CLI framework
Bubble Tea - TUI framework
Bubbles - TUI components
Lipgloss - Styling
Serial - Cross-platform serial port communication

📦 Releases

Automated releases are built for multiple platforms:

Platform	Architecture	Download
Linux	AMD64	ctty-linux-amd64.tar.gz
Linux	ARM64	ctty-linux-arm64.tar.gz
macOS	Intel	ctty-darwin-amd64.tar.gz
macOS	Apple Silicon	ctty-darwin-arm64.tar.gz
Windows	AMD64	ctty-windows-amd64.zip
Windows	ARM64	ctty-windows-arm64.zip

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Development Workflow

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📝 License

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

🙏 Acknowledgments

This project is a fork of sshm by @Gu1llaum-3. We are grateful for the original work that made ctty possible.

Charm for the amazing TUI libraries
Cobra for the excellent CLI framework
@Gu1llaum-3 for creating sshm, the ssh foundation of ctty
@yimeng for contributing SSH Include directive support
@ldreux for contributing multi-word search functionality
@qingfengzxr for contributing custom key bindings support
Linux.do for opensource support
The Go community for building such fantastic tools

Made with ❤️ by zsuroy

⭐ Star this repo if you found it useful! ⭐

Name		Name	Last commit message	Last commit date
Latest commit History 18 Commits
.github		.github
cmd		cmd
images		images
install		install
internal		internal
.gitignore		.gitignore
.goreleaser.yaml		.goreleaser.yaml
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
README_CN.md		README_CN.md
go.mod		go.mod
go.sum		go.sum
main.go		main.go

Folders and files

Latest commit

History

Repository files navigation

🚀 ctty - Connection Manager

✨ Features

🚀 Core Capabilities

🛠️ Technical Features

🚀 Quick Start

Installation

📖 Usage

Interactive Mode

Serial Connections

SFTP File Transfer

Port Forwarding

CLI Usage

Host Info (JSON)

Shell Completion

Direct Host Connection

Remote Command Execution

Backup Configuration

Configuration File Options

Advanced Features

Host Movement Between Config Files

Real-time Connectivity Status

Automatic Update Checking

Port Forwarding History

Platform-Specific Notes

🏗️ Configuration

SSH Include Support

Supported SSH Options

Application Configuration

🛠️ Development

Prerequisites

Build from Source

Project Structure

Dependencies

📦 Releases

🤝 Contributing

Development Workflow

📝 License

🙏 Acknowledgments

About

Topics

Resources

Stars

Watchers

Forks

Releases

Used by

Contributors

Languages