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.

Typical workflow

In most cases, getting started with the CLI looks like this:

Create or select an environment with dw env
Log in with dw login
Run the command you need, such as dw files, dw query, dw command, or dw install

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:

Clone from github
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

The CLI also supports these global options:

--host - run a command against a specific host without switching environment first
--protocol - set the protocol used with --host, defaults to https
--apiKey - use an API key directly instead of a stored logged-in user
-v, --verbose - enable verbose logging

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 config stored in `.dwc` in your user home directory
dw files [dirPath] [outPath]	Handles various files-related tasks, e.g. like exporting, listing, and importing 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 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>

You can modify the .dwc file 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"
    }
}

The environments and users you create are stored in the .dwc file in your user home directory.

If you already have a manually generated API key, you can also skip the stored login flow and call commands directly with --host and --apiKey.

For example:

dw files templates ./templates --export --recursive --host localhost:12345 --protocol http --apiKey <yourApiKey>

The dw env command also supports:

-l, --list - list all configured environments
-u, --users - list users for the specified environment or the current environment

Examples:

dw env --list
dw env production --users

Warning

The interactive login prompt is not verified to work against all current DynamicWeb authentication setups.

If dw login does not work in your environment, generate an API key manually on the target solution and use --apiKey <key> together with --host and --protocol instead of relying on a stored login.

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)
-af, --asFile – Force the source path to be treated as a file
-ad, --asDirectory – Force the source path to be treated as a directory

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

Tip

Files source type detection

By default, the CLI detects whether dirPath should be treated as a file or directory based on the path name.

If that detection is wrong, you can force the behavior:

Use --asFile when the path should be treated as a single file
Use --asDirectory when the path should be treated as a directory, even if the name contains a dot

Examples:

dw files templates/Translations.xml ./templates --export --asFile
dw files templates/templates.v1 ./templates --export --asDirectory

Importing and deploying between environments

You can use dw files to deploy files between environments:

Set environment to development

dw env development dw files templates ./templates --export --recursive
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" }'

Note

The --list option exists for dw command, but it is currently not working reliably, so do not depend on it for command schema discovery.

Installing custom add-ins and extensions

The dw install command is used to install custom add-ins and extensions into a Dynamicweb environment. It supports both locally built add-ins (such as compiled .dll or .nupkg files) and packaged extensions.

dw install <filePathOrPackage> [--queue]

The install command has this option to specify if loading of the addin should be deferred;

-q, --queue - Will defer loading of the installed addin to ensure dependencies are loaded before load

After compiling your add-in, you can install it by pointing the command to the output file:

dw install ./bin/Release/net8.0/CustomProject.dll

By default, the add-in is installed and made available immediately once the command completes.

Immediate installation (default behavior)

When dw install is run without the --queue option, the add-in is:

Installed into the environment
Activated immediately

This mode is well suited for:

Local development
Iterative testing
Single add-in updates with no external dependencies

As soon as the command finishes, the add-in is available to the running application.

Queued installation (`--queue`)

When the --queue option is specified, the add-in is installed but not activated immediately:

dw install ./bin/Release/net8.0/CustomProject.dll --queue

Instead, the installation is added to the environment’s install queue and activated later as part of controlled processing.

When to use `--queue`

Queued installation is recommended when:

Installing multiple add-ins in sequence
Deploying add-ins as part of automated scripts or CI/CD pipelines
Installing add-ins that depend on other add-ins or shared libraries
Preparing an environment before a planned restart

Using --queue ensures that all add-ins and their dependencies are fully installed before any of them are activated, reducing the risk of partial loads or dependency conflicts.

Installing add-ins with dependencies

If your add-in depends on other assemblies or packages, queued installation provides a safer deployment flow:

All add-ins and dependencies are installed first
Activation happens only after the full set is in place

This avoids scenarios where an add-in is activated while one or more of its dependencies are still being updated.

For this reason, --queue is strongly recommended when installing add-ins that depend on shared libraries or other extensions.

Notes

Note

Some add-in types require an application restart before they become active.
When installing add-ins in hosted or cloud environments, queued installation is the preferred approach for predictable and reliable deployments. See the DynamicWeb Cloud article for guidance on restarts and deployment workflows.

Recommended usage summary

Local development: use dw install
Automation, dependencies, or multiple add-ins: use dw install --queue

This keeps development fast and deployments safe — the correct balance for a system that’s both extensible and alive.

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

Troubleshooting

Git Bash path conversion

If you are using Git Bash, you may run into path conversion issues when working with relative paths.

To disable path conversion for the current shell session:

export MSYS_NO_PATHCONV=1

Example:

export MSYS_NO_PATHCONV=1
dw files -iro ./ ./TestFolder --host <host> --apiKey <apiKey>

Table of Contents

DynamicWeb CLI

Typical workflow

Installation

Commands

Environments and users

Warning

Uploading and Managing Files

Common options

Listing files

Uploading files

Exporting files

Tip

Importing and deploying between environments

Cloning Swift

Queries and commands

Note

Installing custom add-ins and extensions

Immediate installation (default behavior)

Queued installation (--queue)

When to use --queue

Installing add-ins with dependencies

Notes

Note

Recommended usage summary

Database operations

Requirements

Editing the .dwc configuration

Troubleshooting

Git Bash path conversion

Queued installation (`--queue`)

When to use `--queue`