@dynamicweb/cli 1.0.16 → 1.1.0

package/README.md

@@ -1,222 +1,244 @@
-# DynamicWeb CLI
-
-## What is it?
-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 inclues 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 had, 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 a solution.
-
-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.
-
-## Get started
-To install after cloning, move to project dir and run
-> $ npm install -g .
-> 
-> $ npm install
-
-Note that specific installations might be necessary if you're faced with errors such as 'Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'yargs''
-In which case try installing that module specifically;
-> $ npm install yargs
-
-## Commands
-All commands and options can be viewed by running
-> $ dw --help
-> 
-> $ dw \<command\> --help
-
-### Users and environments
-As most commands are pulling or pushing data from the DW admin API, the necessary authorization is required.
-
-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 also ask for a host, if you're running a local environment, set this to the host it starts up with, i.e `localhost:6001`.
-
-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\>
-
-and swap between users by simply supplying the name of the user in the login command
-> $ dw login \<username\>
-
-You can view the current environment and user being used by simply typing
-> $ dw
-
-The configuration will automatically be created when setting up your first environment, but if you already have an Api-key you want to use for a user, you can modify the config directly in the file located in `usr/.dwc`. The structure should look like the following
-```json
-{
-    "env": {
-        "dev": {
-            "host": "localhost:6001",
-            "users": {
-                "DemoUser": {
-                    "apiKey": "<keyPrefix>.<key>"
-                }
-            },
-            "current": {
-                "user": "DemoUser"
-            }
-        }
-    },
-    "current": {
-        "env": "dev"
-    }
-}
-```
-
-### Files
-> $ dw files \<dirPath\> \<outPath\>
-
-The files command 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
-
-#### Examples
-Exporting all templates from current environment to local solution
-> $ cd DynamicWebSolution/Files
-> 
-> $ dw files templates ./templates -fre
-
-Listing the system files structure of the current environment
-> $ dw files system -lr
-
-### Files Source Type Detection
-By default, the `dw files` command automatically detects the source type based on the \<dirPath\>:
-If the path contains a file extension (e.g., 'templates/Translations.xml'), it is treated as a file.
-Otherwise, it is treated as a directory.
-In cases where this detection is incorrect, you can force the type using these flags:
-
-- `-ad` `--asDirectory`  Forces the command to treat the path as a directory, even if its name contains a dot.
-- `-af` `--asFile`       Forces the command to treat the path as a single file, even if it has no extension. 
-
-#### Examples
-
-Exporting single file from current environment to local solution
-> $ dw files templates/Translations.xml ./templates -e
-
-Exporting a directory that looks like a file
-> $ dw files templates/templates.v1 ./templates -e -ad
-
-Exporting a file that has no extension
-> $ dw files templates/testfile ./templates -e -af
-
-### Swift
-> $ dw swift \<outPath\>
-
-The swift command is used to easily get your local environment up to date with the latest swift release. It will override all existing directories and content in those, which can then be adjusted in your source control afterwards. 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
-
-#### Examples
-Getting all the available releases
-> $ dw swift -l
-
-Pulling and overriding local solution with latest nightly build
-> $ cd DynamicWebSolution/Swift
-> 
-> $ dw swift . -n --force
-
-### Query
-> $ dw query \<query\>
-
-The query command will fire any query towards the admin Api with the given query parameters. This means any query parameter that's necessary for the given query, is required as an option in this command. It's also possible to list which parameters is necessary for the given query through the options;
-- `-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'
-
-#### Examples
-Getting all properties for a query
-> $ dw query FileByName -l
-
-Getting file information on a specific file by name
-> $ dw query FileByName --name DefaultMail.html --directorypath /Templates/Forms/Mail
-
-### Command
-> $ dw command \<command\>
-
-Using command will, like query, fire any given command in the solution. 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.
-- `-l` `--list` Lists all the properties for the command, as well as the json model required **currently not working**
-- `--json` Takes a path to a .json file or a literal json, i.e --json '{ abc: "123" }'
-
-#### Examples
-Creating a copy of a page using a json-string
-> $ dw command PageCopy --json '{ "model": { "SourcePageId": 1189, "DestinationParentPageId": 1129 } }'
-
-Removing a page using a json file
-> $ dw command PageMove --json ./PageMove.json
-
-Where PageMove.json contains
-```json
-{ "model": { "SourcePageId": 1383, "DestinationParentPageId": 1376 } }
-```
-
-Deleting a page
-> $ dw command PageDelete --json '{ "id": "1383" }'
-
-### Install
-> $ dw install \<filePath\>
-
-Install is somewhat of a shorthand for a few commands. It will upload and install a given .dll or .nupkg addin to your current environment.
-
-It's meant to be used to easily apply custom dlls to a given project, it being local or otherwise, so after having a dotnet library built locally, this command can be run, pointing to the built .dll and it will handle the rest with all the addin installation, and it will be available in the DynamicWeb solution as soon as the command finishes.
-
-#### Examples
-> $ dw install ./bin/Release/net6.0/CustomProject.dll
-
-### Database
-> $ dw database \<outPath\>
-
-This command is used for various actions towards your current environments database.
-- `-e` `--export`       Exports your current environments database to a .bacpac file at \<outPath\>
-
-#### Examples
-> $ dw database -e ./backup
-
-### Config
-> $ dw config
-
-Config is used to manage the .dwc file through the CLI, given any prop it will create the key/value with the path to it.
-- `--<property>`  The path and name of the property to set
-
-#### Examples
-Changing the host for the dev environment
-> $ dw config --env.dev.host localhost:6001
-
-## Using Git Bash
-If you're using Git Bash, you may encounter issues with path conversion that can interfere with relative paths used in commands.
-
-### Path Conversion Issues
-Git Bash automatically converts relative paths to absolute paths, which can cause problems. 
-You'll see a warning message if the conversion setting is not disabled:
-
-"You appear to have path conversion turned on in your shell. 
-If you are using relative paths, this may interfere. 
-Please see https://doc.dynamicweb.dev/documentation/fundamentals/code/CLI.html for more information."
-
-### Solution
-To resolve this issue, disable path conversion by setting the `MSYS_NO_PATHCONV` environment variable (current session only):
-
-> $ export MSYS_NO_PATHCONV=1
-
-#### Examples
-
-> $ export MSYS_NO_PATHCONV=1
-> $ dw files -iro ./ /TestFolder --host \<host\> --apiKey \<apiKey\>
-
-### Alternative Solutions
-If you prefer not to disable path conversion globally, you can:
-
-1. Prefix relative paths with `./` instead of just `/` to prevent conversion for specific commands.
-2. Use PowerShell or CMD instead of Git Bash.
-
-#### Examples
-
-> $ dw files -iro ./ ./TestFolder --host \<host\> --apiKey \<apiKey\>
+# DynamicWeb CLI
+
+## What is it?
+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 include 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 had, 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 a solution.
+
+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.
+
+## Get started
+### Install from npm
+Install the published CLI globally:
+> $ npm install -g @dynamicweb/cli
+
+Then verify the command is available:
+> $ dw --help
+
+### Install from source
+If you're working on the CLI locally, clone the repository, move into the project directory, and run:
+> $ npm install
+>
+> $ npm install -g .
+
+This installs dependencies for development and links the current checkout as the global `dw` command.
+
+### Publish a new version
+Before publishing, make sure the version in `package.json` has been bumped:
+> $ npm version patch
+
+Log in to npm and publish the scoped package publicly:
+> $ npm login
+>
+> $ npm publish --access public
+
+## Commands
+All commands and options can be viewed by running
+> $ dw --help
+> 
+> $ dw \<command\> --help
+
+### Global options
+Most commands support the following global options:
+- `-v` `--verbose`    Run with verbose logging
+- `--host`            Set the host directly, bypassing environment config (requires `--apiKey`)
+- `--apiKey`          Set the API key for an environmentless execution
+- `--protocol`        Set the protocol used (only with `--host`, defaults to `https`)
+
+### Users and environments
+As most commands are pulling or pushing data from the DW admin API, the necessary authorization is required.
+
+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 also ask for a host, if you're running a local environment, set this to the host it starts up with, i.e `localhost:6001`.
+
+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\>
+
+and swap between users by simply supplying the name of the user in the login command
+> $ dw login \<username\>
+
+You can view the current environment and user being used by simply typing
+> $ dw
+
+The configuration will automatically be created when setting up your first environment, but if you already have an Api-key you want to use for a user, you can modify the config directly in the file located in `~/.dwc`. The structure should look like the following
+```json
+{
+    "env": {
+        "dev": {
+            "host": "localhost:6001",
+            "users": {
+                "DemoUser": {
+                    "apiKey": "<keyPrefix>.<key>"
+                }
+            },
+            "current": {
+                "user": "DemoUser"
+            }
+        }
+    },
+    "current": {
+        "env": "dev"
+    }
+}
+```
+
+### Files
+> $ dw files \<dirPath\> \<outPath\>
+
+The files command 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
+
+#### Examples
+Exporting all templates from current environment to local solution
+> $ cd DynamicWebSolution/Files
+> 
+> $ dw files templates ./templates -fre
+
+Listing the system files structure of the current environment
+> $ dw files system -lr
+
+### Files Source Type Detection
+By default, the `dw files` command automatically detects the source type based on the \<dirPath\>:
+If the path contains a file extension (e.g., 'templates/Translations.xml'), it is treated as a file.
+Otherwise, it is treated as a directory.
+In cases where this detection is incorrect, you can force the type using these flags:
+
+- `-ad` `--asDirectory`  Forces the command to treat the path as a directory, even if its name contains a dot.
+- `-af` `--asFile`       Forces the command to treat the path as a single file, even if it has no extension. 
+
+#### Examples
+
+Exporting single file from current environment to local solution
+> $ dw files templates/Translations.xml ./templates -e
+
+Exporting a directory that looks like a file
+> $ dw files templates/templates.v1 ./templates -e -ad
+
+Exporting a file that has no extension
+> $ dw files templates/testfile ./templates -e -af
+
+### Swift
+> $ dw swift \<outPath\>
+
+The swift command is used to easily get your local environment up to date with the latest swift release. It will override all existing directories and content in those, which can then be adjusted in your source control afterwards. 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
+
+#### Examples
+Getting all the available releases
+> $ dw swift -l
+
+Pulling and overriding local solution with latest nightly build
+> $ cd DynamicWebSolution/Swift
+> 
+> $ dw swift . -n --force
+
+### Query
+> $ dw query \<query\>
+
+The query command will fire any query towards the admin Api with the given query parameters. This means any query parameter that's necessary for the given query, is required as an option in this command. It's also possible to list which parameters is necessary for the given query through the options;
+- `-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'
+
+#### Examples
+Getting all properties for a query
+> $ dw query FileByName -l
+
+Getting file information on a specific file by name
+> $ dw query FileByName --name DefaultMail.html --directorypath /Templates/Forms/Mail
+
+### Command
+> $ dw command \<command\>
+
+Using command will, like query, fire any given command in the solution. 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.
+- `-l` `--list` Lists all the properties for the command, as well as the json model required
+- `--json` Takes a path to a .json file or a literal json, i.e --json '{ abc: "123" }'
+
+#### Examples
+Creating a copy of a page using a json-string
+> $ dw command PageCopy --json '{ "model": { "SourcePageId": 1189, "DestinationParentPageId": 1129 } }'
+
+Removing a page using a json file
+> $ dw command PageMove --json ./PageMove.json
+
+Where PageMove.json contains
+```json
+{ "model": { "SourcePageId": 1383, "DestinationParentPageId": 1376 } }
+```
+
+Deleting a page
+> $ dw command PageDelete --json '{ "id": "1383" }'
+
+### Install
+> $ dw install \<filePath\>
+
+Install is somewhat of a shorthand for a few commands. It will upload and install a given .dll or .nupkg addin to your current environment.
+
+It's meant to be used to easily apply custom dlls to a given project, it being local or otherwise, so after having a dotnet library built locally, this command can be run, pointing to the built .dll and it will handle the rest with all the addin installation, and it will be available in the DynamicWeb solution as soon as the command finishes.
+
+#### Examples
+> $ dw install ./bin/Release/net10.0/CustomProject.dll
+
+### Database
+> $ dw database \<outPath\>
+
+This command is used for various actions towards your current environments database.
+- `-e` `--export`       Exports your current environments database to a .bacpac file at \<outPath\>
+
+#### Examples
+> $ dw database -e ./backup
+
+### Config
+> $ dw config
+
+Config is used to manage the .dwc file through the CLI, given any prop it will create the key/value with the path to it.
+- `--<property>`  The path and name of the property to set
+
+#### Examples
+Changing the host for the dev environment
+> $ dw config --env.dev.host localhost:6001
+
+## Using Git Bash
+If you're using Git Bash, you may encounter issues with path conversion that can interfere with relative paths used in commands.
+
+### Path Conversion Issues
+Git Bash automatically converts relative paths to absolute paths, which can cause problems. 
+You'll see a warning message if the conversion setting is not disabled:
+
+"You appear to have path conversion turned on in your shell. 
+If you are using relative paths, this may interfere. 
+Please see https://doc.dynamicweb.dev/documentation/fundamentals/code/CLI.html for more information."
+
+### Solution
+To resolve this issue, disable path conversion by setting the `MSYS_NO_PATHCONV` environment variable (current session only):
+
+> $ export MSYS_NO_PATHCONV=1
+
+#### Examples
+
+> $ export MSYS_NO_PATHCONV=1
+> $ dw files -iro ./ /TestFolder --host \<host\> --apiKey \<apiKey\>
+
+### Alternative Solutions
+If you prefer not to disable path conversion globally, you can:
+
+1. Prefix relative paths with `./` instead of just `/` to prevent conversion for specific commands.
+2. Use PowerShell or CMD instead of Git Bash.
+
+#### Examples
+
+> $ dw files -iro ./ ./TestFolder --host \<host\> --apiKey \<apiKey\>