Skip to main content

XM Solution CLI Command Reference

Introduction​

This reference guide documents every command and flag available in the XM Solutions CLI.

If you would like to join the early access program for XM Solution Plugins, then please let us know by taking this survey.

Not generally available

This feature is in Early Access and is not yet generally available. Functionality, APIs, and documentation may change before general availability.

It's recommended that you go through the Quick Start Guide first to set up and familiarize yourself with the system.

The XM Solutions CLI helps you author XM Solutions from the command line.

Installing the Solution CLI globally is recommended for both Mac/Linux and Windows users. To do so, use npm install and npm install --location=global @qualtrics/solution-cli.

Installing the Solution CLI globally enables the Solution CLI to run across the file directories without needing to install the CLI again. The Solution CLI will auto upgrade when new version is introduced.

Windows users

For Windows users, follow these steps to add Solution CLI to the environment path:

  1. In the System Properties window, click on the Environment Variables... button.

  2. In the Environment Variables window, under User variables or System variables, find the Path variable,

 select it, and click on `Edit...`.

  1. In the Edit environment variable window, click on New and paste the path to your global npm bin directory (C:\Users\<username>\AppData\Roaming\npm\bin) which is where the Solution CLI is installed.

  2. Click OK to save the changes and close all the open windows.

  3. Restart the Command Prompt or PowerShell window for the changes to take effect.

Mac/Linux users may install the CLI locally under the current working directory using npm install.

By default, this will add the requisite files to your project/local node_modules directory and will require that you prefix the CLI commands with npx.

For example, the solution init command would be run npx solution init.

Authentication​

To use the XM Solutions CLI, you first need to authenticate by initializing with the init command. This command runs a 'Getting Started' workflow to authorize XMT access to the Developer Platform.

Syntax​

solution init [-c]

Description​

After running this command, you should see the following command line prompt:

You must log in to continue. Would you like to log in (y/n)? [y]:

Press enter to log in. This opens a login page in your default browser. Be sure to log in with the same credentials you used to log in to the XMT CLI.

Flags​

-c, --console-only

Prevents the XM Solutions CLI from launching a browser when authenticating.

Global Flags​

--config filepath

Specify a user configuration file located at filepath. If not specified, the CLI will create and use one under your home directory at HOME/.config/solution/config.json.

Updating The XM Solutions CLI​

The CLI updates itself before executing commands, but you can also manually initiate an update to the latest version with this command.

Syntax​

solution update

Description​

Updates XM Solutions CLI executable to the latest version.

Adding Languages​

You may find yourself authoring an XM Solution that needs to be translated into languages other than your own. In this case, you need to add a language to your XM Solution with the add-lang command. A full guide on translating XM Solutions can be found here.

Syntax​

solution add-lang { language_code [language_codes...] [-p filepath] | -l }

Description​

This command adds a language to the XM Solution.

Flags​

language_code

