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 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: False
    • Acceptable values: None, ApiKey, Basic
    • Default: None
  • --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

  • --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
  • --token
    • Token for calling Xchange API.
    • 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

Close an open code submission

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

get

Looks up a code submission for the provided correlation ID.

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
  • --correlation-id
    • Correlation ID of the code submission.
    • Required: True
  • --token
    • Token for calling Xchange API.
    • 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 a code submission by correlation ID

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

list

Looks up all code submissions for the Connector.

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
  • --getFinished
    • Get all finished submissions.
    • Required: False
  • --getOpen
    • Get all open submissions.
    • Required: False
  • --status
    • Get all submissions for status.
    • Required: False
  • --submitter
    • Get submissions for submitter.
    • Required: False
  • --token
    • Token for calling Xchange API.
    • 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

  • --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
  • --token
    • Token for calling Xchange API.
    • 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 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

  • --additional-submitters
    • Additional points of contact for submission.
    • 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
  • --override-archive
    • Override code archive if it already exists.
    • Required: False
  • --submitter
    • Main point of contact for submission.
    • Required: True
  • --token
    • Token for calling Xchange API.
    • 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 --submitter developer@example.com
Submission that has multiple points of contact

xchange code submit --submitter developer1@example.com --additional-submitters developer2@example.com --additional-submitters developer3@example.com
Overwrite a local archive with override archive during submission

xchange code submit --override-archive --submitter developer1@example.com

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
  • --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 1 --name MyDataObject
Create a new data object with a specific reader type

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

extract

Extract the Connector interface from the Connector source.

Options

  • --check-compatibility
    • Checks to see if the new Connector is compatible with existing ones.
    • Required: False
  • --component
    • Component to extract.
    • 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-file-name
    • JSON file name that will contain the extracted Connector interface.
    • Required: False
    • Default: connector.json
  • --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 an extract of the connector

xchange extract

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

  • --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 1 --name "Project Management" --key project-management --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