Skip to content

Xchange Connector CLI Usage

The version of the Xchange Connector CLI you are using may depend on a specific version of the Xchange Connector SDK library in order to support a specific command or option. Please check the version of the Xchange Connector SDK library in use by your connector and the command you wish to use.

Verifying SDK and CLI Versions

To verify the versions you are using of the Xchange Connector SDK and the Xchange Connector CLI, navigate to the "Connector" directory in the root of your Connector code repository and run:

xchange --version

The Xchange Connector CLI output should echo back with the in-use versions for each component:

CLI Version: <version>
SDK Version: <version>

If you encounter issues between the installed CLI version and your connector, see the troubleshooting guide for more information.

Below is a listing and detailed overview of each available command broken down by category.

Command List

root

The root command for the Xchange Connector CLI.

Options

  • --help (aliases: -h, /h, -?, /?)
    • Show help and usage information
    • Required: False
  • --verbosity (aliases: -v)
    • Controls the verbosity of logging.
    • Required: False
    • Acceptable values: Verbose, Debug, Information, Warning, Error, Fatal
    • Default: Information
  • --version
    • Show version information
    • Required: False

action

Manage action handlers in the Connector source.

Options

  • --help (aliases: -h, /h, -?, /?)
    • Show help and usage information
    • Required: False
  • --verbosity (aliases: -v)
    • Controls the verbosity of logging.
    • Required: False
    • Acceptable values: Verbose, Debug, Information, Warning, Error, Fatal
    • Default: Information

new

Creates a new action handler.

Options

  • --connector-path
    • The path of the folder in which the connector project lives. Defaults to the current working directory if not set.
    • Required: False
    • Default: current working directory
  • --module-id
    • The module id of the module to which a new action handler will be added. Must exist in the connector.json file.
    • Required: True
  • --name (aliases: -n, --action-name)
    • The name of the action to create an action handler for. PascalCase is preferred.
    • Required: True
  • --object-name (aliases: -o)
    • The name of the data object to create an action handler for. PascalCase is preferred.
    • Required: True
  • --help (aliases: -h, /h, -?, /?)
    • Show help and usage information
    • Required: False
  • --verbosity (aliases: -v)
    • Controls the verbosity of logging.
    • Required: False
    • Acceptable values: Verbose, Debug, Information, Warning, Error, Fatal
    • Default: Information

Examples

Create a new action

xchange action new --module-id app-1 --object-name MyDataObject --name MyAction

client

Manage clients for the Connector source.

Options

  • --help (aliases: -h, /h, -?, /?)
    • Show help and usage information
    • Required: False
  • --verbosity (aliases: -v)
    • Controls the verbosity of logging.
    • Required: False
    • Acceptable values: Verbose, Debug, Information, Warning, Error, Fatal
    • Default: Information

new

Creates a client for interfacing with application.

Options

  • --auth-type (aliases: --auth)
    • Type of authentication to use.
    • Required: True
    • Acceptable values: Custom, ApiKey, Basic, OAuth2CodeFlow, OAuth2ClientCredentials, OAuth2Password
  • --connector-path
    • The path of the folder in which the connector project lives. Defaults to the current working directory if not set.
    • Required: False
    • Default: current working directory
  • --type (aliases: -t)
    • Type of client to create. HTTP is used by default.
    • Required: False
    • Acceptable values: Http
    • Default: Http
  • --help (aliases: -h, /h, -?, /?)
    • Show help and usage information
    • Required: False
  • --verbosity (aliases: -v)
    • Controls the verbosity of logging.
    • Required: False
    • Acceptable values: Verbose, Debug, Information, Warning, Error, Fatal
    • Default: Information

Examples

Create a new HTTP typed client

xchange client new --type Http --auth-type ApiKey

code

Manage code submissions for the Connector source.

Options

  • --help (aliases: -h, /h, -?, /?)
    • Show help and usage information
    • Required: False
  • --verbosity (aliases: -v)
    • Controls the verbosity of logging.
    • Required: False
    • Acceptable values: Verbose, Debug, Information, Warning, Error, Fatal
    • Default: Information

close

Closes the open code submission for the provided correlation ID.

Options

  • --api-key (aliases: --token)
    • Token for calling Xchange API.
    • Required: False
  • --connector-path
    • The path of the folder in which the connector project lives. Defaults to the current working directory if not set.
    • Required: False
    • Default: current working directory
  • --correlation-id
    • Correlation ID of the code submission.
    • Required: True
  • --help (aliases: -h, /h, -?, /?)
    • Show help and usage information
    • Required: False
  • --verbosity (aliases: -v)
    • Controls the verbosity of logging.
    • Required: False
    • Acceptable values: Verbose, Debug, Information, Warning, Error, Fatal
    • Default: Information

