← xfer home · Download man page

XFER

NAME

xfer - interactive remote file transfer client

SYNOPSIS

xfer
xfer attach [id]
xfer -f | --file file
xfer -s | --script commands
xfer -h | --help
xfer -V | --version

DESCRIPTION

xfer is an interactive, terminal-based file transfer program for S3 and S3-compatible storage, SFTP, SMB, and WebDAV. It provides a command prompt, remote and local working directories, listings, recursive transfers, completion, a file selector, a pager, and job control.

Without arguments, xfer starts a new per-session daemon and attaches the terminal to it. Establish a connection with the open command. The daemon owns the connection, settings, and jobs; detaching the terminal does not cancel running transfers. A detached daemon exits when it has no running jobs.

The interface is modeled after lftp(1), but xfer is not a drop-in replacement. In particular, it does not implement FTP, FTPS, most of lftp’s batch options, or lftp’s shell command language.

Normal startup

For normal use, simply run:

xfer

This automatically creates a daemon and a terminal client connected to it. You do not need to start the daemon separately or attach manually. Detaching and reattaching are optional features for leaving jobs running and returning to them later.

Command scripts

xfer -s commands behaves like -f but takes the script inline, with commands separated by semicolons (not inside quotes or after a backslash).

xfer -f file starts a fresh daemon, runs commands from the named file, and exits. Each nonblank, non-comment line is one command, using the same quoting as the interactive prompt. Commands execute in order and each job finishes before the next command starts. Script output goes to standard output; the pager and command history are not used. The usual ˜/.xferrc is not read in script mode, so scripts do not depend on interactive startup commands. The daemon still reads its normal configuration files.

A failed or cancelled job, malformed or unknown command, failed Bash escape, or unavailable interactive operation stops the script with a nonzero exit status and a file and line diagnostic. Some commands report usage or setting errors as ordinary output rather than a failure status; such messages do not stop the script. Do not rely on the exit status alone to detect those errors.

Interactive password prompts, bookmark editing, and interactive job-control commands are not available. Use noninteractive credentials instead. exit or detach ends the script early. Lines starting with ! run Bash and a nonzero Bash exit status stops the script.

Attaching to a session

xfer attach attaches to the only ready detached daemon. If several are available, it lists their instance IDs and asks you to select one. With id, it selects an exact instance ID or an unambiguous ID prefix. Only one terminal may be attached to a daemon at a time.

Command syntax

Enter one command per line. Arguments use shell-like quoting and backslash escaping; for example:

cd ’photo album’
get ’annual report.pdf’

Ordinary xfer commands do not perform shell variable or command expansion, pipelines, redirection, command grouping, or chaining with semicolons, &&, or ||. A trailing & is not a background operator. Use Ctrl-Z to leave a job running in the background. Commands beginning with ! are an exception: their remaining text is passed unchanged to Bash.

Where supported, -- ends option parsing so that subsequent names beginning with a hyphen are operands. Quoting a wildcard does not disable a command’s own pattern matching. The get and put commands match patterns against files in the current remote or local directory, respectively, using * for any sequence and ? for one character; other characters are literal. Prefix a name with ./ to bypass their pattern expansion.

Jobs and retries

Remote operations run as daemon jobs. The client normally waits for a started job in the foreground. Ctrl-C requests cancellation of the foreground job; Ctrl-Z returns to the prompt without stopping it. Use jobs and status for information, fg to wait for a job again, and cancel to cancel a background job.

Retryable operations use backoff for transient failures. This is not a transaction guarantee: mutating operations such as mv and rm are not automatically replayed. A failed or cancelled operation can leave partial files or an ambiguous remote result. Inspect the destination before retrying.

COMMANDS

!command

Run a local Bash command with the terminal’s standard input, output, and error streams. The working directory is the daemon’s current local directory. Bash handles quoting, expansion, pipelines, and redirection. This is a client-side command, not a daemon job.

bookmark [edit | reload]

Without arguments, list bookmark names and addresses, omitting credentials. edit opens the TOML bookmark file using VISUAL, then EDITOR, or vi. A missing file is created with private permissions. reload validates the file. Bookmarks are read afresh on each connection, so edits do not require a daemon restart and do not change an existing connection.

