Datastore CLI reference guide

Prerequisites

The following software must be installed or be available on your computer:

Install the CLI tools

To set up the Datastore command line interface (CLI) tool locally on your computer:

  1. After meeting the prerequisites (above), install the Experience Cloud CLI tool, which provides the base set of commands for all Squiz DXP products:

    npm install --global @squiz/dxp-cli
    If you experience EACCES permission errors when running this command, follow the recommendations in this troubleshooting article to resolve these issues.
  2. Install the Datastore CLI tool, which is installed as a plugin to the Experience Cloud CLI tool and provides all commands relevant to working with Datastore:

    dxp plugin add @squiz/dxp-plugin-datastore

Experience Cloud CLI tool command reference

This section lists and describes the base CLI commands available for all Squiz DXP products.

dxp help


Shows command line help for the dxp command and lists all other dxp commands currently available with the Experience Cloud CLI tool.

Parameters

None.

dxp login


Logs you in to your Squiz Experience Cloud account.

Required parameters

--username

The username (email address) of your Experience Cloud account.

--password

The password associated with the username for your Experience Cloud account.

Example

dxp login --username alex@example.com --password <password-entered-here>

Logs user alex@example.com in to their Experience Cloud account.

dxp logout


Logs you (the current user) out of your Experience Cloud account.

Parameters

None.

dxp plugin add


Adds a new CLI tool plugin to your local Experience Cloud CLI tool installation.

The Experience Cloud CLI tool’s functionality can be extended by adding new CLI tool plugins to your local Experience Cloud CLI tool installation.

This command requires the value of the CLI tool plugin to be specified after add.

Parameters

None.

Example

dxp plugin add @squiz/dxp-plugin-datastore

Adds the Datastore CLI tool plugin to your local Experience Cloud CLI tool installation, thereby providing you with the complete set of Datastore CLI tools.

dxp plugin remove


Removes a CLI tool plugin from your local Experience Cloud CLI tool installation.

If you no longer require the features offered by a CLI tool plugin you previously added to your local Experience Cloud CLI tool installation, you can remove the plugin using this command.

This command requires the value of the CLI tool plugin to be specified after remove.

Parameters

None.

Example

dxp plugin remove @squiz/dxp-plugin-datastore

Removes the Datastore CLI tool plugin from your local Experience Cloud CLI tool installation, thereby paring it back to just the Experience Cloud CLI tool and any other CLI tool plugins you have installed.

dxp whoami


Returns the email address of the current user who is logged in to the Squiz DXP.

Parameters

None.

Datastore CLI tool command reference

This section lists and describes all CLI commands available for Datastore.

dxp datastore blueprint add


Adds and uploads a new blueprint to your Datastore instance and creates a Datastore service for this blueprint.

Before running this command, work with a simulation of your blueprint first, to verify that the functionality of your blueprint meets your expectations.

Required parameters

--path

The path to your blueprint’s API specification file (typically named api.yaml).

--name

The name of your blueprint from which a Datastore service will be created.
Blueprint names support spaces, although the name must be enclosed within either single or double quotes.

--region

Your nearest (cloud-based) region to upload your blueprint to and access its Datastore service from.
The valid values for this parameter include us for the US and au for Australia.

Optional parameters

Some of these parameters may be mandatory based on your logged in user account’s current circumstances.

--dxp-instance-id

The ID of the Datastore instance to which the blueprint will be added.
If your logged in user account is a member of one Datastore instance only, you can omit this parameter, and the blueprint will be added to this Datastore instance.
Otherwise, this parameter is mandatory.

Example

dxp datastore blueprint add --path /path/to/api.yaml --name Events --region us --dxp-instance-id 01234567-abcd-12ab-abc1-12345a123456

Adds and uploads your new blueprint with the name "Events",
whose API specification file is located at /path/to/api.yaml to your Datastore instance, and
creates a Datastore service for this blueprint in the US region.

dxp datastore blueprint list


Lists all blueprints which have been added to your Datastore instance.

Optional parameters

Some of these parameters may be mandatory based on your logged in user account’s current circumstances.

--dxp-instance-id