Examples

Close an open code submission

xchange code close --correlation-id *correlation-id*

feedback

Retrieve an archive containing feedback of the code submission for the provided correlation ID.

Options

  • --api-key (aliases: --token)
    • Token for calling Xchange API.
    • Required: False
  • --connector-path
    • The path of the folder in which the connector project lives. Defaults to the current working directory if not set.
    • Required: False
    • Default: current working directory
  • --correlation-id
    • Correlation ID of the code submission.
    • Required: True
  • --output
    • Output directory for the feedback file.
    • Required: False
  • --help (aliases: -h, /h, -?, /?)
    • Show help and usage information
    • Required: False
  • --verbosity (aliases: -v)
    • Controls the verbosity of logging.
    • Required: False
    • Acceptable values: Verbose, Debug, Information, Warning, Error, Fatal
    • Default: Information

Examples

Retrieve an archive containing feedback for the given submission

xchange code feedback --correlation-id *correlation-id*

get

Looks up a code submission for the provided correlation ID.

Options

  • --api-key (aliases: --token)
    • Token for calling Xchange API.
    • Required: False
  • --connector-path
    • The path of the folder in which the connector project lives. Defaults to the current working directory if not set.
    • Required: False
    • Default: current working directory
  • --correlation-id
    • Correlation ID of the code submission.
    • Required: True
  • --help (aliases: -h, /h, -?, /?)
    • Show help and usage information
    • Required: False
  • --verbosity (aliases: -v)
    • Controls the verbosity of logging.
    • Required: False
    • Acceptable values: Verbose, Debug, Information, Warning, Error, Fatal
    • Default: Information

Examples

Get a code submission by correlation ID

xchange code get --correlation-id *correlation-id*

list

Looks up all code submissions for the Connector.

Options

  • --api-key (aliases: --token)
    • Token for calling Xchange API.
    • Required: False
  • --connector-path
    • The path of the folder in which the connector project lives. Defaults to the current working directory if not set.
    • Required: False
    • Default: current working directory
  • --getFinished
    • Get all finished submissions.
    • Required: False
  • --getOpen
    • Get all open submissions.
    • Required: False
  • --limit
    • Amount of submissions to return.
    • Required: False
    • Default: 10
  • --status
    • Get all submissions for status.
    • Required: False
  • --submitter
    • Get submissions for submitter.
    • Required: False
  • --help (aliases: -h, /h, -?, /?)
    • Show help and usage information
    • Required: False
  • --verbosity (aliases: -v)
    • Controls the verbosity of logging.
    • Required: False
    • Acceptable values: Verbose, Debug, Information, Warning, Error, Fatal
    • Default: Information

Examples

Get all code submissions

xchange code list
Get all code submissions for a submitter

xchange code list --submitter developer@example.com
Get all code submissions that are finished

xchange code list --getFinished

status

Looks up a code submission status for the provided correlation ID.

Options

  • --api-key (aliases: --token)
    • Token for calling Xchange API.
    • Required: False
  • --connector-path
    • The path of the folder in which the connector project lives. Defaults to the current working directory if not set.
    • Required: False
    • Default: current working directory
  • --correlation-id
    • Correlation ID of the code submission.
    • Required: True
  • --help (aliases: -h, /h, -?, /?)
    • Show help and usage information
    • Required: False
  • --verbosity (aliases: -v)
    • Controls the verbosity of logging.
    • Required: False
    • Acceptable values: Verbose, Debug, Information, Warning, Error, Fatal
    • Default: Information

Examples

Get a code submission status by correlation ID

xchange code get status --correlation-id *correlation-id*

submit

Archives the connector code and creates a submission for approval.

Options

  • --allow-breaking-changes
    • Allow breaking changes in the connector.json when sending to Xchange
    • Required: False
  • --api-key (aliases: --token)
    • Token for calling Xchange API.
    • Required: False
  • --connector-path
    • The path of the folder in which the connector project lives. Defaults to the current working directory if not set.
    • Required: False
    • Default: current working directory
  • --draft
    • Sets the submission as a draft to allow for early feedback on progress of the Connector.
    • Required: False
  • --dry-run
    • Test and validate your submission before sending to Xchange.
    • Required: False
  • --override-archive
    • Override code archive if it already exists.
    • Required: False
  • --submitter
    • The person who is submitting the code. Defaults to the email address of the logged in user. Not needed if you are signed in.
    • Required: False
  • --help (aliases: -h, /h, -?, /?)
    • Show help and usage information
    • Required: False
  • --verbosity (aliases: -v)
    • Controls the verbosity of logging.
    • Required: False
    • Acceptable values: Verbose, Debug, Information, Warning, Error, Fatal
    • Default: Information