debug [level]

Show or set the daemon log level and display the log file path. Level 0 (the default) records errors and warnings; 1 also records debug events; 2 also records trace events. By default the private log is named xfer-debug-<pid>.log in the initial local directory. Configure its filename with xfer:debug-file. The log file is created only when a message is emitted, and is not automatically deleted. Diagnostics omit command arguments, job output, and error details, which may contain sensitive data.

cancel job-id

Request cancellation of a daemon job.

cat [--] file...

Fetch remote file contents for display, using the pager for long output when enabled. Multiple operands are read in order.

cd [directory]

Change the remote working directory. Without an argument, return to the connection’s initial directory.

connect url|name

Connect to a URL or a bookmark. The URL scheme selects the backend; bookmarks may specify a backend explicitly. See PROTOCOLS and BOOKMARKS.

detach

Detach the terminal. Running daemon jobs continue; the daemon remains only while jobs are running. Reattach using xfer attach.

disconnect

Release the active backend connection.

du [-sh] [--] [path...]

Recursively report remote apparent byte usage, not allocated disk blocks. The default path is the current remote directory. -s reports only totals for the requested roots; -h uses human-readable sizes.

fg job-id

Bring a daemon job into the client’s foreground and wait for it.

get [-c] [--] file...

Download remote files into the daemon’s local working directory using their basenames. Patterns select files in the current remote directory. Existing local files are protected unless xfer:clobber is true. -c continues an existing local file from its current length. A local file larger than its remote counterpart cannot be resumed. Directories must be downloaded with mirror.

lcd [directory]

Change the local working directory used by transfers and Bash escapes. Without an argument, use the user’s home directory. Local paths may use ˜ or ˜/. The initial local directory is the directory from which the daemon started.

ls [-FlarSh] [--] [path]

List remote entries. Without a path, list the current directory. A path may name a directory, a file, or a supported filename pattern. Default options come from ui:ls-default-options.

Normally directories sort before files, with names sorted within each group. Command options are applied after the defaults. Use --no-classify, --no-long, --no-all, --no-reverse, --no-size, or --no-human-readable to disable the corresponding option.

mirror [-c] [--] directory...

Recursively download named remote directories below the local working directory, preserving each directory’s basename. A literal . downloads the contents of the current remote directory directly into the current local directory instead, including when the remote directory is root. Existing regular files are skipped by default, or overwritten when xfer:clobber is true. -c resumes existing files. This is a recursive copy, not a synchronization engine: it does not delete extra destination files or compare timestamps like lftp’s mirror command. Explicit remote root and dot-dot are not accepted as root directory names.

mirror-upload [--] directory...

Recursively upload local directories below the current remote directory, preserving their basenames. A literal . uploads the contents of the current local directory directly into the current remote directory instead. Local files are not removed. Replacement of existing remote files is controlled by xfer:clobber. This command has no resume option and does not delete extra remote files.

mirror-up

Alias for mirror-upload.

mkdir [-p] [--] directory...

Create remote directories. -p (--parents) creates missing parents and accepts existing directories. S3 directories are trailing-slash marker objects; this command does not create buckets.

mv [-f] [--] source destination

Rename a remote file to an exact destination path, not a destination directory. Directory moves are not supported. -f (--force) permits replacement of an existing file for this operation; otherwise xfer:clobber controls replacement. S3 implements this as copy followed by delete, which is not atomic.

open url|name

Alias for connect.

put [--] file...

Upload local files into the current remote directory using their basenames. Patterns select regular files in the current local directory. Existing remote files are protected unless xfer:clobber is true. Use mirror-upload for directories.

rm [-rf] [--] path...

Delete exact remote paths. Without -r, only files are removed. WARNING: -r recursively deletes directories and their contents. This is dangerous and cannot be undone. Recursive deletion is supported for SFTP, SMB and S3; WebDAV recursive deletion is not supported because a collection DELETE can recursively remove newly created children. Symlinks are not followed by SFTP; SMB reparse points are refused. Do not modify a remote tree concurrently with recursive deletion. By default, stop on the first error. -f continues after errors, reports them, and leaves the job failed if any occurred; it does not suppress missing-file errors. Mutations are never retried. Use -- before paths beginning with a dash.

