Client CLI Reference - Undying Terminal

Synopsis

undying-terminal.exe [OPTIONS]

Description

The Undying Terminal client is the user-facing component that connects to persistent terminal sessions. It handles interactive I/O, automatic reconnection, port forwarding, and SSH bootstrap.

Connection Modes

Direct Connection

Connect to an existing terminal session:

undying-terminal.exe --connect <HOST> <PORT> <CLIENT_ID> [OPTIONS]

SSH Bootstrap

Start a remote terminal via SSH, then connect directly:

undying-terminal.exe --ssh <HOST> [OPTIONS]

Options Reference

Connection Options

`--connect <HOST> <PORT> <ID>`

Connect to existing terminal session. Arguments:

HOST: Server hostname or IP address
PORT: Server port number (typically 2022)
ID: Client ID (from terminal output)

Example:

--connect 192.168.1.100 2022 abc123def456

`--key <PASSKEY>`

Authentication passkey for the session. Required: Yes (with --connect)
Format: Hexadecimal string
Example:

--key 1234567890abcdef

`--ssh <HOST>`

Bootstrap mode: SSH to host, start remote terminal, connect. Example:

--ssh user@remote-server.com

Behavior:

Spawns ssh to connect to host
Executes undying-terminal-terminal remotely
Extracts client ID and passkey from output
Switches to direct TCP connection
Maintains persistent session

SSH login username (used with --ssh). Example:

--ssh remote-server.com -l admin

SSH Config Options

`--ssh-config <PATH>`

Specify a custom SSH config file path instead of the default (~/.ssh/config). Example:

--ssh myserver --ssh-config C:\custom\ssh_config

Behavior:

Loads SSH config directives for the specified host
Supports: HostName, User, Port, IdentityFile, ProxyJump, LocalForward, ForwardAgent

`--no-ssh-config`

Disable SSH config file parsing entirely. Example:

--ssh user@192.168.1.100 --no-ssh-config

Use case: When you want to ignore SSH config settings and use only CLI arguments.

`-A, --ssh-agent`

Enable SSH agent forwarding (passes local SSH keys to remote session). Example:

--ssh myserver -A
--ssh myserver --ssh-agent

Security note: Only enable agent forwarding to trusted hosts.

`--no-ssh-agent`

Explicitly disable SSH agent forwarding (overrides ForwardAgent in SSH config). Example:

--ssh myserver --no-ssh-agent

`--jumphost <HOST>, --jport <PORT>`

Connect through intermediate jump server. Example:

--connect jump-server.com 2022 jump-id --key jump-key `
  --jumphost destination-server.com --jport 2022

Flow:

Client → Jump Server → Destination Server → Destination Terminal

Command Execution

`-c, --command <COMMAND>`

Execute a single command and exit. Format: Command string with newline
Example:

# Note: `r`n for cmd.exe newline
--command "dir`r`n"
--command "echo Hello`r`n"

--command @"
cd C:\projects
npm run build`r`n
"@

Behavior:

Sends command to session
Waits for output
Exits on idle timeout
Does NOT enter interactive mode

`--noexit`

Keep client running after command completes (interactive mode). Use with: --connect (default for SSH mode)
Example:

# One-shot command (exits when idle)
--connect ... -c "dir`r`n"

# Interactive session (stays open)
--connect ... --noexit

Port Forwarding

`-t, --tunnel <SPEC>`

Forward tunnel (local → remote). Syntax:

LOCAL:REMOTE
LOCAL:HOST:REMOTE
BIND:LOCAL:HOST:REMOTE
START-END:START-END

Examples:

-t 8080:9090
# localhost:8080 → remote:9090

-t 8080:database:5432
# localhost:8080 → database:5432

-t 0.0.0.0:8080:api:3000
# 0.0.0.0:8080 → api:3000 (accessible externally)

-t 8080-8085:9090-9095
# 6 tunnels: 8080→9090, 8081→9091, ..., 8085→9095

Multiple Tunnels:

-t 5432:db:5432 -t 6379:redis:6379 -t 3000:api:3000

`-r, --reversetunnel <SPEC>`

Reverse tunnel (remote → local). Syntax:

REMOTE:LOCAL
REMOTE:HOST:LOCAL

Examples:

-r 3000:8000
# Server listens on 3000 → client's localhost:8000

-r 8080:localhost:3000
# Server:8080 → client's localhost:3000

-r 8080:3000 -r 5432:5432 -r 6379:6379

Environment Variables

`--environmentvariable <NAME>=<VALUE>`

Send environment variable to remote session. Example:

--environmentvariable PATH=/usr/local/bin:$PATH
--environmentvariable NODE_ENV=production

Multiple Variables:

--environmentvariable FOO=bar `
--environmentvariable BAZ=qux