The ID of the Datastore instance whose blueprints will be listed.
If your logged in user account is a member of one Datastore instance only, you can omit this parameter, and blueprints will be listed from this Datastore instance.
Otherwise, this parameter is mandatory.

Example

dxp datastore blueprint list --dxp-instance-id 01234567-abcd-12ab-abc1-12345a123456

Lists all blueprints which have been added to your Datastore instance (with the example ID 01234567-abcd-12ab-abc1-12345a123456).

dxp datastore blueprint rename


Renames an existing blueprint in your Datastore instance.

Required parameters

--old-name

The name of an existing blueprint in your Datastore instance.
If your blueprint’s name contains one or more spaces, enclose the name in either single or double quotes.

--new-name

The new name for this blueprint in your Datastore instance.
Blueprint names support spaces, although the name must be enclosed within either single or double quotes.

Optional parameters

Some of these parameters may be mandatory based on your logged in user account’s current circumstances.

--dxp-instance-id

The ID of the Datastore instance containing the blueprint to be renamed.
If your logged in user account is a member of one Datastore instance only, you can omit this parameter, and the blueprint being renamed is assumed to be in this Datastore instance.
Otherwise, this parameter is mandatory.

Example

dxp datastore blueprint rename --old-name Events --new-name "Event management"

Rename the "Events" blueprint in your Datastore instance to "Event management".

dxp datastore blueprint update


Updates an existing blueprint in your Datastore instance.

If you have made functional changes to your existing blueprint’s files, use this command to update the blueprint in your Datastore instance with these changes.

Required parameters

--path

The path to your blueprint’s API specification file (typically named api.yaml).

--name

The name of the blueprint in your Datastore service.
Blueprint names support spaces, although the name must be enclosed within either single or double quotes.

You cannot use this parameter to change the name of the blueprint. To change the name of the blueprint, use the
dxp datastore blueprint rename command instead.

Optional parameters

Some of these parameters may be mandatory based on your logged in user account’s current circumstances.

--dxp-instance-id

The ID of the Datastore instance containing the blueprint to be updated.
If your logged in user account is a member of one Datastore instance only, you can omit this parameter, and the blueprint will be updated in this Datastore instance.
Otherwise, this parameter is mandatory.

Example

dxp datastore blueprint update --name "Event management" --path /path/to/api.yaml

Updates the "Event management" blueprint in your Datastore instance (with functional changes you have made to your blueprint files).

dxp datastore simulator add


Adds a new blueprint (referenced by its API specification file) to your local Datastore simulator and creates a simulated Datastore service for this blueprint.

Unlike adding and uploading a blueprint to your Datastore instance, there is no need to update your blueprint in a simulated Datastore service. While running the local Datastore simulator, any changes you save to an added blueprint’s files locally are updated automatically in the local simulator.

Required parameters

--blueprint

The path to your blueprint’s API specification file (typically named api.yaml).

Optional parameters

--port

The HTTP port number through which your locally simulated Datastore service is available.
If you do not specify this value, then the next free port number within the range of 7001 through to 7010 will be chosen.

Example

dxp datastore simulator add --blueprint /path/to/api.yaml

Adds your new blueprint (whose API specification file is located at /path/to/api.yaml) to your local Datastore simulator, and
creates a simulated Datastore service for this blueprint.

dxp datastore simulator clear


Clears all data associated with a blueprint (referenced by its API specification file) in your local Datastore simulator.

This command is useful if you have tested a blueprint, made structural changes to it and then need to re-test the amended blueprint.

Any data stored by the blueprint’s simulated Datastore service is permanently destroyed by this command.

The blueprint and its Datastore service, however, will still be available.

Required parameters

--blueprint

The path to your blueprint’s API specification file (typically named api.yaml).

--force

This parameter must be specified (without a value) to explicitly confirm that you want to clear all data associated with this blueprint in your local Datastore simulator.

Example

dxp datastore simulator clear --blueprint /path/to/api.yaml --force

Clears all data for your blueprint (whose API specification file is located at /path/to/api.yaml) in your local Datastore simulator.

dxp datastore simulator list


Lists all blueprints which have been added to your local Datastore simulator.

