Skip to main content

XMT CLI Reference

Introduction​

This guide covers only commands and flags relevant to XM Extensions from the eXtension Management Toolkit (XMT) command-line interface (CLI).

Review this guide for a higher-level view of XMT CLI commands, including installation instructions. For XMT Plugin commands look through this guide.

Connections​

Connections are used to enable communication between third-party service providers. Currently Extensions are limited to a single connection.

Create a Connection​

Syntax​

xmt create connection [--path=FILEPATH]

Flags​

-p, --path=FILEPATH

The FILEPATH to an Extension directory. If no FILEPATH is provided, the current working directory will be used. If the FILEPATH is not within an Extension directory, the command will fail.

-s, --scheme=SCHEME

The SCHEME is the credential type that gets set for the connection. If SCHEME is not specified, you will be prompted to provide it when creating a connection. Valid schemes are: apikey, basic, oauth2, sftp, awsSigV4, oauth2ClientJWT.

-n, --name=NAME

The NAME of the connection.

-t, --target=TARGET

The TARGET of the connection. This is the URL of the connection target.

-y, --yes

Skip all prompts and use default values. This flag should be used for automation.

Description​

Initiates a series of prompts for creating a connection to your Extension. This connection will be stored in the Extension manifest. Once the connection is created you will be prompted to add valid domains.

You will also be prompted to enable or disable this connection for each installed Plugin within your Extension directory.

Note

For a Plugin to use a connection, it must declare the credential in the Plugin config.json file like so:

"credentials": [ "myConnectionName" ]

Update a Connection​

Syntax​

xmt update connection [--path=FILEPATH]

Flags​

-p, --path=FILEPATH

The FILEPATH to an Extension directory. If no FILEPATH is provided, the current working directory will be used. If the FILEPATH is not within an Extension directory, the command will fail.

-s, --scheme=SCHEME

The SCHEME is the credential type that gets set for the connection. If SCHEME is not specified, you will be prompted to provide it when creating a connection. Supported credential types include apikey, basic, sftp, and oauth2.

Description​

Initiates a series of prompts for updating an existing connection. If no connections exist, you can create a connection with xmt create connection. This will overwrite the connection stored in the Extension manifest.

Once the connection is updated, you will be prompted to add valid domains and to enable or disable this connection for each installed Plugin within the Extension directory.

View a Connection​

Syntax​

xmt view connection [--path=FILEPATH]

Flags​

-p, --path=FILEPATH

The FILEPATH to an Extension directory. If no FILEPATH is provided, the current working directory will be used. If the FILEPATH is not within an Extension directory, the command will fail.

-o, --output=FORMAT

The output FORMAT. json and table are supported. FORMAT defaults to table.

Description​

Displays the current connection for an Extension.

Create a valid domain​

Syntax​

xmt create domain [--path=FILEPATH]

Flags​

-p, --path=FILEPATH

The FILEPATH to an Extension directory. If no FILEPATH is provided, the current working directory will be used. If the FILEPATH is not within an Extension directory, the command will fail.

-d, --domain=DOMAIN

The DOMAIN to add to the extension. This is the domain that will be allowed to use the connection.

-y, --yes

Skip all prompts and use default values. This flag should be used for automation.

Description​

Adds a valid domain in your manifest.json. This is a list of domains that your extension is allowed to communicate with, either from the user’s browser or a backend proxy service.

Extensions​

An XM Extension is a set of configurations and UX that organize and coordinate functionality that extends one or more parts of the Qualtrics platform.

Create an Extension​

Syntax​

xmt create extension [--name=NAME] [--path=FILEPATH]

Flags​

-n, --name=NAME

The NAME of the new Extension. This is used to identify the Extension. The value is added to the default translation file (assets/translations/EN.json). These values can be changed at any time by submitting modified translation files.

-p, --path=FILEPATH

The FILEPATH of where the Extension should be created. If FILEPATH is not specified, a new directory based on the provided NAME will be created in the current working directory.

-y, --yes

Skip all prompts and use default values. This flag should be used for automation use cases.

--businessScenario=SCENARIO

The business scenario of the extension. Current accepted values are:

  • integration or i: Integration scenario
  • feature_innovation or f: Feature innovation scenario


--billingTeam=TEAM

Your organization for tracking purposes.

--skipCreatePluginPrompt

Skip prompt to create plugin when extension creation is complete.

--skipInitGitRepoPrompt