set name value

Change a daemon setting. Quote values containing spaces; use an empty quoted string for an empty text value. Changes are session-local and are not written to a configuration file. Connection settings generally take effect on a new connection.

show [name]

Show all settings or a single setting, with descriptions. Password values are redacted.

status [job-id]

Without an argument, show daemon, connection, local and remote directory, and configuration-file information. With a job ID, show job details.

PROTOCOLS

s3://bucket

Use S3 with the default AWS credential chain unless bookmark credentials are supplied. Use s3:endpoint or an HTTP(S) S3 bookmark for an S3-compatible service. Buckets must already exist. Only Signature Version 4 is supported.

sftp://[user@]host[:port][/path]

Use SFTP through OpenSSH. SSH configuration, keys, and ssh-agent are normally used for authentication. Host-key checking is strict by default. Password bookmarks support a single password exchange, not keyboard-interactive MFA or challenge-response authentication.

smb://[domain;][user@]host[:port][/share[/path]]

Use SMB. A server URL without a share can be used to browse shares. An empty username means anonymous access, not the operating-system user.

http://host/path/, https://host/path/

Use WebDAV. The schemes dav, davs, webdav, and webdavs are also supported; the variants ending in "s" use TLS. The server must support WebDAV PROPFIND; an HTML directory index is insufficient. Authentication is anonymous or Basic, not Digest, NTLM, OAuth/Bearer, or client certificates. Plaintext HTTP credentials are refused unless explicitly enabled.

HTTP(S) bookmarks select S3 instead of WebDAV when they specify type = ’s3’, a bucket field, or an accessKey field. An explicit bookmark type takes precedence over inference.

SETTINGS

Settings are named with colon-separated namespaces. Boolean values are true or false; timeouts are in seconds. The defaults are shown below. Use show for current values.
bookmarks:file (path)

Bookmark file. Default: bookmarks.toml in the application configuration directory.

cache:max-bytes (integer)

Per-connection directory cache budget in bytes. Default: 4194304. Reconnect to apply.

cache:ttl (integer)

Directory cache lifetime in seconds; zero disables caching. Default: 30. Reconnect to apply.

s3:endpoint (string)

Optional S3-compatible HTTP(S) endpoint. Default: empty.

s3:region (string)

Default S3 signing region. Default: us-east-1.

sftp:connect-timeout (integer)

Positive SSH connection and authentication timeout. Default: 30.

sftp:disable-strict-checking (boolean)

Disable strict SSH host-key checking for new connections. Default: false. This permits unverified unknown host keys and is insecure; OpenSSH may still restrict authentication when a known host key changes.

sftp:max-requests (integer)

Concurrent SFTP read/write requests, from 1 to 256. Default: 64. Reconnect to apply.

smb:connect-timeout (integer)

SMB connection and login timeout. Default: 10.

smb:operation-timeout (integer)

SMB operation timeout. Default: 30.

smb:max-credits (integer)

Maximum in-flight 64 KiB transfer chunks, from 1 to 128. Default: 32. Reconnect to apply.

smb:user (string)

Default SMB username; empty selects anonymous access. Default: empty.

smb:password (secret)

Default SMB password, displayed redacted. Default: unset. Prefer per-bookmark credentials or interactive entry.

smb:domain (string)

Default NTLM domain. Default: empty.

smb:dfs (boolean)

Allow DFS referrals to other servers, forwarding credentials to them. Default: false. Reconnect to apply.

smb:require-encryption (boolean)

Refuse shares without active SMB3 encryption. Default: false. Reconnect to apply.

ssl:skip-validation (boolean)

Disable TLS certificate validation. Default: false. Enabling this is insecure and permits man-in-the-middle attacks.

ui:auto-pager (boolean)

Use the built-in pager for long output. Default: true.

ui:history-file (path)

Persistent command history file. Default: history in the application state directory. The values session and /dev/null disable persistence. The client reads this setting when attaching.

ui:ls-default-options (string)

Base options for ls. Default: -lF. Only options, not a path, are allowed.

ui:prompt (string)

