HostnExtra Sync

HostnExtra Sync is the official sync plugin for the HostnExtra CLI. Fast and simple file synchronization between local and remote servers using SSH and rsync.

HostnExtra Sync provides a clean CLI around rsync for common file synchronization tasks without requiring users to manage complex rsync and SSH commands manually.

Why HostnExtra Sync?

rsync is powerful and efficient, but its command syntax becomes difficult to manage when combined with SSH configuration, exclusions, dry runs, deletion, and repeated synchronization.

HostnExtra Sync provides a simpler interface:

hostnextra sync push ./build --to web-prod-01:/var/www

The actual file synchronization is performed by rsync, allowing HostnExtra Sync to benefit from rsync's efficient synchronization and partial-transfer capabilities.

Features

• Push files and directories to remote servers
• Pull files and directories from remote servers
• Compare local and remote content
• Watch local directories and synchronize changes automatically
• Dry-run support
• Exclude patterns
• Safe directory-scoped --delete
• SSH connection reuse
• Remote rsync availability detection
• Progress reporting
• Direct SSH targets
• HostnExtra SSH Config integration

Requirements

• Node.js 22+
• rsync installed locally
• rsync installed on the remote server
• SSH access to the remote server

Check the local rsync installation:

rsync --version

Installation

Install the HostnExtra CLI.

npm install -g hostnextra

Install the SSH Config plugin.

hostnextra plugin add sync

Verify the installation.

hostnextra plugin list

Update

Install the latest version of the plugin.

hostnextra plugin update sync

HostnExtra Sync requires rsync on both ends because rsync performs the actual synchronization.

Commands

Push

Synchronize a local file or directory to a remote server.

hostnextra sync push ./build --to web-prod-01:/var/www

Pull

Synchronize a remote file or directory to the local machine.

hostnextra sync pull web-prod-01:/var/www/build --to ./backup

Diff

Compare local and remote content without modifying either side.

hostnextra sync diff ./build --to web-prod-01:/var/www

Watch

Continuously synchronize a local directory when changes are detected.

hostnextra sync watch ./src --to web-prod-01:/var/www

Watch mode is intended for development and local-to-remote synchronization.

Status

Display the local rsync version and supported capabilities.

hostnextra sync status

Options

| Option | Description | | --- | --- | | --to <target> | Synchronization target | | --dry-run | Preview synchronization without modifying files | | --delete | Delete files missing from the source within the synchronization scope | | --exclude <patterns> | Exclude files or directories | | --no-progress | Disable transfer progress |

SSH Targets

HostnExtra Sync supports direct SSH targets:

hostnextra sync push ./build --to [email protected]:/var/www

It can also use server definitions from the HostnExtra SSH Config plugin:

hostnextra sync push ./build --to web-prod-01:/var/www

When SSH Config is available, HostnExtra Sync can use the configured host, user, port, identity file, and ProxyJump settings.

The SSH Config plugin is optional. Direct SSH targets work independently.

--delete

--delete is a destructive operation and should be used deliberately.

It removes files from the synchronization scope when those files do not exist in the source.

For example:

hostnextra sync push ./build --to web-prod-01:/var/www --delete

Deletion is limited to the directory being synchronized. Files and directories outside that synchronization scope are not candidates for deletion.

HostnExtra Sync requires explicit confirmation before performing a non-dry-run delete operation.

Directory Only

--delete can only be used when synchronizing a directory.

It is intentionally rejected for individual files:

hostnextra sync push ./file.txt --to web-prod-01:/var/www --delete

This prevents ambiguous and potentially destructive file-level deletion behavior.

Before using --delete on an important directory, use a dry run first:

hostnextra sync push ./build --to web-prod-01:/var/www --delete --dry-run

Exclusions

Exclude files or directories using --exclude:

hostnextra sync push ./build \
  --to web-prod-01:/var/www \
  --exclude node_modules,.git

Multiple patterns can be provided as a comma-separated list.

Dry Run

Preview a synchronization without modifying files:

hostnextra sync push ./build \
  --to web-prod-01:/var/www \
  --dry-run

Dry runs are especially useful before using --delete.

Remote rsync

HostnExtra Sync checks that rsync is available on the remote server before starting a synchronization.

If rsync is unavailable, HostnExtra Sync reports the requirement and provides installation commands for common Linux distributions.

Ubuntu / Debian

sudo apt install rsync

RHEL / Rocky / AlmaLinux / Fedora

sudo dnf install rsync

Arch Linux

sudo pacman -S rsync

Security

HostnExtra Sync uses the system SSH client for remote authentication.

It does not store or manage SSH passwords.

SSH keys, SSH agents, password authentication, custom ports, identity files, and ProxyJump configurations are handled through the SSH configuration available to the connection.

Temporary SSH control sockets used for connection reuse are created in the system temporary directory and cleaned up after synchronization.

Design

HostnExtra Sync keeps its scope focused.

It provides a user-friendly synchronization interface while leaving file transfer and synchronization logic to rsync.

The project is not intended to replace:

• rsync
• SSH
• Git
• CI/CD systems
• deployment platforms
• backup systems

Its purpose is to make common rsync-based synchronization workflows easier to use within the HostnExtra CLI.

Development

Install dependencies:

npm install

Type-check:

npm run check

Build:

npm run build

Run local tests:

npm test

Integration tests require an SSH-accessible test server with rsync installed.

License

MIT License

Copyright © HostnExtra

HostnExtra

HostnExtra Sync is an open-source plugin for the HostnExtra CLI.

HostnExtra