Usage Examples

Basic Connection

# Standard interactive session
./undying-terminal.exe `
  --connect 192.168.1.100 2022 abc123def456 `
  --key 1234567890abcdef `
  --noexit

# Execute command and exit
./undying-terminal.exe `
  --connect 192.168.1.100 2022 abc123def456 `
  --key 1234567890abcdef `
  -c "dir C:\`r`n"

SSH Bootstrap

# SSH with username@host
./undying-terminal.exe --ssh user@remote-server.com

# SSH with separate login flag
./undying-terminal.exe --ssh remote-server.com -l admin

# SSH on non-standard port (use standard SSH syntax)
./undying-terminal.exe --ssh user@remote-server.com:2222

# Uses host alias from ~/.ssh/config
./undying-terminal.exe --ssh myserver

# Custom SSH config file
./undying-terminal.exe --ssh myserver --ssh-config C:\custom\ssh_config

# Disable SSH config parsing
./undying-terminal.exe --ssh user@192.168.1.100 --no-ssh-config

# Enable SSH agent forwarding
./undying-terminal.exe --ssh myserver -A

# Disable agent forwarding (overrides config)
./undying-terminal.exe --ssh myserver --no-ssh-agent

Port Forwarding

# Forward remote database to local port
./undying-terminal.exe `
  --connect db-server.com 2022 <ID> --key <KEY> `
  -t 5432:postgres-internal:5432 `
  --noexit

# Forward multiple dev services
./undying-terminal.exe `
  --connect dev-server.com 2022 <ID> --key <KEY> `
  -t 3000:api:3000 `
  -t 8080:frontend:8080 `
  -t 6379:redis:6379 `
  --noexit

# Expose local web server to remote network
./undying-terminal.exe `
  --connect remote-server.com 2022 <ID> --key <KEY> `
  -r 8080:localhost:3000 `
  --noexit

Jumphost

# Connect through jump server to final destination
./undying-terminal.exe `
  --connect jump.company.com 2022 jump-client-id --key jump-key `
  --jumphost prod.internal.company.com --jport 2022 `
  --noexit

Combined Example

# Full-featured connection:
# - Connect to remote server
# - Forward database and Redis
# - Reverse tunnel for local dev server
# - Set environment variable
./undying-terminal.exe `
  --connect prod-server.com 2022 abc123def456 `
  --key 1234567890abcdef `
  -t 5432:db.internal:5432 `
  -t 6379:redis.internal:6379 `
  -r 8080:localhost:3000 `
  --environmentvariable NODE_ENV=production `
  --noexit

Exit Codes

Code	Meaning
`0`	Success (normal exit)
`1`	Connection failed
`2`	Invalid arguments
`3`	Authentication failed
`4`	Network error
`5`	Protocol error

Environment Variables

These environment variables affect client behavior:

`UT_DEBUG_HANDSHAKE`

Enable packet-level debugging.

$env:UT_DEBUG_HANDSHAKE = 1
./undying-terminal.exe --connect ...

Output: Prints packet types sent/received

`UT_PIPE_NAME`

Override named pipe path (when connecting to non-default server).

$env:UT_PIPE_NAME = "\\\\.\\pipe\\undying-terminal-custom"
./undying-terminal-terminal.exe

Common Patterns

Connection Script

Save frequently-used connections:

# connect-dev.ps1
$clientId = "abc123def456"
$passkey = "1234567890abcdef"

./undying-terminal.exe `
  --connect dev-server.com 2022 $clientId `
  --key $passkey `
  -t 5432:db:5432 `
  --noexit

Usage:

.\connect-dev.ps1

Health Check Script

Check if session is responsive:

# health-check.ps1
$output = ./undying-terminal.exe `
  --connect 127.0.0.1 2022 $clientId `
  --key $passkey `
  -c "echo OK`r`n"

if ($output -match "OK") {
  Write-Output "Session healthy"
  exit 0
} else {
  Write-Output "Session unresponsive"
  exit 1
}

