Command line reference

SpecSync functions are provided through the command line tool. To use the command line tool open a command window or bash shell and run SpecSync followed by a command and appropriate options. The options and further configuration have to be specified in a SpecSync configuration file (by default specsync.json). The SpecSync command line tool is normally invoked from the folder where the configuration file of the project is saved.

Running SpecSync might require you to use different executable depending on the installation.

• dotnet specsync <COMMAND> [options] — when SpecSync is installed as a platform independent .NET tool (recommended)

• SpecSync4AzureDevOps.exe <COMMAND> [options] — when you use the .NET Framework interface through the SpecSync.AzureDevOps.Console NuGet package on Windows

• SpecSync4AzureDevOps <COMMAND> [options] — when you use the native binaries for Linux or MacOS

The available commands and the options are the same for all usage, please check the Installation & Usage page for further information about usage options. In the command line reference we generally use the .NET tool usage syntax.

Exit Codes

The command line tool terminated with a specific exit code depending on the execution result.

Exit Code	Description
0	Completed
5	Warnings (use --zeroExitCodeForWarnings to use zero exit code)
10	Failed with a synchronization error
90	Failed with an unhandled error
100	Failed with a configuration error

Examples

Invoking the following command displays SpecSync version.

dotnet specsync version

SpecSync collects anonymous error diagnostics and statistics. Neither user nor machine names, nor Azure DevOps URLs, nor test case & other work item names nor IDs are collected! This can be disabled with the --disableStats parameter.

Commands

Command	Description
init	Initializes SpecSync configuration
push	Pushes changes of the scenarios on the local repository to the Azure DevOps server. This includes linking of new scenarios to new test cases (link) and updating test cases of linked scenarios (update).
pull	Pulls changes from Azure DevOps server to the local repository. This by default includes creation of new scenarios from unlinked test cases (create) and changing scenarios of linked test cases (change).
publish-test-results	Publishes local test results to Azure DevOps server.
re-link	Re-links scenarios (local test cases) to cloned Test Cases in Azure DevOps.
help	Displays help information or help for a command.
version	Displays SpecSync version and license information.

Common command line options

The following command line options are available for all commands that require established configuration (push, pull, publish-test-results).

Option	Description	Default
<CONFIG‑FILE‑PATH>	The path of the SpecSync configuration file, absolute path or relative to the current folder, e.g. MyProject.Specs\specsync.json. Has to be specified as a last parameter.	use specsync.json from the current folder
--user <USER‑NAME>	The Azure DevOps user name or personal access token (PAT). For ServicePrincipal authentication method the application ID is specified here. Overrides remote/user setting of the configuration file. See Azure DevOps authentication options for details.	use from config file or interactive prompt
--password <PASSWORD>	The password for the Azure DevOps user. Overrides remote/password setting of the configuration file. For ServicePrincipal authentication method the client secret is specified here. See Azure DevOps authentication options for details.	use from config file or interactive prompt
--ignoreCertificateErrorsForThumbprint	The thumbprint of the server certificate that should be treated as trusted. It is recommended to install trusted certificates on the operating system instead of using this setting. See related Troubleshooting entry for details.	SSL is verified by the OS
--license <LICENSE‑FILE‑PATH>	The path to the license file; can be relative to the project folder. Overrides toolSettings/licensePath setting of the configuration file. See Licensing for details. (Default: use from config file or specsync.lic)	use from config file or specsync.lic
--disableStats	If specified, SpecSync will not collect anonymous error diagnostics and statistics. Overrides toolSettings/disableStats setting of the configuration file.	false
-v, --verbose	If specified, diagnostic information will be added to the output. Overrides toolSettings/outputLevel setting of the configuration file.	false
--log <LOG-FILE>	If specified, the output will also be saved to a log file.	no log file is written
--zeroExitCodeForWarnings	If specified, the command line tool will terminate with 0 exit code even in case of warnings.	Non-zero exit code is returned for warnings
--configOverride	Can be used to override configuration file settings. This option can be used multiple times. See Override configuration setting from command line for details.	No configuration setting overrides
--dryRun	If specified, the command will be performed, but no actual change is made either to Azure DevOps or to the local test files (feature files). This option is useful for testing the impact of an operation without making an actual change.	Normal mode

Override configuration setting from command line

With the --configOverride option any configuration file setting can be overridden even if there is no dedicated command line option for that. Using this option can be used as a backup solution to handle special cases. As an alternative to this option, you can also consider using hierarchical configuration files.

The following example overrides the user name setting in the remote configuration section (equivalent to the exposed --user option).

dotnet specsync push --configOverride "remote/user=myusername"

Most of the configuration settings changes the synchronization behavior and therefore changing them might cause a modification for many Test Cases. Therefore it is generally not recommended to use the --configOverride option. Please contact support if you are unsure about how to solve a particular synchronization requirement with SpecSync.

In order to override multiple configuration setting, the --configOverride option can be used multiple times or you can specify multiple settings separated by a semicolon (;).

The value for the --configOverride option is a configuration setter that has to follow a certain format: <path>=<value>, where

• <path> is the path of the configuration setting, e.g. remote/testSuite/name. For overriding values of list (array) settings, you can use the following path values:

  • <array-path>[<index>] -- overrides a setting at a specific index. E.g. synchronization/links[0]/tagPrefix can be used to set or override the tagPrefix setting of the first link element.

  • <array-path>[] -- adds a new element to the end of the list. E.g. synchronization/links[]/tagPrefix can be used to add a new link element and set the tagPrefix setting.

  • <array-path>[-<index>] -- overrides a setting at a specific index backwards (-1 is the last element, -2 is the one before last, etc.). E.g. synchronization/links[-1]/tagPrefix can be used to set or override the tagPrefix setting of the last link element. This setting can also be used in combination with the [] syntax. E.g. the following two setting adds a new link elements and sets two settings of it: synchronization/links[]/tagPrefix=bug;synchronization/links[-1]/relationship=tests

• <value> is the new value of the setting. The option recognizes numbers, booleans (true/false) and arbitrary strings.

Examples

Display SpecSync version:

dotnet specsync version

Get help about command line options for push command:

dotnet specsync help push

Synchronize local changes to Azure DevOps and save execution log to a file log.txt:

dotnet specsync push --log log.txt