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
- Install the CLI tools
- DXP Console CLI tool command reference
- Datastore CLI tool command reference
- dxp datastore blueprint add
- dxp datastore blueprint list
- dxp datastore blueprint rename
- dxp datastore blueprint update
- dxp datastore simulator add
- dxp datastore simulator clear
- dxp datastore simulator list
- dxp datastore simulator pause
- dxp datastore simulator remove
- dxp datastore simulator resume
- dxp datastore simulator upgrade
- dxp datastore bundle
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.
dxp login
Logs you in to your Squiz DXP Console account.
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
.
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
.
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 includeus
for the US andau
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.
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.
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.
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
).
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. |
dxp datastore simulator list
Lists all blueprints which have been added to your local Datastore simulator.
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.
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.
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.
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. |
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 |
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
.