xxh

Connect to a host and run the current shell

$ xxh "[host]"

$ xxh "[host]" ++install

$ xxh "[host]" ++shell [xonsh|zsh|fish|bash|osquery]

$ xxh "[host]" ++host-xxh-home [~/.xxh]

$ xxh "[host]" ++xxh-config [~/.config/xxh/config.xxhc]

$ xxh "[host]" ++password "[password]"

$ xxh "[host]" ++install-xxh-packages [package]

$ xxh "[host]" ++env [name]=[value]

xxh [OPTIONS] [USER@]HOST [COMMAND]
xxh [OPTIONS] [USER@]HOST:[PATH]

--shell <shell_name>
    Specify the shell to use on the remote host (e.g., zsh, bash, fish).

--plugins <plugin_names>
    A comma-separated list of xxh plugins to enable and apply to the remote shell environment.

--install
    Force installation or re-installation of the xxh client and specified shells on the remote host.

--update
    Update the xxh client and/or the installed shells and plugins on the remote host.

--config
    Open or modify the xxh client configuration file on the local machine.

--ssh-options <options>
    Pass raw options directly to the underlying ssh command (e.g., -o StrictHostKeyChecking=no).

--arguments <args>
    Pass arguments directly to the remote shell once it starts. Useful for interactive shell sessions.

--login <user>
    Specify the username for the SSH login on the remote host.

--port <port>
    Specify the SSH port to connect to on the remote host.

--key <path>
    Specify the path to an identity file (private key) for SSH authentication.

--yes
    Automatically answer 'yes' to all prompts, useful for non-interactive scripts.

--verbose
    Enable verbose output, showing detailed steps of the xxh process for debugging.

--version
    Display the current version of the xxh client.

--help
    Display a help message with available options and usage.

The xxh command acts as a powerful wrapper around the standard ssh client, designed to provide a consistent and personalized shell environment on any remote server.
It enables users to utilize their preferred local shell (like Zsh, Fish, or Bash) along with their customized dotfiles and plugins, even if these are not natively installed or configured on the remote host.
Unlike a simple ssh connection, xxh automatically manages the transfer and setup of the desired shell and its configurations on the remote machine. It achieves this by transferring a small Python client to the remote, which then handles the download and unpacking of a pre-built shell environment (e.g., zsh-xxh) into the user's home directory (~/.xxh) on the remote.
This significantly streamlines development workflows and enhances user experience by eliminating the need for manual remote shell setup or complex configuration synchronization.

• Requires Python 3.6 or higher to be present on the remote host for the xxh server component to function.
• Initial connection to a new host or selection of a new shell/plugin might incur a delay due to downloading and unpacking the necessary shell environment and plugins.
• Network bandwidth is consumed for transferring shell environments and plugins, which can be significant depending on the configuration.
• While designed with security in mind, introducing external scripts and configurations (plugins, dotfiles) to a remote system always carries inherent security considerations.
• xxh is not a standard Linux utility; it needs to be explicitly installed on the local client machine.

When you invoke xxh, it first establishes an SSH connection to the remote host. It then uploads a small Python script to the remote host. This script, which acts as the xxh server component, checks for Python availability and then downloads and unpacks the selected shell environment (e.g., zsh-xxh, bash-xxh) and any specified plugins into the ~/.xxh directory on the remote. Finally, it launches your preferred shell with your local dotfiles and configurations applied, giving you a consistent and familiar experience.

xxh supports a robust plugin system, allowing users to extend its functionality significantly. Plugins can include additional utilities, custom shell configurations, themes, or other scripts that are automatically deployed and activated in the remote shell environment. This makes xxh highly customizable and adaptable to various development needs, from specific language toolchains to custom prompt setups.

The xxh project was initiated by Andrey Lekar (lekum) with its first public commits appearing on GitHub around 2018. It emerged from the common frustration of maintaining consistent shell environments across numerous remote servers. The goal was to simplify the process of bringing a personalized development environment, including specific shells, dotfiles, and plugins, to any remote machine without extensive manual setup or system-wide installations. Its development has focused on cross-platform compatibility and ease of use, leveraging Python for its remote client component and providing a rich plugin ecosystem.

ssh(1): The fundamental Secure Shell client for remote command execution and file transfer., rsync(1): A versatile tool for remote file copying and synchronization, often used for managing dotfiles., tmux(1): A terminal multiplexer that allows multiple terminal sessions within a single window, useful for persistent remote sessions., screen(1): Another terminal multiplexer, similar to tmux, providing session management capabilities.