Examples

Submit Connector code to Xchange for approval

xchange code submit
Submit Connector code to Xchange for approval with API key

xchange code submit --api-key {API key} --submitter {email}
Overwrite a local archive with override archive during submission

xchange code submit --override-archive
Create a submission as a draft that indicates to Xchange you would like feedback on the direction of the Connector code base

xchange code submit --draft
Test and validate your submission before sending to Xchange

xchange code submit --dry-run
Submit Connector code that may contain breaking changes to Xchange for approval

xchange code submit --allow-breaking-changes

connector

Manage the Connector source.

Options

  • --help (aliases: -h, /h, -?, /?)
    • Show help and usage information
    • Required: False
  • --verbosity (aliases: -v)
    • Controls the verbosity of logging.
    • Required: False
    • Acceptable values: Verbose, Debug, Information, Warning, Error, Fatal
    • Default: Information

new

Create a new Connector project

Options

  • --allow-prerelease
    • Allows usage of pre-release versions of the Connector SDK packages if one is available greater than latest stable.
    • Required: False
    • Default: False
  • --connector-path
    • The path of the folder in which the connector project lives. Defaults to the current working directory if not set.
    • Required: False
    • Default: current working directory
  • --description (aliases: -d)
    • Description of Connector.
    • Required: False
  • --name (aliases: -n)
    • Name of Connector.
    • Required: True
  • --help (aliases: -h, /h, -?, /?)
    • Show help and usage information
    • Required: False
  • --verbosity (aliases: -v)
    • Controls the verbosity of logging.
    • Required: False
    • Acceptable values: Verbose, Debug, Information, Warning, Error, Fatal
    • Default: Information

Examples

Create a new Connector

xchange connector new --name MyConnector --description "My new connector"

data-object

Manage data objects in the Connector source.

Options

  • --help (aliases: -h, /h, -?, /?)
    • Show help and usage information
    • Required: False
  • --verbosity (aliases: -v)
    • Controls the verbosity of logging.
    • Required: False
    • Acceptable values: Verbose, Debug, Information, Warning, Error, Fatal
    • Default: Information

new

Creates a new data object

Options

  • --connector-path
    • The path of the folder in which the connector project lives. Defaults to the current working directory if not set.
    • Required: False
    • Default: current working directory
  • --module-id
    • The module id of the module to which a new data reader will be added. Must exist in the connector.json file.
    • Required: True
  • --name (aliases: -n, --object-name)
    • The name of the data object to create data reader for. PascalCase is preferred.
    • Required: True
  • --no-pagination
    • Skips pagination from the generated data reader.
    • Required: False
    • Default: False
  • --reader-type (aliases: -t)
    • The name of the data reader for the Data Object. (Options are: full, incremental)
    • Required: False
    • Acceptable values: Full, Incremental
    • Default: Full
  • --help (aliases: -h, /h, -?, /?)
    • Show help and usage information
    • Required: False
  • --verbosity (aliases: -v)
    • Controls the verbosity of logging.
    • Required: False
    • Acceptable values: Verbose, Debug, Information, Warning, Error, Fatal
    • Default: Information

Examples

Create a new data object

xchange data-object new --module-id app-1 --name MyDataObject
Create a new data object with a specific reader type

xchange data-object new --module-id app-1 --name MyDataObject --reader-type Incremental

extract

Extract the Connector metadata from the Connector source.

Options

  • --allow-breaking-changes
    • Allow breaking changes during extraction.
    • Required: False
  • --connector-path
    • The path of the folder in which the connector project lives. Defaults to the current working directory if not set.
    • Required: False
    • Default: current working directory
  • --filename (aliases: --file-name)
    • Filename with extension of the Connector DLL to extract from in relation to the path.
    • Required: False
  • --output-filename (aliases: --output-file-name)
    • JSON file name that will contain the extracted Connector metadata.
    • Required: False
    • Default: connector.json
  • --validate-only
    • Only check if Connector's metadata is valid
    • Required: False
  • --help (aliases: -h, /h, -?, /?)
    • Show help and usage information
    • Required: False
  • --verbosity (aliases: -v)
    • Controls the verbosity of logging.
    • Required: False
    • Acceptable values: Verbose, Debug, Information, Warning, Error, Fatal
    • Default: Information

