> ## Documentation Index > Fetch the complete documentation index at: https://undyingterminal.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Client CLI Reference > Complete command-line interface reference for undying-terminal client ## Synopsis ```bash theme={null} 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: ```powershell theme={null} undying-terminal.exe --connect [OPTIONS] ``` ### SSH Bootstrap Start a remote terminal via SSH, then connect directly: ```powershell theme={null} undying-terminal.exe --ssh [OPTIONS] ``` ## Options Reference ### Connection Options #### `--connect ` 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**: ```powershell theme={null} --connect 192.168.1.100 2022 abc123def456 ``` #### `--key ` Authentication passkey for the session. **Required**: Yes (with `--connect`)\ **Format**: Hexadecimal string\ **Example**: ```powershell theme={null} --key 1234567890abcdef ``` #### `--ssh ` Bootstrap mode: SSH to host, start remote terminal, connect. **Example**: ```powershell theme={null} --ssh user@remote-server.com ``` **Behavior**: 1. Spawns `ssh` to connect to host 2. Executes `undying-terminal-terminal` remotely 3. Extracts client ID and passkey from output 4. Switches to direct TCP connection 5. Maintains persistent session #### `-l, --login ` SSH login username (used with `--ssh`). **Example**: ```powershell theme={null} --ssh remote-server.com -l admin ``` ### SSH Config Options #### `--ssh-config ` Specify a custom SSH config file path instead of the default (`~/.ssh/config`). **Example**: ```powershell theme={null} --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**: ```powershell theme={null} --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**: ```powershell theme={null} --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**: ```powershell theme={null} --ssh myserver --no-ssh-agent ``` #### `--jumphost , --jport ` Connect through intermediate jump server. **Example**: ```powershell theme={null} --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 ` Execute a single command and exit. **Format**: Command string with newline\ **Example**: ```powershell PowerShell theme={null} # Note: `r`n for cmd.exe newline --command "dir`r`n" --command "echo Hello`r`n" ``` ```powershell Multi-line theme={null} --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**: ```powershell theme={null} # One-shot command (exits when idle) --connect ... -c "dir`r`n" # Interactive session (stays open) --connect ... --noexit ``` ### Port Forwarding #### `-t, --tunnel ` Forward tunnel (local → remote). **Syntax**: ``` LOCAL:REMOTE LOCAL:HOST:REMOTE BIND:LOCAL:HOST:REMOTE START-END:START-END ``` **Examples**: ```powershell Simple theme={null} -t 8080:9090 # localhost:8080 → remote:9090 ``` ```powershell Explicit Host theme={null} -t 8080:database:5432 # localhost:8080 → database:5432 ``` ```powershell Custom Bind theme={null} -t 0.0.0.0:8080:api:3000 # 0.0.0.0:8080 → api:3000 (accessible externally) ``` ```powershell Range theme={null} -t 8080-8085:9090-9095 # 6 tunnels: 8080→9090, 8081→9091, ..., 8085→9095 ``` **Multiple Tunnels**: ```powershell theme={null} -t 5432:db:5432 -t 6379:redis:6379 -t 3000:api:3000 ``` #### `-r, --reversetunnel ` Reverse tunnel (remote → local). **Syntax**: ``` REMOTE:LOCAL REMOTE:HOST:LOCAL ``` **Examples**: ```powershell Simple theme={null} -r 3000:8000 # Server listens on 3000 → client's localhost:8000 ``` ```powershell Explicit Destination theme={null} -r 8080:localhost:3000 # Server:8080 → client's localhost:3000 ``` ```powershell Multiple theme={null} -r 8080:3000 -r 5432:5432 -r 6379:6379 ``` ### Environment Variables #### `--environmentvariable =` Send environment variable to remote session. **Example**: ```powershell theme={null} --environmentvariable PATH=/usr/local/bin:$PATH --environmentvariable NODE_ENV=production ``` **Multiple Variables**: ```powershell theme={null} --environmentvariable FOO=bar ` --environmentvariable BAZ=qux ``` ## Usage Examples ### Basic Connection ```powershell Interactive theme={null} # Standard interactive session ./undying-terminal.exe ` --connect 192.168.1.100 2022 abc123def456 ` --key 1234567890abcdef ` --noexit ``` ```powershell One-Shot Command theme={null} # Execute command and exit ./undying-terminal.exe ` --connect 192.168.1.100 2022 abc123def456 ` --key 1234567890abcdef ` -c "dir C:\`r`n" ``` ### SSH Bootstrap ```powershell Simple theme={null} # SSH with username@host ./undying-terminal.exe --ssh user@remote-server.com ``` ```powershell With Login Flag theme={null} # SSH with separate login flag ./undying-terminal.exe --ssh remote-server.com -l admin ``` ```powershell With Port theme={null} # SSH on non-standard port (use standard SSH syntax) ./undying-terminal.exe --ssh user@remote-server.com:2222 ``` ```powershell With SSH Config theme={null} # 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 ``` ```powershell With Agent Forwarding theme={null} # 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 ```powershell Database Access theme={null} # Forward remote database to local port ./undying-terminal.exe ` --connect db-server.com 2022 --key ` -t 5432:postgres-internal:5432 ` --noexit ``` ```powershell Web Development theme={null} # Forward multiple dev services ./undying-terminal.exe ` --connect dev-server.com 2022 --key ` -t 3000:api:3000 ` -t 8080:frontend:8080 ` -t 6379:redis:6379 ` --noexit ``` ```powershell Reverse Tunnel (Expose Local) theme={null} # Expose local web server to remote network ./undying-terminal.exe ` --connect remote-server.com 2022 --key ` -r 8080:localhost:3000 ` --noexit ``` ### Jumphost ```powershell theme={null} # 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 ```powershell theme={null} # 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. ```powershell theme={null} $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). ```powershell theme={null} $env:UT_PIPE_NAME = "\\\\.\\pipe\\undying-terminal-custom" ./undying-terminal-terminal.exe ``` ## Common Patterns ### Connection Script Save frequently-used connections: ```powershell theme={null} # connect-dev.ps1 $clientId = "abc123def456" $passkey = "1234567890abcdef" ./undying-terminal.exe ` --connect dev-server.com 2022 $clientId ` --key $passkey ` -t 5432:db:5432 ` --noexit ``` Usage: ```powershell theme={null} .\connect-dev.ps1 ``` ### Health Check Script Check if session is responsive: ```powershell theme={null} # 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 ```powershell theme={null} # 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: ```powershell theme={null} # Debug handshake $env:UT_DEBUG_HANDSHAKE = 1 # Run client ./undying-terminal.exe --connect ... --noexit ``` Check connection: ```powershell theme={null} # Verify server is reachable Test-NetConnection -ComputerName prod-server.com -Port 2022 # Check client process tasklist | findstr undying-terminal.exe ``` ## Next Steps Server command-line options Terminal command-line options Configure server behavior Detailed tunnel examples