Synchronize using the command line

You can use the sync-cmd command and Google Cloud Directory Sync (GCDS) to run synchronizations from the command line.

When to sync from the command line

When you set up or modify your configuration, you should run a manual synchronization from Configuration Manager. Doing so allows you to check the synchronized data and make sure it's in order. For details, go to Perform a manual synchronization.

After you’re done making configuration changes, you can automate your sync process using the command line. You can incorporate synchronizations into any scheduling or batch script you wish to use. Alternatively, you can use a third-party tool to automate syncs. For details, go to Schedule automatic synchronizations.

Use the command line

You run the sync-cmd command from the GCDS installation directory and enter the command on a single line. You can use the command arguments listed below to perform a range of actions, such as:

  • Apply any detected changes.
  • Read a specified file.
  • Set the logging detail level.

Tip: You can get information about the available command arguments by entering sync-cmd -h.

Command arguments & examples

Expand all  |  Collapse all & go to top

Command arguments
Argument (use either option) Description
-a
--apply
Applies any detected changes.

Note: If you don't use this argument, a sync is run as a test only and no changes are made to your Google Account. For the best results, run a test sync without this argument before running a full sync with it.

-c
--config
file-name
Specifies the XML configuration file to load.

Important: You must include a valid XML file with this argument. For details, go to Work with configuration files.

-cs
--customschemas
Excludes custom schemas.

Use this option if you don't want to sync custom schema data for users.

-d
--deletelimits
Ignores configured delete limits.
-f
--flush
Clears the cached copy of your Google Account data before running the sync.

Important: Improper use can cause performance degradation. Do not use this option unless directed to do so by support.

-g
--groups
Excludes groups.

Use this option if you want to sync users, but not groups.

-h
--help
Displays help information and exits.
-l
--loglevel
value
Overrides the default or configured log level with a specified value. Valid values (in increasing order of detail) are FATAL, ERROR, WARN, INFO, DEBUG, and TRACE.

In most cases, we recommend you set the log level to INFO.

-lic
--license
Excludes licenses.

Use this option if you don't want to sync license data for users.

-o
--oneinstance

Restricts any running synchronizations to a single instance per XML configuration file. Doing so prevents multiple instances from running inadvertently (for example, through a scheduler or cron job). The argument is only valid with the -a argument.

To troubleshoot, go to Why isn’t GCDS running a sync from the command line?

-ou
--orgunit
Excludes organizational units.
-r
--report-out
Writes reports to a specified output file, in addition to the log.
-s
--sharedcontacts
Excludes shared contacts.
-u
--users
Excludes users.

Use this option if you want to sync groups, but not users.

-v Displays short application-version information.
-V Displays detailed application-version information, but does not sync it.
Examples

Windows

Example 1: Run a simulated sync using the XML configuration file C:\Users\user\gdcs-config.xml:

sync-cmd -c C:\Users\user\gdcs-config.xml

Example 2: Run a full sync, including applying any detected changes, using the XML configuration file C:\Users\user\gdcs-config.xml:

sync-cmd -a -c C:\Users\user\gdcs-config.xml

Linux

Example 1: Run a simulated sync using the XML configuration file /path/gcds-config.xml:

sync-cmd -c /path/gcds-config.xml

Example 2: Run a full sync, including applying any detected changes, using the XML configuration file /path/gcds-config.xml:

sync-cmd -a -c /path/gcds-config.xml

Review exit code

After you run your sync or simulation from the command line, you get one of the following exit codes:

  • 0—Sync completed without any sync issues and all modifications do not exceed the configured limits.
  • 255—Simulation completed. Or, sync completed and there are sync issues, such as modifications that exceeded the configured limits or a user failed to sync.

Next step

You should monitor all synchronizations by checking for any notification messages on a regular basis. For details, go to Set your notifications.


Google, Google Workspace, and related marks and logos are trademarks of Google LLC. All other company and product names are trademarks of the companies with which they are associated.

Was this helpful?

How can we improve it?
Search
Clear search
Close search
Google apps
Main menu
799528378232709152
true
Search Help Center
true
true
true