Table of Contents

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:

  1. Clone from github

  2. Move CLI repo to project dir

  3. 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. 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. 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
Improve this doc
To top