Command-line reference

The same tables are available at run time, as JSON, from rcp describe.

Commands

Command	Arguments	Writes	Summary
`copy`	`SOURCE DESTINATION`	yes	copies a tree, recording every entry in a catalog
`resume`		yes	finishes the copy of the catalog named by -id
`sync`		yes	brings the destination of -id back in line with its source, removing what the source dropped
`isync`	`SOURCE DESTINATION`	yes	syncs without a catalog, comparing the two trees as they are
`verify`	`SOURCE DESTINATION`	no	compares two trees byte for byte and reports every difference
`scan`	`SOURCE`	no	lists a tree and reports its shape, optionally saving the listing as an index
`estimate`	`SOURCE`	no	projects how long a copy would take, from a measured sample
`delete`	`TARGET`	yes	removes a tree; counts only until -force
`chmod`	`TARGET`	yes	applies a mode across a tree
`chown`	`TARGET`	yes	applies an owner and group across a tree
`diag`	`SUBCOMMAND`	yes	the diagnostic family: file utilities, generated I/O, index diagnosis, find and change
`show`	`[HOST]`	no	the mounted filesystems here, or what an NFS server offers
`serve`		yes	the far end of an ssh:// endpoint, on stdio; takes no arguments
`indexlist`		no	the catalogs under the catalog directory
`indexdelete`		yes	removes the catalogs named by -id or -match
`logdump`		no	the job log; given an ID it also writes ID.zip in the working directory
`copybatch`		yes	copies one batch of files on a worker’s behalf (-nodes)
`scanbatch`		no	scans one subtree on a worker’s behalf (-nodes)
`job`	`start\|list\|status\|wait\|cancel\|log\|forget`	yes	runs a command in a session of its own and reports on it afterwards, so a caller need not wait for a terabyte; a canceled job leaves its catalog behind, which `rcp resume` finishes for a copy – a sweeping verb (`sync`, `isync`) is finished by running that verb again, because `resume` never plans a removal
`mcp`	`[rails]`	no	a JSON-RPC 2.0 server on stdio, so an agent host can call rcp as a tool. The server writes nothing itself; each call runs rcp as a child, which carries this server’s rails, so -readonly here makes every call read-only rather than refusing to start
`describe`		no	this description, as JSON
`help`	`[info\|filters]`	no	the usage text
`version`		no	the version, the transports and what this build’s hardware offers

Endpoint schemes

Scheme	Syntax	Writable	Sparse	Hard links	Symlinks	Xattrs	ACLs	Rename	Identity	Delta	Times	Summary
`file`	`/path or file:///path`	yes	yes	yes	yes	yes	yes	yes	yes	yes	nanosecond	a local or mounted directory
`nfs`	`host:/export[:/sub] or nfs://host/export`	yes	yes	yes	yes	yes	yes	yes	yes	yes	nanosecond	an NFS export reached with the built-in v3 or v4.0 client
`ssh`	`ssh://[user@]host[:port]/path`	yes	yes	yes	yes	yes	yes	yes	yes	yes	nanosecond	a directory on a host that has rcp, through `rcp serve` over ssh
`rcp`	`rcp://host:port/path`	yes	yes	yes	yes	yes	yes	yes	yes	yes	nanosecond	the same `rcp serve`, over a socket it holds with -listen; plaintext, so the serve may bind only loopback
`rcps`	`rcps://host:port/path`	yes	yes	yes	yes	yes	yes	yes	yes	yes	nanosecond	the same socket inside TLS; with -tls.clientca the serve authenticates the peer, which is what lets it bind a routable address
`sftp`	`sftp://[user@]host[:port]/path`	yes	no	yes	yes	no	no	yes	no	yes	second	a directory on a host that has only OpenSSH, through its sftp subsystem
`s3`	`s3://bucket[/prefix]`	yes	no	no	yes	no	no	yes	no	no	nanosecond	an S3 bucket; POSIX metadata rides in user metadata
`hdfs`	`hdfs://namenode:port/path or hdfs:///path`	yes	no	no	no	no	no	yes	no	no	millisecond	an HDFS path over WebHDFS
`oci`	`oci://host[:port]/repository[:tag]`	yes	no	no	no	no	no	no	no	no	none	a container registry’s repository as an OCI image layout
`tar`	`tar://ARCHIVE[!/SUBPATH]`	yes	yes	yes	yes	no	no	no	yes	no	nanosecond	a tar archive as a tree: read any member, or write a new archive (ustar with pax headers, holes carried as GNU pax 1.0 sparse members); .tar.gz and .tar.zst are read by their magic and written by their name
`smb`	`smb://[user@]host[:port]/share[/path]`	yes	no	no	no	no	no	yes	no	no	100-nanosecond	a Windows, Samba or NAS share over SMB2 (dialects 0x0202-0x0300, NTLMv2)
`dav`	`dav://host[:port]/path or davs://...`	yes	no	no	no	no	no	yes	no	no	none	a WebDAV collection (Nextcloud, SharePoint, Apache mod_dav)
`http`	`https://host[:port]/path or http://...`	no	no	no	no	no	no	no	no	no	second with rcp-index.json, none from an autoindex	a web server as a READ-ONLY tree, listed from rcp-index.json, an nginx JSON autoindex or an Apache HTML one

