Remote SSH/SFTP Browsing

Complete guide to RTFM’s remote directory browsing capabilities.

Overview

RTFM lets you browse and manage files on remote servers via SSH/SFTP as seamlessly as local directories. No need to open separate terminal windows or use command-line scp/sftp.

Quick Start

Press Ctrl-e to enter remote mode
Enter connection: user@server.com:/path/to/directory
Navigate with normal keys
Press D to download, u to upload
Press Ctrl-e to return to local mode

Connection Formats

Basic SSH Connection

user@hostname:/path/to/directory

With Custom SSH Key

-i ~/.ssh/custom-key user@hostname:/path

Or:

user@hostname:/path -i ~/.ssh/custom-key

SSH URI Format

ssh://user@hostname/path/to/directory

IP Address

user@192.168.1.100:/home/user

With Comments (for organization)

user@production.com:/var/www # Production server
admin@dev.local:/home # Development
backup@backup.server:/data # Backup server

Comments help identify connections in history (Ctrl-e then select from list).

Remote Mode Operations

Navigation

Key	Action
`↑` `↓`	Move through file list
`→` `ENTER`	Show file info
`←` `h`	Parent directory
`HOME` `END`	First / last item

File Operations

Key	Action
`d`	Download selected file
`u`	Upload tagged files
`s`	Open SSH shell in current directory

Note: Copy, move, delete operations are disabled in remote mode for safety.

Information Display

Press → or ENTER on a file to see:

File size
Permissions
Owner/group
Modified date
Full path

Downloading Files

Download Single File

Navigate to file
Press D
File downloads to your current local directory

Download Multiple Files

Tag files with t
Press D
All tagged files download

Download location: Current local directory (where you were before entering remote mode)

Uploading Files

Upload Tagged Files

In local mode, tag files with t
Press Ctrl-e to enter remote mode
Navigate to destination directory
Press u to upload all tagged files

Upload Workflow Example

# Local mode
r                           # Launch RTFM
# Navigate to files to upload
t t t                      # Tag 3 files
Ctrl-e                     # Enter remote mode
user@server:/uploads      # Connect
# Navigate to destination
u                          # Upload tagged files

SSH Shell Integration

Opening SSH Shell

While in remote mode:

Navigate to desired directory
Press s
Interactive SSH shell opens in that directory

In SSH Shell

Full interactive shell session
All normal shell commands work
Exit shell with exit or Ctrl-d
Returns to RTFM automatically

Use case: Quick edits, running scripts, checking logs

Connection Caching

RTFM caches remote directory listings for 60 seconds to improve performance.

Force refresh:

Press r to refresh current directory
Change directories and return

SSH Configuration

SSH Key Setup

For passwordless access, set up SSH keys:

# Generate key (if you don't have one)
ssh-keygen -t ed25519

# Copy to server
ssh-copy-id user@server.com

Persistent Connections

Speed up repeated connections in ~/.ssh/config:

Host production
    HostName production.example.com
    User deployuser
    IdentityFile ~/.ssh/production_key
    ControlMaster auto
    ControlPath ~/.ssh/control-%r@%h:%p
    ControlPersist 10m

Host *.local
    User admin
    ControlMaster auto
    ControlPersist 5m

Then in RTFM: Ctrl-e → production:/var/www

Connection History

RTFM saves recent SSH connections in @sshhistory.

Prepopulate connections:

# ~/.rtfm/conf
@sshhistory = [
  "user@production.com:/var/www # Production",
  "admin@staging.com:/var/www # Staging",
  "user@backup.server:/backups # Backups"
]

Access history:

Press Ctrl-e
See list of recent connections
Select connection or enter new one

Use Cases

Remote Log Monitoring

Ctrl-e → server:/var/log → Navigate to log → ENTER (view content)

Deploy Files

Tag local files → Ctrl-e → server:/var/www → u (upload)

Backup Files

Ctrl-e → server:/data → Tag files → D (download)

Quick Config Edit

Ctrl-e → server:/etc → Navigate to config → s (shell) → vim config

Multi-Server File Distribution

Tag files locally → Ctrl-e → server1:/dest → u (upload)
Ctrl-e → server2:/dest → u (upload again)

Troubleshooting

Connection Fails

Check SSH access:

ssh user@hostname

If this works, RTFM should work.

Common issues:

Wrong username or hostname
SSH key not configured
Firewall blocking port 22
Path doesn’t exist on server

Slow Performance

Enable SSH connection caching (see SSH Configuration above)
Use SSH config aliases for complex connections
Reduce SFTP overhead with persistent connections

Permission Denied

Check user has access to remote directory
Verify SSH key permissions: chmod 600 ~/.ssh/id_*
Check server’s ~/.ssh/authorized_keys

Files Don’t Appear

Press r to refresh directory listing
Check if files exist: Press s to open shell, run ls

Upload Fails

Check destination directory exists and is writable
Verify sufficient disk space on server
Check file permissions locally

Advanced SSH Techniques

Jump Hosts

Configure in ~/.ssh/config:

Host production
    HostName internal.server.com
    ProxyJump jumphost.example.com
    User deployuser

Then: Ctrl-e → production:/path

Port Forwarding

Host database
    HostName localhost
    Port 5432
    User postgres
    LocalForward 5432 db.internal:5432
    ProxyJump jumphost

Multiple Identities

# Different keys for different servers
@sshhistory = [
  "-i ~/.ssh/work_key user@work.com:/projects",
  "-i ~/.ssh/personal_key user@personal.com:/files"
]

Security Considerations

Best Practices

Use SSH keys - Never use password authentication
Restrict key permissions - chmod 600 ~/.ssh/id_*
Use different keys - Different keys for different servers
Limited user accounts - Don’t use root for SFTP
Monitor uploads - Review what you’re uploading

What RTFM Sends

RTFM uses standard SFTP protocol - same as:

sftp user@hostname

No passwords are stored. SSH key authentication only.

Performance Tips

Faster Browsing

Persistent connections - Configure ControlMaster (see above)
Compression - Add to ~/.ssh/config: Compression yes
Disable strict checking - For trusted networks: StrictHostKeyChecking accept-new

Large File Transfers

For very large files, consider using rsync outside RTFM:

rsync -avP largefile.tar.gz user@server:/path/

RTFM is optimized for browsing and quick file transfers, not bulk data transfer.

Limitations

Remote mode restrictions:

No file deletion (safety)
No file moving (safety)
No permission changes (safety)
Read-only except download/upload

Why? Safety first. Use SSH shell (s key) for destructive operations.

Examples

Example 1: Deploy Website

# Local: Tag files to deploy
t t t (tag HTML, CSS, JS)

# Enter remote mode
Ctrl-e
user@webserver:/var/www/html

# Upload
u

# Verify
→ (check file info)

# Exit
Ctrl-e

Example 2: Download Logs

# Connect to server
Ctrl-e
admin@logserver:/var/log

# Tag logs
t t t

# Download
d

# Exit and analyze locally
Ctrl-e

Example 3: Quick Config Edit

# Connect
Ctrl-e
root@server:/etc

# Navigate to config
# (use arrow keys)

# Open shell
s

# Edit
vim nginx.conf

# Exit shell (back to RTFM)
exit

# Exit remote mode
Ctrl-e

← Configuration | Next: Keyboard Reference →

docs/remote-browsing