Skip prompt to initialize git repository when extension creation is complete.

Description​

Provisions a new EXTENSION_ID and creates a new XM Extension on the local file system.

When creating the Extension on the local file system, a template is downloaded and applied at the FILEPATH location. The English translation file is also updated to include the provided NAME.

After creating an Extension you will be prompted to create your first Plugin.

Examples​

Running the create command like so:

xmt create extension -n "Example Extension"

Creates the following Extension structure:

example_extension
├── assets
│   ├── images
│   │   └── logo.svg
│   └── translations
│       └── EN.json
└── manifest.json

Clone an Extension​

Syntax​

xmt clone extension [--link=LINK] [--name=NAME] [--path=FILEPATH]

Flags​

-l, --link=LINK

The LINK of the submission package asset for an Extension. This is used to download an extension to your local machine to get a head start on the development process. If no link is provided, then you will prompted to select from a list of Qualtrics certified templates.

-n, --name=NAME

The NAME of the new Extension. This is used to provision the extension directory on your machine.

-p, --path=FILEPATH

The FILEPATH of where the Extension should be created. If FILEPATH is not specified, a new directory based on the provided NAME will be created in the current working directory.

Description​

Downloads a zipped extension asset and creates a new XM Extension on the local file system.

When creating the Extension on the local file system, a template is downloaded and applied at the FILEPATH location.

Qualtrics Certified Sample App Templates​

Survey Management App

Develop an Extension​

Syntax​

xmt develop extension [--path=FILEPATH]

Flags​

-p, --path=FILEPATH

The FILEPATH to an Extension directory. If no FILEPATH is provided, the current working directory will be used. If the FILEPATH is not within an Extension directory, the command will fail.

Description​

Creates a development session for prerelease Extensions that watches for updates in the Extension directory. When changes are detected, the Extension will be validated and updated in the cloud.

It is recommended to use xmt develop extension in conjunction with an automated build script such as webpack to rebuild Plugins when their respective source code is updated. Most Plugin templates include automatic npm build scripts inside the package.json file.

When developing Plugins that have a UI, xmt develop can signal the browser to automatically refresh the page when changes are detected. Automatic refreshing will only happen after checking the refresh when change detected checkbox in the prerelease overlay. If you get an error after enabling auto-refresh let us know via the Feedback & Support button.

To ignore files or folders during development, ensure that an .xmtignore file exists in your Extension root directory.

Concurrent Developing Sessions

Only one developing session is allowed for an Extension version at a time.

You can facilitate multiple concurrent development sessions on the same Extension by having each developer change the prerelease suffix in their copy of the Extension version in the manifest.json file to be unique. For example, 0.0.1-prerelease could be changed to 0.0.1-prerelease2.

Only one xmt develop process may be running on a machine at a time.

Validate an Extension​

Syntax​

xmt validate extension [--path=FILEPATH] [--tidy]

Flags​

-p, --path=FILEPATH

The FILEPATH to an Extension directory. If no FILEPATH is provided, the current working directory will be used. If the FILEPATH is not within an Extension directory, the command will fail.

--tidy

Attempt to automatically apply upgrade rules to the Extension.

Description​

Checks if the Extension is configured correctly for use on the XM Platform. It will package the Extension as if it were submitting it, and returns validation results. If it is not valid, it will return a list of errors encountered during validation.

Package an Extension​

Syntax​

xmt package extension [--path=FILEPATH]

Flags​

-p, --path=FILEPATH

The FILEPATH to an Extension directory. If no FILEPATH is provided, the current working directory will be used. If the FILEPATH is not within an Extension directory, the command will fail.

Description​

This packages the Extension into the format used during submission. For large Extensions, packaging the Extension and inspecting its contents may be helpful in identifying resources that may be causing the submissions size threshold (32MB) to be exceeded.

Submit an Extension​

Syntax​

xmt submit extension [--report] [--path=FILENAME]

Flags​

-r, --report

Indicates that the XMT CLI should wait for the submission to complete and print the submission report when available. This command times out after 3 minutes.

In the event of a timeout, you can get also view the report of the submission with xmt view submission.

Note

Since September 2021, the --report flag is set by default. The XMT CLI waits for the submission to complete unless the --report flag is set to false explicitly, with --report=false.

-p, --path=FILEPATH

The FILEPATH to an Extension directory. If no FILEPATH is provided, the current working directory will be used. If the FILEPATH is not within an Extension directory, the command will fail.

