Datastore CLI reference guide

The Datastore CLI tools provide the commands necessary to add your Datastore blueprint to your local simulator or upload the blueprint to Squiz DXP Console, as well as manage these blueprints in either environment.

To start using Datastore CLI tools, you first need to install them locally to your computer, after meeting the required prerequisites.

Prerequisites

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

Node.js (version 14+) and npm (version 7+) - used to install and run the Datastore command line interface (CLI) tools.
Docker - used by Datastore’s CLI tools to create Docker containers for the local simulator environment.
- For Windows or macOS, install Docker Desktop.
- For Linux, follow the appropriate installation instructions in the Docker Docs site.
A compatible command-line shell environment such as Bash or Zsh (available by default on most macOS or Linux systems), or Windows Terminal (on Windows) to run Datastore’s CLI tools.
- For Windows 10, you can alternatively set up the Windows Subsystem for Linux. To do this, follow its installation instructions in the Microsoft Docs site.

Install the CLI tools

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

After meeting the prerequisites (above), install the DXP Console 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.
Install the Datastore CLI tool, which is installed as a plugin to the DXP Console CLI tool and provides all commands relevant to working with Datastore:
```
dxp plugin add @squiz/dxp-plugin-datastore
```

DXP Console 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 DXP Console CLI tool.

Parameters

None.

Logs you in to your Squiz DXP Console account.

Required parameters

--username: The username (email address) of your DXP Console account.

Optional parameters

--password: The password associated with the username for your DXP Console account. When not specified, you will be prompted for a password.

Example

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

Logs user alex@example.com in to their DXP Console account.

dxp logout

Logs you (the current user) out of your DXP Console account.

Parameters

None.

dxp plugin add

Adds a new CLI tool plugin to your local DXP Console CLI tool installation.

The DXP Console CLI tool’s functionality can be extended by adding new CLI tool plugins to your local DXP Console 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 DXP Console 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 DXP Console CLI tool installation.

If you no longer require the features offered by a CLI tool plugin you previously added to your local DXP Console 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 DXP Console CLI tool installation, thereby paring it back to just the DXP Console 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 DXP Console 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.