Options

Option	Kind	Summary
`-parallel`	setting	worker count, or auto[:N] for the online tuner of workers plus read and write concurrency (default: CPUs, 2 to 8)
`-listen`	setting	serve: an address to serve the protocol on (loopback, unless -tls.cert, -tls.key and -tls.clientca are all set; -allow is required)
`-bs`	setting	read and write block size (default 1m)
`-engine`	setting	auto, uring or threads
`-depth`	setting	stop below this depth
`-bwlimit`	setting	read at most this many bytes a second (at least 4k)
`-nodes`	runs a program	comma-separated hosts to spread the copy or scan over
`-copybatch`	runs a program	a program to run per batch instead of copying here
`-dircount`	setting	NFS readdir buffer size (1k to 4m)
`-catalog`	safety rail	the catalog directory (else RCP_CATALOG, else the state directory)
`-newid`	setting	record this run under a new catalog id
`-id`	setting	the catalog id to resume, sync, scan from or delete
`-noid`	setting	keep no catalog for this run
`-snap`	path	resume or sync from this source instead of the catalog’s
`-match`	setting	keep paths matching this glob (repeatable)
`-exclude`	setting	drop paths matching this glob (repeatable)
`-minsize`	setting	files at least this large
`-maxsize`	setting	files at most this large
`-newer`	setting	files modified within this age
`-older`	setting	files untouched for this age
`-type`	setting	f, d or l
`-uid`	setting	files owned by this user
`-gid`	setting	files owned by this group
`-fileid`	setting	the entry with this inode number
`-nohash`	setting	no digest in the catalog; the kernel may copy the bytes
`-sha256`	setting	digest with SHA-256 (the default)
`-blake3`	setting	digest with BLAKE3
`-xxh3`	setting	digest with XXH3-64, the hash rsync and rclone speak; fast and NOT cryptographic
`-xxh128`	setting	digest with XXH3-128, the hash rsync and rclone speak; fast and NOT cryptographic
`-md5`	setting	accepted for compatibility; the run’s digest is unchanged
`-delta`	setting	send a file the destination already has as a patch against it
`-compress`	setting	compress the payloads on an ssh:// or rcp:// stream
`-compress.codec`	setting	lz4 (fast, the default), deflate or zstd (slower, smaller on text); implies -compress
`-compress-codec`	setting	the same as -compress.codec, the spelling the first zstd change used
`-compress.level`	setting	how hard deflate works, 1..9 (default 6); needs -compress.codec deflate, since neither lz4 nor this crate’s zstd encoder has a level; implies -compress
`-nolinks`	setting	copy hard links as separate files
`-noxattr`	setting	skip extended attributes and ACLs
`-acl4`	setting	carry NFSv4 ACLs on NFS endpoints
`-chown`	setting	ownership must be preserved: fail otherwise
`-noown`	setting	never touch ownership
`-preserve-atime`	setting	leave the source’s access times as they were
`-fsync`	setting	flush every file to stable storage
`-nocache`	setting	drop what was written from the page cache
`-dryrun`	setting	plan and report, write nothing
`-force`	setting	actually remove (delete counts without it)
`-removetopdir`	setting	remove the top directory too
`-replace`	setting	overwrite what is already there
`-nodata`	setting	compare metadata only
`-noattrs`	setting	compare content only
`-nomods`	setting	ignore modification times
`-mtimewindow`	setting	tolerate this many seconds of modification-time difference
`-json`	safety rail	the run’s events on stdout as JSON, one object per line; human lines move to stderr
`-allow`	safety rail	a root this run may touch, repeatable; outside it every endpoint is refused before it is opened
`-readonly`	safety rail	refuse every command that writes to an endpoint; rcp still records the run in the catalog’s jobs.log
`-confirm`	safety rail	the plan digest a dry run printed; the run proceeds only if the plan still has that digest
`-requireconfirm`	safety rail	refuse a run that would remove or overwrite unless -confirm matches
`-v`	setting	one line per entry
`-l`	setting	the long listing
`-q`	setting	no per-entry output
`-stats`	setting	the statistics report
`-csv`	setting	report as comma-separated values
`-html`	setting	report as HTML
`-fmt`	setting	a format string per entry
`-du`	setting	report sizes as du does
`-duk`	setting	report sizes as du -k does
`-edupe`	setting	report duplicate files
`-hashcache`	setting	reuse a remembered digest when size, mtime and inode all still agree
`-rsyncable`	setting	cut .tar.gz members at content-defined boundaries, so an edit does not change every later member
`-nonames`	setting	numeric user and group ids
`-progress`	setting	a progress line on stderr every few seconds
`-noprogress`	setting	no progress lines
`-loglevel`	setting	INFO or DEBUG
`-all`	setting	show everything, not just the usual subset
`-h`	setting	the usage text
`-help`	setting	the usage text
`-version`	setting	the version and transports
`-V`	setting	the version and transports
`-sample`	setting	how many bytes to read for the rate sample
`-gbit`	setting	the link speed to project against
`-t`	setting	how long a live test copy may run, or how long `job wait` waits
`-user`	setting	the user to set
`-group`	setting	the group to set
`-user-from`	setting	only change entries owned by this user
`-group-from`	setting	only change entries owned by this group
`-reference`	path	take the mode or owner from this path
`-mode`	setting	the mode to set
`-rcp.remote`	runs a program	the rcp to run on an ssh:// host
`-via`	runs a program	an ssh://[user@]host[:port] or rcp://host:port whose rcp serve opens every remote endpoint of this run on its behalf
`-tls.ca`	transport	the PEM bundle an rcps:// client checks the serve’s certificate against (default: the system bundle)
`-tls.cert`	transport	this side’s certificate chain (PEM): what a serve -listen presents, and what an rcps:// client presents when asked
`-tls.key`	transport	the private key for -tls.cert (PKCS#8, PKCS#1 or SEC1)
`-tls.clientca`	transport	the PEM bundle a serve -listen requires the peer’s certificate to come from; naming it is what turns mutual TLS on, and what lets a serve bind anything but loopback
`-nfs.sec`	transport	sys, krb5, krb5i or krb5p
`-nfs.vers`	transport	3 or 4
`-hdfs.namenode`	service	the namenode for hdfs:///path
`-s3.endpoint`	service	the S3 service to talk to
`-s3.profile`	credential	the AWS profile to take credentials from
`-s3.insecure`	transport	use http when the S3 endpoint names no scheme
`-s3.noverify`	transport	skip certificate verification
`-oci.user`	credential	USER:PASSWORD for the registry
`-dav.user`	credential	USER:PASSWORD for the WebDAV server
`-smb.user`	credential	[DOMAIN]USER:PASSWORD for the SMB share
`-smb.sign`	setting	sign and verify every SMB message even when the server does not ask, so an edit that clears its signing bit is refused
`-smb.handshake`	transport	seconds an SMB handshake may take before the connection is retried (default 10)
`-dav.insecure`	transport	use http for davs:// endpoints
`-dav.noverify`	transport	skip certificate verification for davs:// endpoints
`-http.user`	credential	USER:PASSWORD for an http:// or https:// source
`-http.noverify`	transport	skip certificate verification for https:// sources
`-http.index`	path	the published index to look for (default rcp-index.json; empty forces the autoindex readers)
`-oci.insecure`	transport	use http for oci:// endpoints
`-oci.noverify`	transport	skip certificate verification for oci:// endpoints
`-rmrf`	setting	diag: remove this tree
`-cat`	setting	diag: print this file
`-mkdir`	setting	diag: make this directory
`-rmdir`	setting	diag: remove this empty directory
`-rmid`	setting	diag: remove this catalog
`-n`	setting	the offset to read a job log from, and diag: how many
`-rand%`	setting	diag: percentage of random access
`-read%`	setting	diag: percentage of reads
`-npend`	setting	diag: how many operations in flight
`-size`	setting	diag: how large
`-u`	setting	diag: user
`-g`	setting	diag: group
`-umap`	path	diag: user id mapping, read from this file
`-gmap`	path	diag: group id mapping, read from this file
`-atime`	setting	diag: the access time to set
`-mtime`	setting	diag: the modification time to set
`-top-match`	setting	diag: match at the top level
`-branch-match`	setting	diag: match a branch
`-m`	setting	diag: a measure argument
`-j`	setting	diag: a job argument
`-read`	setting	diag: read
`-write`	setting	diag: write
`-random`	setting	diag: random access
`-sequential`	setting	diag: sequential access
`-wrdata`	setting	diag: write data
`-rebuild`	setting	diag: rebuild the index

Events

With -json, each line on stdout is one of these events.

Event	Fields
`entry`	a file, directory or symlink completed: path, kind (f\|d\|l), size, mtime_ns, mode, and digest when the run hashed it
`removed`	sync removed an entry the source dropped: path
`deferred`	the destination will remove the entry itself, later (a registry’s garbage collector): path and why; not a failure
`kept`	the destination refused to remove the entry and it is still there (a lock, a namenode’s no): path and why; the run fails
`difference`	verify found one: kind, path, detail
`warning`	something worth saying that did not fail the run: message
`error`	an entry or the run failed: code, message, and op and path for an entry
`done`	the command ended: status (passed\|failed), command, and that command’s counts

Exit codes

Code	Meaning
0	the command passed (STATUS: PASSED)
1	the command failed (STATUS: FAILED); the events say what

Keyboard shortcuts

rcp

Command-line reference

Commands

Endpoint schemes

Options

Events

Exit codes