Automated Deployment

# deploy.ps1
./undying-terminal.exe `
  --connect prod-server.com 2022 $clientId `
  --key $passkey `
  -c @"
cd C:\apps\myapp
git pull origin main
npm install
npm run build
Restart-Service MyAppService`r`n
"@

Comparison with Other Terminals

vs. SSH

Feature	Undying Terminal	SSH
Session Persistence	Yes Automatic	No Drops on disconnect
Recovery	Yes Packet-level	No None
Reconnection	Yes Automatic	No Manual
Port Forwarding	Yes Persistent tunnels	Yes Drops on disconnect
Windows Native	Yes Yes	Warning: Requires WSL/OpenSSH

vs. tmux/screen

Feature	Undying Terminal	tmux/screen
Session Multiplexing	No Single session per terminal	Yes Multiple panes
Network Resilience	Yes Built-in recovery	Yes Via SSH wrapper
Windows Support	Yes Native	No Requires WSL
Port Forwarding	Yes Built-in	No Requires SSH

vs. Eternal Terminal (ET)

Feature	Undying Terminal	ET
Protocol	ET-compatible	ET protocol
Platform	Windows	Linux/macOS
Architecture	Client-Server-Terminal	Client-Server
ConPTY	Yes Yes	No No

Debugging

Enable verbose output:

# Debug handshake
$env:UT_DEBUG_HANDSHAKE = 1

# Run client
./undying-terminal.exe --connect ... --noexit

Check connection:

# Verify server is reachable
Test-NetConnection -ComputerName prod-server.com -Port 2022

# Check client process
tasklist | findstr undying-terminal.exe

Next Steps

Server CLI Reference

Server command-line options

Terminal CLI Reference

Terminal command-line options

Configuration Guide

Configure server behavior

Port Forwarding Guide

Detailed tunnel examples

​Synopsis

​Description

​Connection Modes

​Direct Connection

​SSH Bootstrap

​Options Reference

​Connection Options

​--connect <HOST> <PORT> <ID>

​--key <PASSKEY>

​--ssh <HOST>

​-l, --login <USERNAME>

​SSH Config Options

​--ssh-config <PATH>

​--no-ssh-config

​-A, --ssh-agent

​--no-ssh-agent

​--jumphost <HOST>, --jport <PORT>

​Command Execution

​-c, --command <COMMAND>

​--noexit

​Port Forwarding

​-t, --tunnel <SPEC>

​-r, --reversetunnel <SPEC>

​Environment Variables

​--environmentvariable <NAME>=<VALUE>

​Usage Examples

​Basic Connection

​SSH Bootstrap

​Port Forwarding

​Jumphost

​Combined Example

​Exit Codes

​Environment Variables

​UT_DEBUG_HANDSHAKE

​UT_PIPE_NAME

​Common Patterns

​Connection Script

​Health Check Script

​Automated Deployment

​Comparison with Other Terminals

​vs. SSH

​vs. tmux/screen

​vs. Eternal Terminal (ET)

​Debugging

​Next Steps

Server CLI Reference

Terminal CLI Reference

Configuration Guide

Port Forwarding Guide

Synopsis

Description

Connection Modes

Direct Connection

SSH Bootstrap

Options Reference

Connection Options

`--connect <HOST> <PORT> <ID>`

`--key <PASSKEY>`

`--ssh <HOST>`

`-l, --login <USERNAME>`

SSH Config Options

`--ssh-config <PATH>`

`--no-ssh-config`

`-A, --ssh-agent`

`--no-ssh-agent`

`--jumphost <HOST>, --jport <PORT>`

Command Execution

`-c, --command <COMMAND>`

`--noexit`

Port Forwarding

`-t, --tunnel <SPEC>`

`-r, --reversetunnel <SPEC>`

Environment Variables

`--environmentvariable <NAME>=<VALUE>`

Usage Examples

Basic Connection

SSH Bootstrap

Port Forwarding

Jumphost

Combined Example

Exit Codes

Environment Variables

`UT_DEBUG_HANDSHAKE`

`UT_PIPE_NAME`

Common Patterns

Connection Script

Health Check Script

Automated Deployment

Comparison with Other Terminals

vs. SSH

vs. tmux/screen

vs. Eternal Terminal (ET)

Debugging

Next Steps