Prompt template. Default: "xfer$location> ". Substitutions are $cwd (protocol and remote path), $cwdn (remote basename), $user, $host, $proto, $lcwd (local path), $lcwdn (local basename), and $location (bracketed protocol and remote path, empty when disconnected). Braced forms such as ${host} are accepted; $$ produces a literal dollar sign. No shell code is evaluated.

webdav:user (string)

Default WebDAV Basic-auth username; empty means anonymous. Default: empty.

webdav:password (secret)

Default WebDAV password, displayed redacted. Default: unset.

webdav:allow-insecure-auth (boolean)

Allow Basic credentials over plaintext HTTP. Default: false. This exposes credentials to the network. Reconnect to apply.

webdav:connect-timeout (integer)

TCP connection timeout, from 1 to 300 seconds. Default: 10.

webdav:operation-timeout (integer)

Request/read timeout, from 1 to 300 seconds. Default: 30.

xfer:debug-file (string)

Daemon log filename template. Default: ${cwd}/xfer-debug-${pid}.log. ${pid} and ${cwd} (or the unbraced forms $pid and $cwd) expand to the daemon PID and local directory when the setting is applied. Relative filenames are resolved against that directory. Use quotes around the value in a command if it contains spaces. An existing private regular file owned by the user is appended to, allowing multiple daemons to share a log; each line includes the daemon PID. Parent directories must already exist. A runtime change switches the destination immediately. Invalid paths detected when applying the setting leave the previous destination unchanged; file creation and its permission checks occur when a message is first emitted.

xfer:clobber (boolean)

Allow downloads to overwrite local files and uploads or renames to replace remote files. Default: false. Recursive downloads have their own skip/resume behavior; see mirror.

CONFIGURATION

At daemon startup, xfer reads xfer.conf from its application configuration directory, then reads the file named by XFER_CONFIG if set. Later values override earlier values. Missing optional files are ignored. Configuration lines have the form name: value; blank lines and lines whose first non-space character is # are ignored. Values are literal text, not shell-quoted command arguments.

# xfer.conf
ui:auto-pager: true
ui:ls-default-options: -lhF
s3:region: us-east-1
sftp:max-requests: 64
ssl:skip-validation: false

On the first attachment to a daemon, the client also reads ˜/.xferrc and executes its commands in order, one command per line. Blank lines and comment lines are ignored. This file uses command syntax, not the configuration-file setting syntax. It is not rerun on later attachments. For example:

# ˜/.xferrc
set ui:prompt ’xfer$location> ’
lcd ˜/Downloads

BOOKMARKS

Bookmarks are TOML tables in the file selected by bookmarks:file. Each table name is an alias accepted by open. The url field is required; type may be s3, sftp, smb, or webdav. When omitted, the type is inferred from the URL and S3-specific fields. Unknown fields are rejected.

[archive]
type = ’s3’
url = ’s3://example-archive’
region = ’us-east-1’

[minio]
type = ’s3’
url = ’https://minio.example.net’
bucket = ’backups’
accessKey = ’replace-me’
secretKey = ’replace-me’
api = ’s3v4’

[home]
url = ’sftp://alice@sftp.example.net/home/alice’

[nas]
url = ’smb://nas.example.net/Documents’
user = ’alice’
domain = ’WORKGROUP’
password_interactive = true

[web-files]
url = ’https://dav.example.net/files/’
user = ’alice’
password_interactive = true

S3 fields are bucket, region, accessKey, secretKey, sessionToken, api, override_host, and override_port. Access and secret keys must be supplied together. Without explicit credentials, the AWS credential chain is used.

SFTP, SMB, and WebDAV bookmarks may store a password or set password_interactive = true to request a password in the terminal. SMB and WebDAV also support user; SMB supports domain. Explicit empty user fields select anonymous access. For SFTP, specify the username in the URL.

Protect files containing credentials, for example with mode 0600. Prefer interactive passwords to plaintext storage. Credential-bearing connection commands and password-setting commands are excluded from history, but shell escapes and other command text may still contain secrets: do not rely on history filtering as a general secret scrubber.

TERMINAL INTERFACE

At the prompt, Tab completes commands, bookmarks, settings, and applicable local or remote paths. Up and Down navigate command history. Ctrl-A and Ctrl-E move to the beginning and end of the line. Ctrl-L redraws the screen. Ctrl-C clears the current input; Ctrl-D on an empty line detaches.

