remote | Ralph TUI

Synopsis

Bash

ralph-tui remote <subcommand> [options]

The remote command manages connections to ralph-tui instances running on other machines. This enables monitoring and controlling multiple instances from a single TUI.

Subcommands

add

Add a new remote server configuration.

Bash

ralph-tui remote add <alias> <host:port> --token <token>

Arguments:

<alias> - A unique name for this remote (e.g., prod, staging, dev)
<host:port> - Server hostname and port (port defaults to 7890 if omitted)
--token <token> - Authentication token from the remote server

Examples:

Bash

# Add a remote server with explicit port
ralph-tui remote add prod server.example.com:7890 --token OGQwNTcxMjM0NTY3...
 
# Add with default port (7890)
ralph-tui remote add staging staging.local --token YWJjZGVmMDEyMzQ1...
 
# Add localhost for testing
ralph-tui remote add local localhost --token dGVzdDEyMzQ1Njc4...

Alias naming rules:

Must start with a letter
Can contain letters, numbers, dashes, and underscores
Examples: prod, staging-1, server_2, MyServer

list / ls

List all configured remotes with their connection status.

Bash

ralph-tui remote list
ralph-tui remote ls  # Alias

Output includes:

Connection status (✓ connected, ✗ disconnected)
Server URL
Latency (when connected)
Token preview (first 8 characters)
Last successful connection time

Example output:

Configured Remotes
══════════════════════════════════════════════════════════════

  ✓ prod
    URL:    ws://server.example.com:7890
    Status: connected (45ms)
    Token:  OGQwNTcx...
    Last:   1/19/2026, 3:30:00 PM

  ✗ staging
    URL:    ws://staging.local:7890
    Status: Connection timed out (5s)
    Token:  YWJjZGVm...

──────────────────────────────────────────────────────────────
Total: 2 remote(s)

remove / rm

Remove a remote server configuration.

Bash

ralph-tui remote remove <alias>
ralph-tui remote rm <alias>  # Alias

Example:

Bash

ralph-tui remote remove staging
# Output: ✓ Remote 'staging' removed

test

Test connectivity to a remote server.

Bash

ralph-tui remote test <alias>

This command:

Connects to the remote server
Authenticates with the stored token
Reports connection success/failure and latency
Updates the "last connected" timestamp on success

Example:

Bash

ralph-tui remote test prod
# Output:
# Testing connection to 'prod'...
#   URL: ws://server.example.com:7890
#
# ✓ Connection successful
#   Latency: 42ms

push-config

Push your local configuration to remote instances.

Bash

ralph-tui remote push-config <alias> [options]
ralph-tui remote push-config --all [options]

Options:

Option	Description
`--scope global\|project`	Which config to push (default: auto-detect)
`--preview`	Show diff without applying changes
`--force`	Overwrite existing config without confirmation
`--all`	Push to all configured remotes

Examples:

Bash

# Push config to a specific remote
ralph-tui remote push-config prod
 
# Preview what would be pushed
ralph-tui remote push-config prod --preview
 
# Push to all remotes with force overwrite
ralph-tui remote push-config --all --force
 
# Push only global config
ralph-tui remote push-config prod --scope global
 
# Push only project config
ralph-tui remote push-config prod --scope project

INFO

The push-config command automatically triggers migration on the remote, which installs skills and templates. Changes take effect on the next ralph-tui run.

How it works:

Detection: Checks what config exists locally and on the remote
Scope selection: Auto-detects or uses --scope flag
Backup: Creates timestamped backup before overwriting (e.g., config.toml.backup.2026-01-19T12-30-00-000Z)
Transfer: Pushes the TOML config content over WebSocket
Validation: Server validates TOML syntax before writing
Migration: Triggers auto-migration to install skills/templates

Scope selection logic (when --scope not specified):

If you have project config and remote doesn't → push project
If you have global config → push global
If you only have project config → push project

Configuration Storage

Remote configurations are stored in TOML format:

File: ~/.config/ralph-tui/remotes.toml

TOML

version = 1
 
[remotes.prod]
host = "server.example.com"
port = 7890
token = "OGQwNTcxMjM0NTY3ODkwYWJjZGVmMDEyMzQ1Njc4OQ"
addedAt = "2026-01-19T00:00:00.000Z"
lastConnected = "2026-01-19T15:30:00.000Z"
 
[remotes.staging]
host = "staging.local"
port = 7890
token = "YWJjZGVmMDEyMzQ1Njc4OTBhYmNkZWYwMTIzNDU2Nzg5"
addedAt = "2026-01-18T10:00:00.000Z"

Security

INFO

Tokens are stored in plain text in remotes.toml. Ensure appropriate file permissions and do not commit this file to version control.

Token handling:

Tokens are shown in preview form (first 8 characters + ...) in list output
Full tokens are only shown when generated on the server
All remote actions are logged to ~/.config/ralph-tui/audit.log

run --listen - Run with remote listener enabled

Troubleshooting

Connection Failed

✗ Connection failed
  Error: Connection timed out (5s)

Possible causes:

Server is not running (ralph-tui run --listen)
Firewall blocking port 7890
Incorrect hostname or port

Solution: Verify the server is running and the port is accessible.

Authentication Failed

✗ Connection failed
  Error: Invalid token

Possible causes:

Token was rotated on the server
Token was copied incorrectly

Solution: Get a fresh token from the server with ralph-tui run --listen --rotate-token and update the remote configuration.

Config Push Failed

✗ Push failed: Config already exists at /path/to/config.toml. Use overwrite=true to replace.

Solution: Use --force flag to overwrite existing config, or --preview to see what would change first.

Invalid TOML

✗ Push failed: Invalid TOML: Expected "=" at line 5

Solution: Fix the syntax error in your local config file before pushing.