Parameters

None.

dxp datastore simulator pause


Pauses your entire local Datastore simulator, along with all its blueprints' simulated Datastore services.

Alternatively, this command only pauses a single blueprint’s simulated Datastore service (in your local simulator), where the blueprint is referenced by its API specification file. When a simulated Datastore service is paused, its local simulator continues to run.

Optional parameters

--blueprint

The path to your blueprint’s API specification file (typically named api.yaml).
If this parameter is omitted, then the entire local Datastore simulator will be paused, along with all its simulated Datastore services.

Example

dxp datastore simulator pause --blueprint /path/to/api.yaml

Pauses the simulated Datastore service associated with the blueprint (whose API specification file is located at /path/to/api.yaml) in your local Datastore simulator.

dxp datastore simulator remove


Removes and deletes a blueprint (referenced by its API specification file) and its simulated Datastore service from your local Datastore simulator.

The blueprint’s simulated Datastore service, along with all its stored data, is permanently destroyed by this command.

Required parameters

--blueprint

The path to your blueprint’s API specification file (typically named api.yaml).

--force

This parameter must be specified (without a value) to explicitly confirm that you want to remove and delete the local Datastore simulator associated with this blueprint, along with all its data.

Example

dxp datastore simulator remove --blueprint /path/to/api.yaml --force

Removes and deletes your blueprint (whose API specification file is located at /path/to/api.yaml) and its simulated Datastore service from your local Datastore simulator.

dxp datastore simulator resume


Resumes your entire local Datastore simulator, along with all its blueprints' simulated Datastore services.

Alternatively, this command only resumes a single blueprint’s simulated Datastore service (in your local simulator), where the blueprint is referenced by its API specification file.

Optional parameters

--blueprint

The path to your blueprint’s API specification file (typically named api.yaml).
If this parameter is omitted, then the entire local Datastore simulator will be resumed, along with all its simulated Datastore services.

Example

dxp datastore simulator resume --blueprint /path/to/api.yaml

Resumes the simulated Datastore service associated with the blueprint (whose API specification file is located at /path/to/api.yaml) in your local Datastore simulator.

dxp datastore simulator upgrade


Upgrades your entire local Datastore simulation environment to the latest version currently available. This includes all your locally simulated Datastore services for each blueprint you have added, as well as the Docker image itself (from which these simulated services were instantiated).

Running this command clears all existing data within your Datastore simulator. Any data stored by all of your current blueprints' simulated Datastore services will be permanently destroyed.

All your existing blueprints and their Datastore services, however, will still be available.

Required parameters

--force

This parameter must be specified (without a value) to explicitly confirm that you want to upgrade all your local Datastore simulators (containers), as well as the Docker image itself, and also clear all your existing data in your Datastore simulator.

Example

dxp datastore simulator upgrade --force

dxp datastore bundle


Bundles your blueprint’s API specification and data model files into a single API specification file. Bundling your blueprint’s files into a single API spec file is required to configure a blueprint credential for the Datastore component in Connect.

Your blueprint must first be added and uploaded to your Datastore instance, and its Datastore service created, before you can use this bundle command.

Once this is done, the servers > url value will be added to your bundled API spec file. If your blueprint has not been added to your Datastore instance, then this value will be missing.

Required parameters

--blueprint

The path to your pre-bundled blueprint’s API specification file (typically named api.yaml).

--name

The name of your blueprint on the Datastore dashboard (in bold letters within the Blueprints list), which you can access through the Experience Cloud console. If the name of your blueprint contains spaces, enclose the name in double-quotes.

--output

The path and name for your bundled API specification file in YAML format. Including the word bundle in the file name will help you identify which of your YAML files has been bundled.

Example

dxp datastore bundle --blueprint /path/to/api.yaml --name "Online form" --output /path/to/online-form-api-bundled.yaml

Bundles your API specification file located at /path/to/api.yaml (including the blueprint’s JSON schema files),
which had previously been added to (and if necessary, updated in) your Datastore instance with the name Online form, and
outputs the bundled API spec file to /path/to/online-form-api-bundled.yaml.

© 2015- Squiz Pty Ltd