Ctrl-S opens the context-sensitive file selector. Use arrows or j/k to move, Page Up/Down or Ctrl-B/Ctrl-F to scroll, Home/End for boundaries, Space to mark entries where multiple selection is available, and Enter to accept. Slash starts filtering. Escape or Ctrl-C cancels.

In the built-in pager, use arrows or j/k for lines, Space, Page Down, or Ctrl-F for the next page, Page Up or Ctrl-B for the previous page, and Home/End for the beginning/end. Press q or Escape to quit. The vertical bar key opens a private copy of the output in VISUAL, then EDITOR, or vi; editing the copy does not change the pager’s data.

ENVIRONMENT

XFER_CONFIG

Additional settings file, read after the default xfer.conf at daemon startup.

XDG_CONFIG_HOME

If absolute, places configuration in $XDG_CONFIG_HOME/xfer.

XDG_CACHE_HOME

If absolute, places disposable data in $XDG_CACHE_HOME/xfer.

XDG_STATE_HOME

If absolute, places persistent local state in $XDG_STATE_HOME/xfer.

XDG_RUNTIME_DIR

If absolute, places daemon discovery files and sockets in $XDG_RUNTIME_DIR/xfer/instances. Otherwise the native runtime directory is used if available, falling back to the state directory’s instances subdirectory. Empty or relative XDG overrides are ignored.

VISUAL, EDITOR

Editor commands for bookmark editing and pager output copies.

AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN, AWS_PROFILE

Used by the standard AWS credential provider chain when bookmark credentials are not supplied.

SSH_AUTH_SOCK

Used by OpenSSH for ssh-agent authentication.

FILES

The following are Linux defaults. Absolute XDG overrides take precedence. On macOS, configuration and persistent state normally use ˜/Library/Application Support/xfer, and cache data uses ˜/Library/Caches/xfer.
˜/.config/xfer/xfer.conf

Daemon settings.

˜/.config/xfer/bookmarks.toml

Connection bookmarks; overridable with bookmarks:file.

˜/.xferrc

Commands run on the first attachment to a daemon.

˜/.local/state/xfer/history

Persistent command history; overridable with ui:history-file.

˜/.cache/xfer/jobs/

Daemon job output spools.

$XDG_RUNTIME_DIR/xfer/instances/

Private daemon sockets and discovery files when XDG_RUNTIME_DIR is set.

˜/.ssh/config, ˜/.ssh/known_hosts

OpenSSH client configuration and known host keys used by SFTP.

EXAMPLES

Connect to a bookmark, download a file, and upload a local file:

$ xfer
xfer> open home
xfer[sftp:/home/alice/]> ls
xfer[sftp:/home/alice/]> get report.pdf
xfer[sftp:/home/alice/]> put local-notes.txt

Resume a download and recursively copy a directory:

lcd ˜/Downloads
get -c large-image.iso
mirror -c photos

Upload a local directory, explicitly allowing replacement:

set xfer:clobber true
mirror-upload documents
set xfer:clobber false

After Ctrl-Z backgrounds a transfer, inspect it and detach:

jobs
status 1
detach

From another terminal, while the detached daemon still has running jobs:

$ xfer attach

LIMITATIONS

S3 has no real directories. File moves use server-side copy followed by delete and can leave both objects after failure or cancellation. Objects up to 5 TiB are supported; uploads and copies larger than 5 GiB use multipart operations. Multipart copy also requires permission to read object tags and abort multipart uploads. Directory/prefix moves are not implemented.

Failed or cancelled multipart uploads and copies are aborted on a best-effort basis. Configure S3 lifecycle cleanup for incomplete multipart operations to avoid ongoing storage charges. If completion fails, check the destination before retrying because completion may have succeeded. Other backends may also leave partial files after failed uploads.

Disabling TLS validation or strict SSH host-key checking compromises peer authentication. Sending Basic credentials over HTTP exposes them in plaintext. Keep the secure defaults unless the risks are understood.

AUTHOR

Grzegorz Antoniak <xfer@anadoxin.org>

WEBSITE

https://anadoxin.org/xfer

SEE ALSO

lftp(1), ssh(1), ssh_config(5), bash(1)