--release

The --release flag is used to release your prerelease extension for wider consumption without a prerelease tag. This will update the extension version stored in the manifest.json.


Description​

Submits an XM Extension to Qualtrics. This command will package the Extension and send it to the XM platform for review.

Files from the Extension directory can be ignored via the .xmtignore file, which is included automagically in all new Extensions.

Prerelease versions cannot be submitted. See for information here.

List Extension Versions​

Syntax​

xmt list versions [--extension=EXTENSION_ID | --path=FILEPATH] [--limit=LIMIT] [--output=FORMAT]

Flags​

-e, --extension=EXTENSION_ID

EXTENSION_ID of the Extension to share. If run within an Extension root directory, the default value is the id in the manifest.json.

-l, --limit=LIMIT

The maximum number of Extension versions to return. LIMIT defaults to 10.

-o, --output=FORMAT

The output FORMAT. json and table are supported. FORMAT defaults to table.

-p, --path=FILEPATH

The FILEPATH to an Extension directory. If no FILEPATH is provided, the current working directory will be used. If the FILEPATH is not within an Extension directory, the command will fail.

Description​

Displays a list of Extension versions.

Examples​

$ xmt list versions
+---------+--------------------------+----------------------------+-----------+---------+
| VERSION |         SUBMITTED AT     |         SUBMITTED BY       | PUBLISHED | PREVIEW |
+---------+--------------------------+----------------------------+-----------+---------+
| 0.0.3   | 2020-01-03 22:10:00 UTC  | developerOne@qualtrics.com |           | true    |
| 0.0.2   | 2020-01-02 00:08:00 UTC  | developerTwo@qualtrics.com | true      |         |
| 0.0.1   | 2020-01-01 10:00:00 UTC  | developerOne@qualtrics.com |           |         |
+---------+--------------------------+----------------------------+-----------+---------+

Roles​

A role identifies a set of permissions available to a user within an Extension team.

View Roles​

Syntax​

xmt view roles

Description​

Display all roles and their permissions.

Examples​

$ xmt view roles
+---------------------+-------+-------+-----------+
|     PERMISSION      | OWNER | ADMIN | DEVELOPER |
+---------------------+-------+-------+-----------+
| View extension      | true  | true  | true      |
| Submit extension    | true  | true  | true      |
| Share extension     | true  | true  | false     |
| Invite members      | true  | true  | false     |
| Remove members      | true  | true  | false     |
| Update member roles | true  | true  | false     |
| Change owner        | true  | false | false     |
+---------------------+-------+-------+-----------+

Shares​

A Share provides the ability for an organization to gain access to a submitted Extension. For example, if a user created an Extension for generating cat memes, the user can provide organizations foo and bar access to this Extension by creating a Share. Once a share is initiated, an administrator from foo and bar would need to install the Extension to make it available for use.

Create a Share​

Syntax​

xmt create share --organization=ORGANIZATION [--extension=EXTENSION_ID | --path=FILEPATH] [--version=VERSION] [--preview]

Flags​

-e, --extension=EXTENSION_ID

EXTENSION_ID of the Extension to share. If run within an Extension root directory, the default value is id in the manifest.json.

-o, --organization=ORGANIZATION

ORGANIZATION to share the Extension with.

-p, --path=FILEPATH

The FILEPATH to an Extension directory. If no FILEPATH is provided, the current working directory will be used. If the FILEPATH is not within an Extension directory, the command will fail.

-P, --preview

Automatically share the latest preview version of the Extension with the target organization. If omitted, the share will not auto-update to the preview version. A preview version must be published before using this flag.

-v, --version=VERSION

VERSION of the Extension to share. If run within an Extension root directory, the default value is version in the manifest.json.

Description​

Submits a request to allow the provided ORGANIZATION an option to install the Extension. Only organizations for which a team member is an administrator are accepted. New shares will auto-update to share the latest submitted extension version by default unless the version or preview flag is provided.

View Shares for an Extension​

Syntax​

xmt list shares [--extension=EXTENSION_ID | --path=FILEPATH]

Flags​

-e, --extension=EXTENSION_ID

EXTENSION_ID of the Extension share. If run within an Extension root directory, the default value is id in the manifest.json.

-p, --path=FILEPATH

The FILEPATH to an Extension directory. If no FILEPATH is provided, the current working directory will be used. If the FILEPATH is not within an Extension directory, the command will fail.

