The ShareFile Command Line Interface (SFCLI) is a scriptable tool for securely interacting with your ShareFile account.  It can upload and download files and synchronize entire directory structures.  Files sent via SFCLI are encrypted using SSL and are transmitted using the standard port 443. SFCLI is a great tool for uploading large amounts of data or connecting with Windows Scheduler to automate upload, download, and synchronization tasks.

The Basics

Installation: Windows

Download:

Installation: Macintosh

SFCLI can be used on Mac OS X by downloading the free Mono runtime environment from Novell. Install the Mono framework from the installation package; the development tools are not necessary for SFCLI to run. From a shell script, preface the SFCLI.exe on the command line in the examples with the command mono. For example:

mono SFCLI.exe -version

Identification:

-u username -pw password -s subdomain

Paths:

-l "Local Path

• This is the local path on the hard disk for SFCLI is to upload from or download into. It can terminate in a file or folder. It is important to enclose the path in quotes if it contains any spaces. It’s also important that the path not end in a backslash ("\") if quotes are being used. If, for some reason, this is unavoidable, put the -l tag at the very end of your call.
  • The local path can also terminate in a “pattern” like *.* or *.pdf, except during a sync, which only works with entire folders

• This is the path in ShareFile SFCLI is to upload into or download from. It can either be a path, a ShareFile Folder ID, or Request ID. ShareFile paths take the following form: /rootfolder/subfolder It is important to note that you cannot upload files directly to the ShareFile root (“/”). You can, however, upload a folder to the root, which would create a new root level folder, provided the flag -createroot is set.
  • The ShareFile path cannot terminate in a pattern.

Verbs:

Advanced

Syncing:

SFCLI can be used to sync a ShareFile folder and a local folder. Currently there is no option for a "bi-directional sync" that would make sure both locations had the latest versions of the files - all syncs are one-way. That is, when you specify the -sync tag you must also specify one of the basic verbs -upload or -download. This establishes which folder, the local or ShareFile, is the definitive (source) folder and should overwrite the other (target) folder. If -upload is specified, the local folder is the definitive source, and any files transferred will go "up" to ShareFile. If -download is specified, the ShareFile folder is the definitive source, and any files present there that are not present locally will come "down" to the local path. In addition to files missing from the target getting copied, files already present in the target that do not match the copy in the source will get overwritten by the definitive source version of the file. By default, files and folders present in the target folder that are not in the source are NOT deleted during a sync.

1. Strict Sync

• If -strict is specified in addition to -sync, strict sync is enabled. In this case, the target folder will be made to be an exact copy of the source folder - that is to say any files or folders present in the target directory that are not present in the source will be deleted.

• It is possible to use SFCLI to upload files to a Request a File link by specifying the -sf path to be a Request a File Link ID instead of a folder path or ID. This method has the advantage that it does NOT necessarily need to have a username and password specified on the command line. A subdomain (-s) is still necessary. Another advantage is that Request a File links can be expired. With these two advantages, you can deploy SFCLI to clients or vendors who need to be able to automate uploads to your account while not necessarily having a login to it, and you can also cut off their access at any time.
  
  Uploading to a Request a File link also has drawbacks:

Warning: -createroot and -deep do not work when uploading to a Request a File link

Both flags will simply be ignored if the target is a Request a File link and the opration will take place as if they were not present. The reason, in both cases, is that it is impossible to create a folder "under" a Request a File link - they only permit uploading files directly to them.

• For automated jobs where you are using a batch file and may not want to place the password of the account SFCLI is using in "clear text," SFCLI supports encrypted parameters. This layer of security is intended only as an obfuscation technique to prevent curious people from obtaining the password to an account and using it to log in to the web application, and should not be used in lieu of properly securing the PC or user account where SFCLI runs.
  
  

  To get an encrypted version of a parameter, use the -encrypt flag alone from the command prompt. For example:

sfcli -encrypt BoBsP4Ss

SFCLI will return the encrypted version in curly braces. You can use the encrypted version, including the curly braces, in place of the regular one on the command line. For example, if SFCLI returns {MNq9SdDMiOZR4iXm} as the encrypted version of BoBsP4Ss, then the following two commands would have the same results (other parameters omitted for clarity):

sfcli .... -pw BoBsP4Ss ....

sfcli .... -pw {MNq9SdDMiOZR4iXm} ....

Encryption is typically used only for passwords, but can be used for any parameter (folder IDs, local paths, usernames, etc.) The use of encrypted parameters requires build 1009 or higher of SFCLI.

Additional Flags:

1. - deep/recurse

• Specifying -deep or -recurse will make SFCLI recurse through all of the subfolders of a given source folder and perform the operation on them and their contents. This flag is useful for manipulating entire directory structures. Obviously, this flag does nothing when the source path is a single file rather than a folder

2. - createroot

• Specifying -createroot or -cr will make SFCLI create the source folder as a new subfolder of the destination folder. For example, if you are uploading c:\clients to /My SF Folder/, by default the result will be /My SF Folder/. However, if -createroot is specified, the result will be /My SF Folder/clients/.

3. - overwrite

• By default, SFCLI does not overwrite existing files. During a download, duplicate files are simply not downloaded; during an upload, copies are created. To change this behavior so existing files will be overwritten, specify -overwrite or -o.

Note: Pre-existing files are always overwritten during a sync if they differ!

4. - move

• Specifying -move will delete the source folder or file after it is successfully uploaded or downloaded.

5. - keepfolders

• Specifying -keepfolders or -kf in addition to the -move tag will delete source files after successful transfer, but leave folders and folder structures intact.

6. - quiet

• Specifying -quiet or -q will put SFCLI into quiet mode. In quiet mode, SFCLI only outputs when it starts and stops an operation, or when it encounters an error. This is useful if you need to log SFCLI's output to a file and do not need or want the full verbosity.

7. - help & version

• Specifying -help will output a briefer version of this documentation to the console. Specifying -version will output the current version of SFCLI to the console. No further action will be taken regardless of what other flags are set.

Examples:

sfcli -l "c:\Clients\*.pdf" -up -sf "/Clients/Acrobat Files" -u bob@widgetco.com -pw BoBsP4Ss -s widgetco -o

• This will upload every pdf file in the c:\Clients directory to /Clients/Acrobat Files on ShareFile, overwriting any duplicates. Any subfolders of c:\Clients and their contents will NOT be uploaded, because -deep is not set.

sfcli -l "c:\Clients\Jimbo" -up -sf "/Clients/" -u bob@widgetco.com -pw BoBsP4Ss -s widgetco -deep -cr

• This will upload the entire c:\Clients\Jimbo directory to ShareFile, including any subfolders and their contents. Since -cr is specified, Jimbo would be created as a subfolder of /Clients/ if it did not already exist. If /Clients/Jimbo/ already exists in ShareFile, any duplicate files it has will NOT get overwritten because -o is not specified.

sfcli -sf "/Clients/" -sync -down -l "c:\Clients" -u bob@widgetco.com -pw {MNq9SdDMiOZR4iXm} -s widgetco -deep

• This would download every file present in /Clients/ (including any in subfolders as -deep is set) that does not exist in or differs from one existing in c:\Clients. Any extra files in c:\Clients that are not present in /Clients/ will NOT get deleted because -strict is not set. This is also example of how to use an encrypted password.

sfcli -sf "/Clients/Jimbo" -down -l "c:\Clients\Jimbo" -u bob@widgetco.com -pw BoBsP4Ss -s widgetco -deep -move

• This would download every file present in /Clients/Jimbo/ to the local folder c:\Clients\Jimbo, including any subfolders as -deep is set. Duplicate files that exist in c:\Clients\Jimbo will NOT get overwritten as -o is not set. After a successful download, the entire /Clients/Jimbo/ folder will get deleted from ShareFile, as -move is specified and they have been "moved".

sfcli -sf "/" -sync -down -l "c:\ShareFile Backup" -u bob@widgetco.com -pw BoBsP4Ss -s widgetco -deep -strict

• This would download your entire ShareFile account (or at least, all of the files you have access to) to the directory c:\ShareFile Backup. Subsequent invocations of this command would download only files that have been updated in ShareFile since the last sync. Including the -strict flag will cause your backup to exactly match your ShareFile account, i.e., files that are deleted from ShareFile would get deleted from the local backup upon sync. Omitting the -strict flag would cause SFCLI only to download new and changed files, but never to delete files from C:\ShareFile Backup.