Examples

Create a JSON representation of the Connector

xchange extract
Only validate that the Connector is valid according to Xchange rule sets

xchange extract --validate-only
Do not fail an extraction if breaking changes are found

xchange extract --allow-breaking-changes

login

Log into Xchange platform using TrimbleID.

Options

  • --help (aliases: -h, /h, -?, /?)
    • Show help and usage information
    • Required: False
  • --verbosity (aliases: -v)
    • Controls the verbosity of logging.
    • Required: False
    • Acceptable values: Verbose, Debug, Information, Warning, Error, Fatal
    • Default: Information

Examples

Log into Xchange

xchange login

logout

Logout of the Xchange platform.

Options

  • --help (aliases: -h, /h, -?, /?)
    • Show help and usage information
    • Required: False
  • --verbosity (aliases: -v)
    • Controls the verbosity of logging.
    • Required: False
    • Acceptable values: Verbose, Debug, Information, Warning, Error, Fatal
    • Default: Information

Examples

Log out of Xchange

xchange logout

module

Manage modules in the Connector source.

Options

  • --help (aliases: -h, /h, -?, /?)
    • Show help and usage information
    • Required: False
  • --verbosity (aliases: -v)
    • Controls the verbosity of logging.
    • Required: False
    • Acceptable values: Verbose, Debug, Information, Warning, Error, Fatal
    • Default: Information

new

Creates a new module in the referenced connector.

Options

  • --add-health-checks
    • Add health check endpoints to the module.
    • Required: False
    • Default: False
  • --connector-path
    • The path of the folder in which the connector project lives. Defaults to the current working directory if not set.
    • Required: False
    • Default: current working directory
  • --description (aliases: -d)
    • A description of what the module is for.
    • Required: False
  • --id (aliases: --module-id)
    • The id of the module to which a module will be created. Must not already exist in the settings.json file.
    • Required: True
  • --key (aliases: --url-part, --module-key)
    • The key defining the module in our platform. Must not already exist in the settings.json
    • Required: True
  • --name (aliases: -n)
    • Name of the module to add. (e.g. "Project Management")
    • Required: True
  • --version
    • The version of the module.
    • Required: True
  • --help (aliases: -h, /h, -?, /?)
    • Show help and usage information
    • Required: False
  • --verbosity (aliases: -v)
    • Controls the verbosity of logging.
    • Required: False
    • Acceptable values: Verbose, Debug, Information, Warning, Error, Fatal
    • Default: Information

Examples

Create a new module

xchange module new --id app-1 --name App --key app --version 1

test

Manage Connector testing.

Options

  • --help (aliases: -h, /h, -?, /?)
    • Show help and usage information
    • Required: False
  • --verbosity (aliases: -v)
    • Controls the verbosity of logging.
    • Required: False
    • Acceptable values: Verbose, Debug, Information, Warning, Error, Fatal
    • Default: Information

init

Initializes test data so that a developer can easily set the flow data they want to use in test.

Options

  • --connector-path
    • The path of the folder in which the connector project lives. Defaults to the current working directory if not set.
    • Required: False
    • Default: current working directory
  • --filename (aliases: --file-name)
    • Filename with extension of the Connector DLL to extract from in relation to the path.
    • Required: False
  • --help (aliases: -h, /h, -?, /?)
    • Show help and usage information
    • Required: False
  • --verbosity (aliases: -v)
    • Controls the verbosity of logging.
    • Required: False
    • Acceptable values: Verbose, Debug, Information, Warning, Error, Fatal
    • Default: Information

Examples

Initialize test configuration for Connector

xchange test init

reset

Resets local testing databases.

Options

  • --configuration (aliases: --config, -c)
    • The Connector project configuration. Default value is 'Debug'.
    • Required: False
    • Default: Debug
  • --connector-path
    • The path of the folder in which the connector project lives. Defaults to the current working directory if not set.
    • Required: False
    • Default: current working directory
  • --help (aliases: -h, /h, -?, /?)
    • Show help and usage information
    • Required: False
  • --verbosity (aliases: -v)
    • Controls the verbosity of logging.
    • Required: False
    • Acceptable values: Verbose, Debug, Information, Warning, Error, Fatal
    • Default: Information

Examples

Reset local testing databases

xchange test reset
Reset local testing databases with a specific configuration

xchange test reset --configuration Release