Command Line Options in the Groups Application

Last updated

This article has moved to our new Help Center and will no longer be updated on this page. Please see the Help Center for the newest version.

Command line operation is available on all supported desktop operating systems. Running SpiderOak Groups with --help will give you a general overview. The output of the --help command can also be found at the bottom of this article.

Beginning with version 6.0, paths to the executable are:

  • Windows: C:\Program Files\SpiderOak Groups\SpiderOakGroups.exe
  • Mac OS X: /Applications/
  • Linux: /usr/bin/SpiderOakGroups

Below are additional details on two options that an administrator may find especially useful.


The --setup option automates initial login of the client through the use of a JSON configuration file. At a minimum, the file should contain these options:

  • username - The username of the account to be logged into.
  • password - The password of the account to be logged into. An auth token generated in the Management Console by the administrator can be used in place of the account password.
  • device_name - The name the device should be given within the SpiderOak Groups application.
  • fingerprint - The organization’s fingerprint (found in the Management Console).


  • reinstall - Should be set to true or false. The setting defaults to false if omitted. This should only be set to true if SpiderOak Groups is being reinstalled on a device it was installed on before with the exact same file structure. This option should not be used to recover files to a new device. In the event of a reinstall, the device_name should be the name of an existing device that is being reinstalled.

When completed, the JSON file should look like this:

    "username": "username",
    "password": "password",
    "reinstall": false,
    "device_name": "device name",
    "fingerprint": "org fingerprint"

--point-in-time <date/time>

As of version 6.1.2, point-in-time recovery of directories and their contents is supported by the SpiderOak Groups application. This feature, used in conjunction with --restore, allows for the recovery of a directory as it appeared on a particular date and/or time.

The general syntax of the command (using Windows in this example) is:

SpiderOakGroups.exe --restore C:\DIRECTORY\TO\RESTORE --point-in-time YYYY-MM-DD/hh:mm

By default, the restored directory is placed in the SpiderOak Groups download directory, not in the original location. This prevents the possibility of data being erroneously overwritten. You may also combine --point-in-time with one or more of the following options:

  • --output /TARGET/LOCATION specifies where to download the directory to. If not specified, it will be downloaded to the default download directory.
  • --device N specifies the device number (not name) to download the directory from. If not specified, the directory will be downloaded from the current device.
  • --verbose will specify the files being downloaded.
  • --simulate will report what files would be downloaded, but will not actually download anything. By its nature this command is verbose, so there is no need to specify verbose when --simulate is used.

Prior to using --point-in-time, you may find it helpful to use --tree-changelog to see what restore points are available. Note however that point in time restoration is not retroactive and can only restore points backed up since the installation of a SpiderOak Groups version that supports this feature (version 6.1.2 or later). For example, if you upgraded on February 1, 2016 to a version that supports point in time restoration, then you will not be able to restore to points prior to that date even if --tree-changelog reports prior changes. Note also that the output of --tree-changelog can be very large. It is recommended that you redirect the output of the command to a file so that it can be more easily worked with.

The --point-in-time option also gives administrators access to files maintained through Purgehold. In order to access the held files the administrator must have previously enabled Purgehold for the user and, before using --point-in-time, must run SpiderOak Groups with the --get-held-metadata option. This command will download information related to any deleted files being maintained by Purgehold so that they can be restored.

--help output:

Usage: SpiderOak Groups basic command line usage:
  --version             show program's version number and exit
  -h, --help            show this help message and exit
  -v, --verbose         be verbose: show detailed status information as it
  --redirect=FILE       Redirect console output to file
  -d NUMBER, --device=NUMBER
                        operate on specified device id (default is the local
  -o DIR, --output=DIR  Target dir to restore items to (default is normal
                        download dir)
  --enable-schedule     honor the set activity schedule, even in batchmode
                        (normally the schedule is ignored in batchmode)
  --disable-schedule    disable activity scheduling
  Operational Modes and Commands:
    --scan, --scan-only
                        scan the filesystem for changes and report a summary
    --build, --scan-and-build-only
                        scan the filesystem, and build all possible file
                        system changes as shelved upload transactions, and
                        exit without uploading them
    --sync              like batchmode, but only backup/update synced folders
    --backup=TARGET     ad hoc operation: backup whatever exists at TARGET in
                        the filesystem and exit (ignores existing backup
    --restore=item      Restore a folder, file, or version.
                        Run "--restore help" for more info
    --batchmode         like headless, but will exit when all available work
                        is done
    --headless          run in headless mode (without the graphical interface)
    --purge=item        purge a folder, file (including historical versions)
  Information Commands:
    --userinfo, --user-info
                        Show user and device info
    --shelved-x, --print-shelved-x
                        Show information about each shelved upload transaction
    --space             Show space usage information by category and by device
    --tree              Show the hierarchy of stored backup folders
    --fulllist          Show all folders and files stored on device
    --tree-changelog    Show a log of how the hierarchy of stored backup
                        folders has changed over time
                        Show the changelog of a given folder
  Backup Selection Manipulation Commands:
    --force             Do in/exclusion even if the path doesn't exist
    --selection, --print-selection
                        Show a list of selected and excluded backup items
    --reset-selection   Reset selection (but preserve excluded files)
                        Exclude the given file from the selection
                        Include the given file from the selection
                        Exclude the given directory from the selection
                        Include the given directory from the selection
  Maintenance Commands:
                        rebuild the SpiderOak Groups reference database (can
                        take awhile)
    --billing           print a secure web auto-login URL for billing info
                        destroy each shelved upload transaction already in
    --repair            repair a local SpiderOak Groups installation
                        retrieve metadata held by server according to policy
                         purge historical versions of a folder, file:
                        "all": purge all historical versions of all files; '
                        "hM,dN,w": hourly for last M hours, daily for last N
                        days, weekly thereafter          (also accepts
                        (m)onthly and (y)early); '     no option: hourly for
                        last 24 hours, daily for last month, then weekly
                        purge deleted items older than N days
    --vacuum            Vacuum SpiderOak Groups's local database (rebuilds
                        indexs and reclaims local disk space)
                        list parent_id's of unreferenced external block files
                        convert SpiderOak Groups's local database to use
                        external files
                        generate missing image previews for the local device
  Dangerous/Support Commands:
  Caution: Do not use these commands unless advised by SpiderOak Groups support.
  They can damage your installation if used improperly.
                        apply all transactions previously received from remote
                        devices -- (not intended for general use -- this
                        normally happens automatically)
                        purge all deleted items on the current device
    --orphans=ACTION    help, find, free orphans
                         This is similar to asking the user to send us log
                        files, in that it gives us  access to meta-information
                        about their account including file names and  space
                        usage. It does not however give us plain text access
                        to any keys or  actual data -- just metadata.
  Account Commands:
                        Rename the specified device with name NEWNAME
                        Read a json definition file and use contents to create
                        a new account (Deprecated - use --setup instead.)
    --setup=SETUP_FILE  Read a json definition file and use contents to create
                        a new account. See
                        set_up_a_new_user_from_the_commandline for more info,
                        or use '--setup=-' to prompt for setup details.
  Share Commands:
                        optional password for --create-share
    --list-shares       List shares
                        Create an xact with a new share. run 'help' for
                        Create an xact deleting a share
                        share a single file, returning a URL
  Restore Options:
                        Use this option together with --restore to restore
                        data as stored at DATE. Format: YYYY-MM-
    --simulate          Use this option together with --restore to simulate
                        the download and list the files to download