This (and language_codes if you're adding multiple) should be replaced with either the language code (i.e., ur or "ur") or the full language string (i.e., "Urdu").

These inputs are case-insensitive and should be space separated if you're entering multiple languages. The complete list of languages and codes can be seen by running solution add-lang -l.

-p filepath, --path filepath

Specifies a file path to the plugin directory. Only used if the current working directory is not a valid plugin directory. Defaults to the current working directory.

-l, --list

This flag lists all available languages with their corresponding codes.

Extracting Translations​

Syntax​

solution translation-extract [-p filepath]

Description​

Extracts translatable strings from each resource and adds them to the public/translations directory. A full guide on translating XM Solutions can be found here.

Flags​

-p filepath, --path filepath

Specifies a file path to the plugin directory. Only used if the current working directory is not a valid plugin directory. Defaults to the current working directory.

Retrieving Translations​

Syntax​

solution translation-update {namespace [-p filepath]}

Description​

Retrieves non-English translated file content from the translations repository. The content will be stored in languages files in the translations folder of the plugin. The namespace argument is equivalent to the file name in the translations repository.

Flags​

-p filepath, --path filepath

Specifies a file path to the plugin directory. Use when the current working directory is not a valid plugin directory. Defaults to the current working directory.

Building an XM Solution for Submission​

This command modifies files in the plugin directory that require auto-generation. A successful build prepares the XM Solution for submission with the xmt submit extension command.

Syntax​

solution build [-p filepath]

Description​

This command will turn your source files into files that can be used in the Qualtrics product. Once these files are built, you're ready to submit your extension. Check out the documentation on submitting extensions here.

Flags​

-p filepath, --path filepath

Specifies a file path to the plugin directory. Only used if the current working directory is not a valid plugin directory. Defaults to the current working directory.

Generating an auto-completion script​

Syntax​

solution completion shell [--no-descriptions]

Description​

Generates the auto-completion script for solution for the specified shell.

Flags​

shell

Specifies the shell you're generating the script for. Options are:

  • bash: This option generates the auto-completion script for bash shells. This script depends on the bash-completion package. If it isn't installed, you should install it via your OS's package manager.
    • To load completions in your current shell session, run source <(solution sompletion bash)
    • To load completions for every new session, execute the following. You'll need to start a new shell for this setup to take effect:
      • Linux: solution completion bash > /etc/bash_completion.d/solution
      • MacOS: solution completion bash > $(brew --prefix)/etc/bash_completion.d/solution
  • fish: This option generates the auto-completion script for fish shells.
    • To load completions in your current shell session, run solution completion fish | source
    • To load completions for every new session, run solution completion fish > ~/.config/fish/completions/solution.fish. You'll need to start a new shell for this setup to take effect
  • powershell: This option generates the auto-completion script for PowerShell.
    • To load completions in your current shell session, run solution completion powershell | Out-String | Invoke-Expression
    • To load completions for every new session, add the output of the above command to your PowerShell profile.
  • zsh: This option generates the auto-completion script for Zsh shells. If shell completion is not already enabled in your environment, you will need
  • zsh: This option generates the auto-completion script for Zsh shells. If shell completion is not already enabled in your environment, you will need to enable it. You can execute the following once: echo "autoload -U compinit; compinit" >> ~/.zshrc
    • To load completions in your current shell session, run source <(solution completion zsh); compdef _solution solution
    • To load completions for every new session, execute the following. You'll need to start a new shell for this setup to take effect:
      • Linux: solution completion zsh > "${fpath[1]}/_solution"
      • MacOS: solution completion zsh > $(brew --prefix)/share/zsh/site-functions/_solution

--no-descriptions

This option disables completion descriptions.

Opening An Editor​

Syntax​

solution editor { -s | -l }

Description​

Opens an editor with a specific shorthand or flag.

Flags​

-s, --setupAssistant

Opens a browser to the login page set to redirect to the Setup Assistant Creator in the appropriate datacenter.

-l, --list

Displays a list of all available editors with their name, shorthand, and flag.

Importing Resources​

Syntax​

solution import

Description​

Imports resources as a built-out solution with Solution Execution file from a project in your Qualtrics account.

Flags​

-r, --replace, --replace=true

Specifies that the imported project should replace every solution resource-related file in the /src directory of the plugin.

Be Careful With The Replace Flag, Please!

Setting the replace flag will DELETE ALL of the solution resource files under the current plugin and replace them with the files produced by the import command.

  1. The default value for the replace flag (shorthand flag as well) is true, meaning invoking the replace flag without explicitly setting the value to false will execute the import process with original resource files removed.

  2. If you don't want the resource files under the /src folder getting DELETED, don't invoke the replace flag when running solution import command.

  3. This replace flag is most useful when you are starting your solution plugin from a start state.

-s id, --search id

Specifies the resource ID that you're searching for.

-p filepath, --path filepath

Specifies a file path to the plugin directory. Only used if the current working directory is not a valid plugin directory. Defaults to the current working directory.

Downloading Resources​

Syntax​

solution download --resourceID id --resourceType type

Description​

Downloads a specific resource from your account without having to go through the full import flow again.

Flags​

--resourceID id

Specifies the resource ID of the resource you are trying to download.

--resourceType type

Specifies the resource type of the resource you are trying to download.

Generating Test Files​

You can test the creation of your XM Solution with predefined context values. Running validation on the XM Solution can help identify possible errors / warnings before actual XM Solution creation happens. This command opens up the Setup Assistant, where you input your custom answers, and then a second command downloads your answers into a test file. file based on the current XM Solution resource content. You can find more information on validation here or generating custom answers here.

Syntax​

For opening the Setup Assistant and input your answers:

solution generate-test

For downloading the answers into the Test File:

solution generate-test --session-id {sessionId}

Flags​

--random

Gives you the option of letting the test file be generated with random values for each of the questions. The resulting test file will be named exampleTest.json

Description​

Generates an example test file using the information you input into the Setup Assistant. The resulting test file can be found under in the /tests directory. Feel free to run the command multiple times to create different files or duplicate any test file and edit/modify these files and contexts to change the way you want the XM Solution creation to run.

Validation​

After your XM Solution has been submitted, you are ready to validate. The goal is to achieve 100% step coverage with the test files you provided. You can find more information on test files here, or you can find a full guide on validating an XM Solution here.

Syntax​

solution validate [-p filepath]

Description​

Validates all resource files in the XM Solution and executes a dry-run to verify that the XM Solution files are properly connected.

For each test case (one test file), the status for each Solution execution step will be displayed:

  • If a file is marked with “done”, it means the step was correctly executed (though potential warning messages could still be displayed).
  • If a file is marked with “error”, it means the step was not executed properly, and the error message will be displayed in the console.
  • If a file is marked with “not evaluated”, it means the step was not executed because the overall process was terminated before reaching the step.
  • If a file is marked "skipped", it means the step was skipped because of some conditional logic.

The overall step execution status shows whether each step has been covered by the test cases. Since there could be conditional Solution execution steps in the XM Solution, one test case might not be able to cover all Solution execution steps.

Flags​

-p filepath, --path filepath

Specifies a file path to the plugin directory. Only used if the current working directory is not a valid plugin directory. Defaults to the current working directory.

Creating a Solution​

Syntax​

solution create

Description​

You may find yourself wanting to create an instance of your Solution without having to go through the Setup Assistant UI. This command creates an instance of your XM Solution given a json test file containing the answers from Setup Assistant.

Flags​

-t filepath, --test-path filepath

Specifies a file path to the test which contains the Setup Assistant answers with which your solution will be created. If left blank, the CLI will look for a directory named tests in the current directory, and prompt you to choose one of the test files in that directory.

If you need to create a test file, you can run solution generate-test. You can find more information about it here

-l language_code, --language language_code

This should be replaced with the language code (i.e., es or "es") for the language you want to create a solution for. If left blank, it will default to English ("en").

-p filepath, --path filepath

Specifies a file path to the plugin directory. Only used if the current working directory is not a valid plugin directory. Defaults to the current working directory.

--verbose

If this flag is provided, the CLI will output the context values that were used to create the solution.

Logging out​

Syntax​

solution logout

Description​

Logs you out of your current session.