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 Comments
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 Hardcoded 2GB limit, will fail with 'No files found'-error if larger
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 using a DynamicWeb user with backend access and administrator privileges:

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"
    }
}
Warning

At this point in time, the interactive session to create logins for new users is broken.

As a workaround, you can generate an API key manually on the target environment and use the --apiKey <key> parameter directly on a command instead of relying on a logged-in user. You can also register users manually in the .dwc as shown above.

Uploading and Managing Files

The dw files command lets you list, upload, and export files in your Dynamicweb solution. This command effectively replaces traditional FTP workflows with a secure, auditable, API-driven method.

dw files <dirPath> <outPath> [options]

Common options

  • -l, --list – Lists all directories (and files if --includeFiles is also set)
  • -f, --includeFiles – Include files in listings
  • -r, --recursive – Traverse subdirectories recursively (works with list, import, and export)
  • -e, --export – Export files from the solution to your local machine
  • -i, --import – Import files from your local machine into the solution
  • -o, --overwrite – Allow overwriting of existing files when importing
  • --createEmpty – Create empty files when importing (even if the source file is empty)
  • --raw – Keep exported files zipped instead of unpacking them
  • --iamstupid – Also include log and cache folders in export (not recommended)

Listing files

This is an example of how to list the structure of the System folder, including all files, recursively. The operation can be performed at any point in the folder structure.

dw files system -lr

Example output:

system
├── EventNotifications
├── Log
│   ├── AddInManager
│   ├── EventViewer
│   └── ScheduledTasks
└── UserTypes

Uploading files

Upload a single file (e.g., an ERP-generated XML file):

dw files ./orders/order123.xml /imports/orders/ --import

Upload a full folder recursively:

dw files ./orders/ /imports/orders/ --import --recursive

Overwrite existing files if needed:

dw files ./orders/order123.xml /imports/orders/ --import --overwrite

Exporting files

Export a folder recursively:

dw files /templates ./templates --export --recursive

Export top-level files only (no recursion):

dw files /templates ./templates --export

Keep content zipped:

dw files /templates ./templates --export --raw

Importing and deploying between environments

You can use dw files to deploy files between environments:

  1. Set environment to development

    dw env development dw files templates ./templates --export --recursive

  2. Switch to staging

    dw env staging dw files ./templates /templates --import --recursive

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
Note
  • Installation of some addin types, e.g. IPipeline requires an application restart
  • See DynamicWeb Cloud-article for instruction on restarting an application hosted in the cloud

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

Requirements

The db user needs db_backupoperator permissions.

To backup a database with the CLI the db user used for running the Dynamicweb installation will need db_backupoperator permissions which can be setup in SQL-Server Management studio.

Alternatively use T-SQL to set the right permissions

USE [youDwDatabaseName]
GO
ALTER ROLE [db_backupoperator] ADD MEMBER [yourDwDbUserName]
GO

The script has to be run with dbo user or similar permissions

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