Skip to main content

Synchronizing Files and Folders

The sync operation copies files between a local folder and a Files.com folder.

The CLI compares files at matching paths and skips the transfer when the destination file has the same size. This metadata comparison lets it decide what to transfer without reading both copies in full. It does not use a checksum to detect content changes, so a file whose contents changed without changing its size can be skipped. Skipping a transfer does not prevent the source file from being deleted or archived when you enable those options below. Use the dry run option to review which files a sync would transfer.

Push (upload) files from a local Documents folder to a Files.com folder of the same name:

files-cli sync push --local-path="Documents" --remote-path="Documents" --send-logs-to-cloud

Pull (download) files to a local Documents folder from a Files.com folder of the same name:

files-cli sync pull --remote-path="Documents" --local-path="Documents" --send-logs-to-cloud

Delete Source File After Successful Sync

Use the --delete-source-files flag when the source folder should retain only files still waiting to reach the destination. The CLI deletes each source file after a successful transfer or when a file with the same path and size already exists at the destination. In the latter case, no transfer is needed before deletion, regardless of which user, application, or earlier run placed the file there.

The existing-file check compares path and size, not contents. A source file can therefore be deleted even if its contents differ from a destination file of the same size.

A source file stays in place if its transfer fails, if the --include or --ignore filters exclude it, or if --no-overwrite skips an existing destination file. These exceptions also apply to --move-source.

files-cli sync pull --remote-path="path/to/source/folder" --local-path="path/to/local/destination/folder" --send-logs-to-cloud --delete-source-files

If deleting the source files would leave an empty folder you want to dispose of, add the --delete-source-empty-folders flag. A common case is a sync that pulls data from a folder created every day by an external process; --delete-source-empty-folders cleans up the source filesystem and prevents performance issues from accumulated empty folders.

files-cli sync pull --remote-path="path/to/source/folder" --local-path="path/to/local/destination/folder" --delete-source-files --delete-source-empty-folders --send-logs-to-cloud

Move Source File After Successful Sync

Use the --move-source flag to archive source files instead of deleting them. It applies to the same files as --delete-source-files: files that transfer successfully and files already present at the destination with the same path and size. An existing match allows the source file to be archived without a transfer. The move occurs within the source location, so you can clear the working folder while retaining a separate archive.

For a sync push, the source location for the move is the local system where you are running the files-cli:

files-cli sync push --local-path="path/to/local/source/folder" --remote-path="path/to/destination/folder" --move-source="path/to/local/archive/folder" --send-logs-to-cloud

For a sync pull, the source location for the move is the Files.com platform:

files-cli sync pull --remote-path="path/to/source/folder" --local-path="path/to/local/destination/folder" --move-source="path/to/archive/folder" --send-logs-to-cloud

Ignore Certain Files or Folders

Use the --ignore flag to skip certain files or folders. Pass the file and folder name patterns to ignore as a comma-separated string:

files-cli sync push --local-path="path/to/local/source/folder" --remote-path="path/to/destination/folder" --ignore='*.exe,*.msi,Archive/,secret/' --send-logs-to-cloud

Include Only Specified Files or Folders

Use the --include flag to limit the sync to specified file or folder patterns. Pass the patterns as a comma-separated string:

files-cli sync push --local-path="path/to/local/source/folder" --remote-path="path/to/destination/folder" --include='*.txt,*.pdf' --send-logs-to-cloud

Preserve File Times

Uploaded or downloaded files, including those transferred by a sync operation, normally arrive at the destination with a new timestamp reflecting the time of arrival.

Use the --times flag to preserve the original timestamp instead. Files arrive at the destination with the same timestamp they had at the source. This is useful when archiving or backing up data, so you can tell whether a file at the source has changed compared to the copy at the destination.

File times are preserved only if your site is configured to allow file modification times to be set. If file times are not preserved, check your site's data governance settings.

files-cli sync pull --local-path="Documents" --remote-path="Documents" --send-logs-to-cloud --times

Dry Run

Use the --dry-run flag to preview the actions a sync would take without transferring any data. The output shows which files would be affected by the operation. It uses the same size comparison as the actual sync, so the preview does not verify that the file contents match.

files-cli sync pull --local-path="Documents" --remote-path="Documents" --send-logs-to-cloud --times --dry-run