DynamicWeb CLI
Get started with our command-line interface.
DynamicWeb CLI is a powerful command line tool designed to help developers quickly and efficiently manage any given DynamicWeb 10 solution they may have access to. These tools includes an easy setup and handling of different environments, access to the Management API and an easy way to update a Swift solution.
Logging into a DynamicWeb 10 solution through the DynamicWeb CLI will create an API Key for the given user, which in turn lets you use any Queries and Commands the solution has, meaning you can control everything you can do in the backend, from your command line. With this, you can hook it up to your own build pipelines and processes, if certain requests needs to happen before or after deployments or changes.
The DynamicWeb CLI can also help with active development of custom addins to solutions. With a simple dw install
command it will upload and install your custom code to the solution you're connected to.
Extracting files from solutions is just as easy as well, with the DynamicWeb CLI you can list out the structure of a solution and get full exports of the files structure and the database. Importing files into a solution is just as easy as well, as long as you have access to the files and the solution, they can be imported with a simple command using the DynamicWeb CLI.
Installation
DynamicWeb CLI can either be installed from npm or cloned from github and installed locally. If you plan on just using DynamicWeb CLI, install from npm by running the command:
npm i @dynamicweb/cli -g
If you want to extend or contribute to DynamicWeb CLI, clone the repository so all the code is available locally:
Move CLI repo to project dir
Run the following commands:
npm install -g npm install
If you're faced with errors such as Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'yargs' try installing that module specifically:
npm install yargs
Commands
All commands and options can be viewed by running
dw --help
dw <command> --help
Here is a short overview:
Command | Use |
---|---|
dw | Show the current environment and user |
dw login [user] | Starts a prompt for logging in a user, unless [user] is specified, in which case it changes the current user to that user |
dw env [env] | If [env] is specified, changes the current environment to the new environment, else sets up a config for a new environment |
dw install [filePath] | Moves a custom .dll or .nupkg file to the Systems/AddIns/Local folder of the current environment, then installs it by moving it to System/AddIns/Installed |
dw config | Allows you to edit the configs located under usr/.dwc |
dw files [dirPath] [outPath] | Handles various files-related tasks, e.g. like exporting files and folders |
dw swift [outPath] | Downloads latest Swift-version to outPath |
dw database [path] | Handles database tasks, like export the environment database as a .bacpac file |
dw query [query] | Executes a query against our management API |
dw command [command] | Executes a command against our management API |
Below, you will find example of how you do common tasks using the DW CLI.
Environments and users
The first thing you typically want to do is set up your environments - by convention these are usually development, staging and production - by running...
dw env
...for each environment and adding a name and a host URL.
? environment: <environment>
? Enter your host including protocol, i.e "https://yourHost.com": <host>
You can see information about the current environment by using the dw
command:
dw
Environment: development
User: undefined
Protocol: https
Host: localhost:35323
As you can see, no user is associated with this environment. Since the queries and commands used to pull and push data uses the Management API of a solution, you need to add a user with authorization to access it.
To generate an API-key that the CLI will use, login to your environment:
dw login
This will start an interactive session asking for username and password, as well as the name of the environment, so it's possible to switch between different environments easily.
It will ask for a protocol and a host, if you're running a local environment, set this to the host it starts up with, i.e localhost:12345
. The protocol should be http or https.
Each environment has its own users, and each user has its own API-key assigned to it, swap between environments by using:
dw env <env>
Swap between users by supplying the name of the user in the login command
dw login <username>
The environments and users you create are store in a config file located in usr/.dwc
(for a PC user C:\Users<xxx>.dwc). You can modify it directly if you want to, the structure should look like this:
{
"env": {
"dev": {
"host": "localhost:12345",
"users": {
"DemoUser": {
"apiKey": "<keyPrefix>.<key>"
}
},
"current": {
"user": "DemoUser"
}
}
},
"current": {
"env": "dev"
}
}
Moving files around
The dw files
-command...
dw files <dirPath> <outPath>
...is used to list out and export the structure in your DynamicWeb files archive, as such is has multiple options;
-l
--list
This will list the directory given in <dirPath>-f
--includeFiles
The list will now also show all files in the directories-r
--recursive
By default it only handles the <dirPath>, but with this option it will handle all directories under this recursively-e
--export
It will export <dirPath> into <outPath> on your local machine, unzipped by default--raw
This will keep the content zipped--iamstupid
This will include the export of the /files/system/log and /files/.cache folders
For example, to list the files structure of the system folder for the current environment:
dw files system -lr
system
├── EventNotifications
├── Log
│ ├── AddInManager
│ ├── EventViewer
│ └── ScheduledTasks
├── ShadowEdit
├── SmartSearches
│ └── Users
└── UserTypes
To export the templates-folder from the staging
-environment to the templates folder of a local solution:
cd path/to/files/with/templates-folder
dw env staging
dw files templates ./templates -fre
Downloading templates Recursive=true
Finished downloading templates Recursive=true
To deploy from development
to staging
you can therefore:
- Set environment to
development
- Use
dw files
to export your design to somewhere local - Set environment to
staging
- Use
dw files
to export from your local folder to the Designs-folder on staging
Cloning Swift
The dw swift
-command is used to easily clone a Swift release.
dw swift <outPath>
It has multiple options to specify which tag or branch to pull;
-t
--tag <tag>
The tag/branch/release to pull-l
--list
Will list all the release versions-n
--nightly
Will pull #HEAD, as default is latest release--force
Used if <outPath> is not an empty folder, to override all the content
To see a list of all available releases run:
dw swift --list
To clone a specific version run:
dw swift --tag v1.25.1
To override an already cloned solution with latest nightly build:
dw swift . -n --force
Queries and commands
Our DynamicWeb 10 Management API allows you to execute queries and commands against a solution. This can be used for a multitude of things, basically anything which can be done via the UI.
The dw query
-command will execute any query against the management API of the current environment:
dw query <query>
Any parameters which are mandatory for the query are of course also mandatory in this command - if you don't know which parameters are mandatory you can use the following options to find out:
-l
--list
Will list all the properties for the given <query>-i
--interactive
Will perform the <query> but without any parameters, as they will be asked for one by one in interactive mode--<queryParam>
Any parameter the query needs will be sent by--key value
So to list all properties for the query FileByName:
dw query FileByName --list
And to get information on a specific file by name:
dw query FileByName --name git-keep.txt --directorypath /Files/Files
{
model: {
modelIdentifier: '/Files/Files/git-keep.txt',
imagePath: '',
name: 'git-keep.txt',
extension: '.txt',
directoryPath: '/Files/Files',
sizeInBytes: 0,
createdAt: '2024-01-22T13:33:32.524285+01:00',
updatedAt: '2022-09-01T15:17:04.8047224+02:00',
filePath: '/Files/Files/git-keep.txt',
accessedAt: '2024-01-22T13:33:32.524285+01:00',
permissionLevelCurrentUser: 'all'
},
successful: true,
message: ''
}
Likewise, the command
-command will execute any management api command against a solution:
dw command <command>
It works like query, given the query parameters necessary, however if a DataModel
is required for the command, it is given in a json-format, either through a path to a .json file or a literal json-string in the command.
To create a copy of a page using a json-string:
dw command PageCopy --json '{ "model": { "SourcePageId": 1189, "DestinationParentPageId": 1129 } }'
To move a page using a .json-file:
dw command PageMove --json ./PageMove.json
Where PageMove.json contains:
{
"model": {
"SourcePageId": 1383,
"DestinationParentPageId": 1376
}
}
To delete a page:
dw command PageDelete --json '{ "id": "1383" }'
Installing custom dll's
The dw install
-command is used to upload and install a custom .dll og .nupkg add-in on the current environment.
dw install <filePath>
It's meant to be used to easily apply custom dlls to a project or solution, local or otherwise so after having a dotnet library compiled locally, this command can be run, pointing to the compiled .dll and it will handle the rest with all the add-in installation, and it will be available in the DynamicWeb solution as soon as the command finishes:
dw install ./bin/Release/net6.0/CustomProject.dll
Database operations
The dw database
-command is used for actions towards the database of your current environment.
dw database <outPath>
It currently only supports one operation, which is exporting the database of the current environment as a .bacpac file:
-e
--export
Exports your current environments database to a .bacpac file at <outPath>
To export the database:
dw database -e ./backup
Editing the .dwc configuration
The dw config
-command is used to manage the .dwc file which contains environment variables and users authorizations.
dw config
Given any property it will create the key/value with the path to it.
--<property>
The path and name of the property to set
To change the host for the dev environment:
dw config --env.dev.host localhost:12345