What is ExtendCli?

CAST Extend local server and CAST Extend Offline (in v. ≥ 1.1.0) are delivered "empty" without any preconfigured extensions - you will therefore need to populate them with extensions before you can use them. In addition, you may want to update CAST Extend local server/Offline to add new extensions or to include more recent releases of extensions. The ExtendCli tool is designed to perform this job and will allow the integration of the following (see Contributor types for more information about the types of extensions that are available):

• Official Product extensions
• User Community and Labs extensions

Where can you find ExtendCli?

ExtendCli is provided in two ways:

• As a separate downloadable tool, available from CAST Extend: https://extend.castsoftware.com/#/extension?id=com.castsoftware.aip.extendcli&version=latest - CAST highly recommends that you use this tool to benefit from the most recent updates and changes.
• On each Node instance in the following default location:

Console ≥ 2.x Node
%PROGRAMFILES%\CAST\AIP-Node\bin\ExtendCli\ExtendCli.exe

Console 1.x Node
%PROGRAMFILES%\CAST\AipConsole\AipNode\bin\ExtendCli\ExtendCli.exe

What's new

See ExtendCli - Release Notes for more information.

Prerequisites

To use ExtendCli, the following is required:

Supported Operating Systems

Operating System	Supported
Microsoft Windows 10 64-bit
Microsoft Windows Server 2016
Microsoft Windows Server 2019
Microsoft Windows Server 2022

Using ExtendCli

ExtendCli is provided as an executable (ExtendCli.exe) and must be used in command line mode. To do so, either:

• open a command prompt, and run the tool from where the downloaded tool has been unzipped
• create a re-usable batch script file

The required command line is as follows:

ExtendCli.exe [command][options]

Available commands

• bundle
• config
• download
• install (available in ≥ 1.1.0-funcrel)
• uninstall (available in ≥ 1.1.0-funcrel)

bundle

Technically, a bundle is a .json file in which information about the required extensions, any dependencies and other selection options are stored. The default value of "bundle" is default.json. You can create as many "bundles" as necessary. Available options are listed below:

config

The config command configures the parameters to allow the tool to connect to CAST Extend over the internet to fetch the required extensions (extensions) for the bundle:

ExtendCli.exe config set proxy <protocol://[user:password@]host[:port]>

ExtendCli.exe config proxy <protocol://host[:port]> [-options]

download

This option allows you to download an extension in .nupkg format. The package will NOT be downloaded to %PROGRAMDATA%\CAST\CAST\Extensions, instead the package will be downloaded to the following default locations:

• %PROGRAMDATA%\CAST\ExtendCLI\packages

If ExtendCli is being run using the executable provided with a Node, then the default storage location is set to:

• %PROGRAMDATA%\CAST\AIP-Node\ExtendCliConfig\packages
• %PROGRAMDATA%\CAST\AIP-Console-Standalone\ExtendCliConfig\packages

The download folder can be set to an alternative location using the config set storage-dir option.

ExtendCli.exe download [options] <extension id>

install

This option allows you to download an extension from CAST Extend and store it on the local machine in %PROGRAMDATA%\CAST\CAST\Extensions (or an alternative location if you have modified the CAST_PLUGINS_ROOT_PATH option in the CastGlobalSettings.ini file):

SHA256 data integrity checks

When using the install command, ExtendCLI will automatically verify each extension using a unique SHA256 hash code generated by the source Extend server (whether this is CAST's official Extend server, or an Extend Local server) to ensure the integrity of the downloaded data::

• If the integrity check passes, then the extension will be installed without issue
• If the integrity check fails, then an error is thrown and the downloaded extension is deleted and will not be installed. In this scenario, you should attempt the install procedure again - if they integrity check fails again, please contact CAST Support.

uninstall

Extension com.castsoftware.test version : 1.2.0-funcrel is not present on this machine,
and some schemas are using it. Please use ExtensionDownloader to download it and rerun Servman.

Usage examples

Set the CAST Extend (online) connection properties

Set the CAST Extend URL:

ExtendCli.exe config set extend-url "Your URL"

Set the api key:

ExtendCli.exe config set api-key w9876xyz-d999-32ii-9fb0-0123cde45

Define the extensions to package

Add one extension

The extension and any dependencies will be added to the list of extensions in the bundle with the following command:

extendCli.exe bundle add com.castsoftware.typescript

You can also use certain [options] as follows:

ExtendCli.exe bundle add com.castsoftware.typescript [options]

These options can be cumulative, for instance to download the absolute latest release (including alpha/beta) or the latest funcrel release or the latest LTS, use the following:

extendCli.exe bundle add com.castsoftware.typescript -a -f -l

To download the absolute latest release (including alpha/beta) or the latest LTS, use the following:

extendCli.exe bundle add com.castsoftware.typescript -a -l

E.g.:

Add extensions from predefined bundles

The "add template" command allows you to add extensions to your bundle that belong to a specific predefined bundle (predefined in CAST Extend (online)). The following command will add template number 14 to the bundle:

ExtendCli.exe bundle template add 14

The following commands will add all "product", "user community" and "labs" extensions:

ExtendCli.exe bundle template add product
ExtendCli.exe bundle template add community
ExtendCli.exe bundle template add labs

Save the bundle

Once you have defined the content of your bundle using the bundle add or template add commands, you can save it to a .json file, so that you can use the same bundle in the future:

Generate the package

When you generate the package, it will create the .extarchive file <last package name|default package name>.extarchive which can then be uploaded into your CAST Extend local server/Offline instance. You must define a folder where the archive file will be placed and the folder must exist already:

ExtendCli.exe bundle pack -o "C:\PRODUCT\Extend Offline\My package"

Navigate to the folder you have defined as output (in the above example the path is C:\PRODUCT\Extend Offline\My package) - it will contain the generated .extarchive file that you can upload into your CAST Extend local server/Offline instance by following the steps described in Upload the bundle to CAST Extend local server or Upload the bundle to CAST Extend Offline:

Advanced configuration settings - appsettings.json

Some additional advanced settings can be configured using the following file which can be edited with a text editor:

Downloadable tool
<extend_cli_unzip_folder>\appsettings.json

Console ≥ 2.x Node
%PROGRAMFILES%\CAST\AIP-Node\bin\ExtendCli\appsettings.json

Console 1.x Node
%PROGRAMFILES%\CAST\AipConsole\AipNode\bin\ExtendCli\appsettings.json

Timeout

"Timeout": 10800

This setting (available in ≥ 2.1.1-funcrel) is specifically for those with very slow network connections. The value is in seconds (the default value is 10800, or 3 hrs) and should only be increased if you are facing timeouts when fetching data from CAST Extend, i.e. when the total time required for CAST Extend to build the bundle and then for ExtendCli to download it exceeds 3 hrs. CAST does NOT recommend decreasing this value.

SettingsPath

"SettingsPath": null

This setting (available in ≥ 2.1.1-funcrel) is set by default to %PROGRAMDATA%\CAST\ExtendCLI and defines where the current instance of ExtendCli will store configuration settings and cache files. If you need to run multiple instances of ExtendCli on one machine, and you want to ensure clear separation of data between each instance, you can define a custom path for the configuration data using this option. For example to set the path to D:\CAST\temp\ExtendCli:

"SettingsPath": "D:\\CAST\\temp\\ExtendCli"