Description​

Displays a list of Extension shares

Revoke a Share​

Syntax​

xmt delete share --organization=ORGANIZATION [--extension=EXTENSION_ID | --path=FILEPATH]

Flags​

-e, --extension=EXTENSION_ID

EXTENSION_ID of the Extension to share. If run within an Extension root directory, the default value is id in the manifest.json.

-o, --organization=ORGANIZATION

ORGANIZATION to remove the share from.

-p, --path=FILEPATH

The FILEPATH to an Extension directory. If no FILEPATH is provided, the current working directory will be used. If the FILEPATH is not within an Extension directory, the command will fail.

Description​

Revokes an Extension shared with the ORGANIZATION. This will prevent future installations of the Extension for the organization. However, this will not remove any existing installations.

Submissions​

After you have submitted your Extension to the XM Platform for review, you may want to look up past submissions to see their status or read the submission report.

List Extension Submissions​

xmt list submissions [--extension=EXTENSION_ID | --path=FILEPATH]

Flags​

-e, --extension=EXTENSION_ID

EXTENSION_ID of the Extension to list submissions for. If run within an Extension root directory, the default value is the id in the manifest.json.

-p, --path=FILEPATH

The FILEPATH to an Extension directory. If no FILEPATH is provided, the current working directory will be used. If the FILEPATH is not within an Extension directory, the command will fail.

Description​

Displays a list of Extension submissions.

View an Extension Submission with Submission Report​

xmt view submission [--submission=SUBMISSION_ID] [--extension=EXTENSION_ID | --path=FILEPATH]

Flags​

-s, --submission=SUBMISSION_ID

SUBMISSION_ID of the submission you want to show. If no value is specified, the default value is the most recent submission.

-e, --extension=EXTENSION_ID

EXTENSION_ID of the Extension. If run within an Extension root directory, the default value is the id in the manifest.json.

-p, --path=FILEPATH

The FILEPATH to an Extension directory. If no FILEPATH is provided, the current working directory will be used. If the FILEPATH is not within an Extension directory, the command will fail.

-o, --output=FORMAT

The output FORMAT. json and table are supported. FORMAT defaults to table.

Description​

Displays an Extension submission including the submission report.

Appendix​

xmtignore File​

To ignore files or folders in your submission, include a .xmtignore file in the Extension or Plugin root directory. This is helpful to ensure development files (such as node_modules) are not included in your submission or developing session.

The behavior of .xmtignore is similar to .gitignore or .dockerignore, in that each line represents a pattern to match against files or directories that should be ignored. The root context is considered to be the working directory.

Below is an example .xmtignore file:

# My Comment
node_modules
*.env

This file results in the following build behavior:

RuleBehavior
# My CommentIgnored
node_modulesExclude files and directories named node_modules
*.envExclude files with the .env extension

Teams​

A team is composed of one or more developers who collaborate on an Extension. A team is automatically created alongside an Extension, appointing the creator as the owner. Each team consists of at least one owner. More information about the roles available within a team can be found under Roles.

Invite to Team​

Syntax​

xmt create invite --role=ROLE --user=USER_EMAIL [--extension=EXTENSION_ID | --path=FILEPATH | --team=TEAM_ID] [--language=LANGUAGE_CODE]

Flags​

-e, --extension=EXTENSION_ID

EXTENSION_ID to invite the user to. If run within an Extension root directory, the default value is id in the manifest.json.

-l, --language=LANGUAGE_CODE

Language code for the invitation email. A list of supported language codes can be found here.

-p, --path=FILEPATH

The FILEPATH to an Extension directory. If no FILEPATH is provided, the current working directory will be used. If the FILEPATH is not within an Extension directory, the command will fail.

-r, --role=ROLE

Role to apply to the invited user.

-t, --team=TEAM_ID

TEAM_ID to invite the user to.

-u, --user=USER_EMAIL

The recipients email address. The recipient must use USER_EMAIL as their username to accept the invitation.

Description​

Sends an invitation for a user to join an Extension team. Invitations are emailed to specified user. Upon accepting, if the user doesn't have an account they are prompted to create and verify one prior to joining the team.

View Team​

Syntax​

xmt view team [--extension=EXTENSION_ID | --path=FILEPATH | --team=TEAM_ID]

Flags​

-e, --extension=EXTENSION_ID

