Using ExtendCli

Overview

Extend Local Server is delivered “empty” without any preconfigured extensions and in offline mode (i.e. in a secure environment without a connection to https://extend.castsoftware.com ) you will need to populate Extend Local Server with extensions manually. In addition, you may want to update Extend Local Server to add new extensions or to include more recent releases of extensions. ExtendCli is a command line tool designed to perform this job and is explained in detail below.

Where can I 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 in the following location:

%PROGRAMFILES%\CAST\Imaging\CAST-Imaging-Analysis-Node\bin\ExtendCli\ExtendCli.exe

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]

Note that before using ExtendCli with the bundle, download and install commands, you MUST first set the following two values with the config command:

ExtendCli.exe config set extend-url https://extend.castsoftware.com
ExtendCli.exe config set api-key <your_api_key>

See the examples below.

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:

You can determine the <extension_id> of a given extension using the CAST Extend website :

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:

Option	Description	Command line	Comment	Example of command line
set	Setup the CAST Extend (online) connection parameters.	ExtendCli.exe config set <api-key>	<api-key> is specific to a login for CAST Extend (online). You can find this in your profile. Note that this command only needs to be used once (unless you decide to use a different api-key for an alternative CAST Extend (online) login).	extendCli.exe config set api-key w9876xyz-d999-32ii-9fb0-0123c5
		ExtendCli.exe config set [extend-url]	[extend-url] refers to the URL to use for CAST Extend (online). When no option is provided, the default value is used: https://extend.castsoftware.com . Note that this command only needs to be used once (unless you decide to use a different URL).	extendCli.exe config set extend-url "your URL"
		ExtendCli.exe config set [storage-dir]	[storage-dir] refers to the location where extension packages will be downloaded to when using the download option. When no option is provided, the default value is used: %PROGRAMDATA%\CAST\ExtendCLI\packages If ExtendCli is being run using the executable provided with a Node, then the default storage location is set to: C:\ProgramData\CAST\Imaging\CAST-Imaging-Analysis-Node\ExtendCliConfig\packages	extendCli.exe config set storage-dir C:\CAST\temp
		ExtendCli.exe config set [proxy] <proxy_address>	Where possible ExtendCli.exe config proxy <proxy_address> [-options] introduced in 3.0.0 should be used instead. [proxy] is optional. It should be used: when your network environment uses a proxy for internet access. when the machine you are running ExtendCli on does not have operating system level proxy settings enabled. The syntax is as follows: ExtendCli.exe config set proxy <protocol://[user:password@]host[:port]> Note that if you are using the Use setup script option (1), CAST also recommends enabling the Automatically detect settings option (2):	extendCli.exe config set proxy http://proxy_user:proxy_password@proxy.corp.com:3128
proxy	Configure a connection via a proxy (available in ≥ 3.0.0)	ExtendCli.exe config proxy <proxy_address> [-options]	This option should be used instead of ExtendCli.exe config set [proxy] where possible. when your network environment uses a proxy for internet access. and when the machine you are running ExtendCli on does not have operating system level proxy settings enabled. The syntax is as follows: ExtendCli.exe config proxy <protocol://host[:port]> [-options] The following options are available: -b | --bypass-on-local > Do not use the configured proxy settings for local requests. >-c | --default-credentials > Use the current Microsoft Windows account to authenticate with the proxy server. -i | --bypass > Specifies one single address that will not use the proxy. Can be used multiple times in a command. -u | --username > Specifies the username to authenticate with the proxy server if authentication is required. -p | --password > Specifies the password for the username used to authenticate with the proxy server if authentication is required. <li>-d | --domain > Specifies the domain for domain restricted proxy servers. -r | --reset > Will reset any previously configured proxy settings, i.e. when using ExtendCli commands in a batch file or consecutively in a CMD window. Note that if you are using the Use setup script option (1), CAST also recommends enabling the Automatically detect settings option (2) as shown in the image above.	ExtendCli.exe config proxy http://proxy.corp.com:3128 ExtendCli.exe config proxy http://proxy.corp.com:3128 -c ExtendCli.exe config proxy http://proxy.corp.com:3128 -u my_user -p my_password ExtendCli.exe config proxy http://proxy.corp.com:3128 -u my_user -p my_password -i http://some.address.com -i http://some.other.address.com -i *:8080 -i https://*:*

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\Imaging\CAST-Imaging-Analysis-Node\ExtendCliConfig\packages

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

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

An integrity check is only performed if the source server generates a hash code. When using the install command, ExtendCLI will automatically verify each extension using a unique SHA256 hash code generated by the source 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 the integrity check fails again, please contact CAST Support.

uninstall

Use this option to specify an extension that you have downloaded to your machine and that you now want to remove from your machine:

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 one extension to package

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

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:

ExtendCli.exe bundle export "C:\PRODUCT\Extend\ExtendCli\save_test\mylastbundle"

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 Extend Local Server. 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\My package"

Navigate to the folder you have defined as output (in the above example the path is C:\PRODUCT\Extend\My package) - it will contain the generated .extarchive file that you can upload into your Extend Local Server by following the steps described Update Extend Local Server with new content.

If you are packing extensions to use with a Linux deployment of CAST Imaging, use the following command instead:

Extendcli.exe bundle pack -o <FOLDER_PATH> -p linux_x64 -f

Advanced configuration settings - appsettings.json

Some additional advanced settings can be configured using the following file:

Downloadable tool:
<extend_cli_unzip_folder>\appsettings.json

Provided with the Node:
%PROGRAMFILES%\CAST\Imaging\CAST-Imaging-Analysis-Node\bin\ExtendCli\appsettings.json

Timeout

"Timeout": 10800

This setting 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 is set by default to %PROGRAMDATA%\CAST\Imaging\CAST-imaging-analysis-node\ExtendCliConfig 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"

Paths must conform to the following syntax:

• Enclosed in double quotes
• Absolute path (not relative)
• Back slashes are required (forward slashes not accepted) and must be escaped with a back slash