EXTENSION_ID of the team. If run within an Extension root directory, the default value is id in the manifest.json.

-p, --path=FILEPATH

The FILEPATH to an Extension directory. If no FILEPATH is provided, the current working directory will be used. If the FILEPATH is not within an Extension directory, the command will fail.

-t, --team=TEAM_ID

TEAM_ID for the team.

Description​

Displays details about the users and their corresponding roles on the team.

Examples​

$ xmt view team
+-----------------------------+------------+-----------+-----------+
|            USER             | FIRST NAME | LAST NAME |   ROLE    |
+-----------------------------+------------+-----------+-----------+
| admin@qualtrics.com         | Team       | Admin     | Admin     |
| owner@qualtrics.com         | Team       | Owner     | Owner     |
| developer@qualtrics.com     | Team       | Developer | Developer |
+-----------------------------+------------+-----------+-----------+

Update Team User Role​

Syntax​

xmt update team-user --username=USERNAME --role=ROLE [--extension=EXTENSION_ID | --path=FILEPATH | --team=TEAM_ID]

Flags​

-e, --extension=EXTENSION_ID

EXTENSION_ID associated with the team. If run within an Extension root directory, the default value is id in the manifest.json.

-p, --path=FILEPATH

The FILEPATH to an Extension directory. If no FILEPATH is provided, the current working directory will be used. If the FILEPATH is not within an Extension directory, the command will fail.

-r, --role=ROLE

New role to apply to the user.

-t, --team=TEAM_ID

TEAM_ID for the team.

-u, --username=USERNAME

Username of the user to update on the team.

Description​

Update a user's role on a team. XMT does not support changing team ownership. That action must be done in the developer portal.

Remove User From Team​

Syntax​

xmt remove team-user --username=USERNAME [--extension=EXTENSION_ID | --path=FILEPATH | --team=TEAM_ID]

Flags​

-e, --extension=EXTENSION_ID

EXTENSION_ID associated with the team. If run within an Extension root directory, the default value is id in the manifest.json.

-p, --path=FILEPATH

The FILEPATH to an Extension directory. If no FILEPATH is provided, the current working directory will be used. If the FILEPATH is not within an Extension directory, the command will fail.

-t, --team=TEAM_ID

TEAM_ID for the team.

-u, --username=USERNAME

Username of the user to remove from the team.

Description​

Disassociates a user from an Extension team. This does not delete the user account.


Tail XM Functions Logs​

Syntax​

xmt create logdrain --local --organizations=ORGANIZATION [--extension=EXTENSION_ID]

Flags​

-l, --local

Start a local session to temporarily tail logs.

-o, --organizations=ORGANIZATION

ORGANIZATION to tail logs from. XM Functions triggered for this organization will have all logs also sent to terminal. If the local flag is provided, only a single organization can be specified.

-e, --extension=EXTENSION_ID

EXTENSION_ID associated with the team. If run within an Extension root directory, the default value is id in the manifest.json.

Description​

Starts a 15 minute log tailing session for the provided organization. Logs produced from XM Functions during this session will also be sent to your terminal automatically.

Create a logdrain​

Syntax​

xmt create logdrain --url=URL --organizations=ORGANIZATION [--extension=EXTENSION_ID]

Flags​

-u, --url

The HTTP/HTTPS Event Collector URL generated from a Log provider. This URL should respond to POST requests with each line of the request body containing a syslog formatted log. Basic authentication can be provided in the URL itself.

-o, --organizations=ORGANIZATION

ORGANIZATION(s) to tail logs from. XM Functions triggered for this organization will have all logs also sent to terminal. If providing multiple organizations, provide a comma separated list of brands (e.g. --organizations=brand1,brand2).

-e, --extension=EXTENSION_ID

EXTENSION_ID associated with the team. If run within an Extension root directory, the default value is id in the manifest.json.

Description​

Create a logdrain for your XM Function. Any logs produced by your XM Function for the provided organizations will be exported to the given URL. For help generating the URL, please consult your logging providers documentation to create an HTTP/HTTPS event collector (HEC).

View configured logdrains​

Syntax​

xmt view logdrains [--extension=EXTENSION_ID]

Flags​

-e, --extension=EXTENSION_ID

EXTENSION_ID associated with the team. If run within an Extension root directory, the default value is id in the manifest.json.

Description​

Lists the logdrains created for this Extension through xmt create logdrain.