Summary: Information about ExtendCli, a command line tool to create and manage bundles for CAST Extend local server / CAST Extend Offline.
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
- ExtendCli does not replace CAST Extension Downloader - a tool used to download Extensions from CAST Extend (live or offline).
- All dependent extensions of a given extension will be included when using ExtendCli.
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 | Supported by reference |
---|---|---|
Microsoft Windows 8 64-bit | ||
Microsoft Windows 8.1 64-bit | ||
Microsoft Windows 10 64-bit | ||
Microsoft Windows Server 2008 R2 SP1 64-bit (Standard edition) | ||
Microsoft Windows Server 2012 64-bit (Standard edition) | ||
Microsoft Windows Server 2012 R2 64-bit (Standard edition) | ||
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:
You can determine the <extension id> of a given extension using the CAST Extend website:
Option | Description | Command line | Comment | Example of command line |
---|---|---|---|---|
add | Add extensions to the active bundle. | ExtendCli.exe bundle add <extension id> [options] | When no option is provided, the most recent stable release of the extension is taken. Note that [options] can be cumulative. | ExtendCli.exe bundle add com.castsoftware.reactjs |
ExtendCli.exe bundle add <extension id> -D ExtendCli.exe bundle add <extension id> --skip-dependencies | Skip extension dependencies. | ExtendCli.exe bundle add com.castsoftware.reactjs -D | ||
ExtendCli.exe bundle add <extension id> -S ExtendCli.exe bundle add <extension id> --latest-stable | Add most recent stable version (LTS or Funcrel). | ExtendCli.exe bundle add com.castsoftware.reactjs -S | ||
ExtendCli.exe bundle add <extension id> -a ExtendCli.exe bundle add <extension id> --absolute-latest | Add absolute latest version (including alpha and beta releases). | ExtendCli.exe bundle add com.castsoftware.reactjs -a | ||
ExtendCli.exe bundle add <extension id> -f ExtendCli.exe bundle add <extension id> --latest-funcrel | Add latest funcrel release. | ExtendCli.exe bundle add com.castsoftware.reactjs --latest-funcrel | ||
ExtendCli.exe bundle add <extension id> -l ExtendCli.exe bundle add <extension id> --latest-lts | Add latest LTS release. | ExtendCli.exe bundle add com.castsoftware.reactjs --latest-lts | ||
ExtendCli.exe bundle add <extension id> -v ExtendCli.exe bundle add <extension id> --version | Add a specific release of the extension. | ExtendCli.exe bundle add com.castsoftware.reactjs --version 1.1.0-funcrel | ||
clear | Clear your bundle. | ExtendCli.exe bundle clear | - | ExtendCli.exe bundle clear |
download | Download extensions in the current bundle as .nupkg files | ExtendCli.exe bundle download [options] | - | ExtendCli.exe bundle download |
ExtendCli.exe bundle download -o | --outdir "<path>" | In < 1.1.0-funcrel, the specified folder must already exist. In ≥ 1.1.0-funcrel, the folder will be created if it does not exist. | ExtendCli.exe bundle download -o "C:\temp" | ||
export | Export the content of the bundle into another .json file. | ExtendCli.exe bundle export <file path> | - | ExtendCli.exe bundle export "C:\mybundle.json" |
import | Import the content of an existing exported .json file into your bundle. | ExtendCli.exe bundle import <file path> | - | ExtendCli.exe bundle import "C:\mybundle.json" |
list | List the extension versions/releases in your bundle. | ExtendCli.exe bundle list | - | ExtendCli.exe bundle list |
pack | Create an .extarchive file from your bundle that can be imported into CAST Extend Offline. | ExtendCli.exe bundle pack [options] | - | ExtendCli.exe bundle pack |
ExtendCli.exe bundle pack -o "<path>" | Target folder where the archive will be saved. This folder must already exist. | ExtendCli.exe bundle pack -o "C:\Temp\Bundles" | ||
ExtendCli.exe bundle pack -d | Only downloads missing extensions, will not create an archive. | ExtendCli.exe bundle pack -d | ||
template | Manage predefined bundles. | ExtendCli.exe bundle template <command><options> | Manage predefined templates available in CAST Extend and include them in your extension. | - |
ExtendCli.exe bundle template add product | community | labs | <template id> | Allows the addition of the absolute latest version (including alpha and beta releases) of all official / community / labs / or specific predefined bundle of extensions into a template bundle. Available in ≥ 1.1.0-funcrel. | ExtendCli.exe bundle template add product ExtendCli.exe bundle template add community ExtendCli.exe bundle template add labs ExtendCli.exe bundle template add 14 | ||
ExtendCli.exe bundle template add product | community | labs | <template id> -s | --latest-stable ExtendCli.exe bundle template add product | community | labs | <template id> -a | --absolute-latest ExtendCli.exe bundle template add product | community | labs | <template id> -f | --latest-funcrel ExtendCli.exe bundle template add product | community | labs | <template id> -l | --latest-lts | Allows the addition of all official / community / labs / or specific predefined bundle of extensions into a template bundle AND allows you to specify the release of extensions you require:
Available in ≥ 3.0.0-funcrel. | ExtendCli.exe bundle template add product --latest-stable ExtendCli.exe bundle template add community --absolute-latest ExtendCli.exe bundle template add labs --latest-funcrel ExtendCli.exe bundle template add 14 --latest-lts | ||
ExtendCli.exe bundle template list | Lists the seven predefined bundles:
| ExtendCli.exe bundle template list | ||
ExtendCli.exe bundle template content <template Id> | Displays the content of one predefined bundle. | ExtendCli.exe bundle template content 17 |
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-0123cde45 |
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:
If ExtendCli is being run using the executable provided with a Node, then the default storage location is set to:
| 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:
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.
The syntax is as follows: ExtendCli.exe config proxy <protocol://host[:port]> [-options] The following options are available:
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 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\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>
Option | Description | Command line | Example of command line |
---|---|---|---|
-d | --skip-dependencies | This option allows you to download an extension without any dependencies. CAST only recommends using this option if you understand the implication - an extension will not function correctly without its dependencies. | ExtendCli.exe download -d <extension id> ExtendCli.exe download --skip-dependencies <extension id> | ExtendCli.exe download -d com.castsoftware.reactjs |
-s | --latest-stable <true|false> | This option allows you to configure whether to download the most recent stable release of an extension (-LTS or funcrel). The default behaviour (i.e. when the option is omitted) the action is set to true and the latest-stable release will be downloaded. Explicitly add the option and set it to false to ensure that the latest stable release is not downloaded. | ExtendCli.exe download -s false <extension id> ExtendCli.exe download --latest-stable false <extension id> | ExtendCli.exe download -s false com.castsoftware.reactjs |
-a | --absolute-latest | This option allows you to download the most recent release of an extension including alpha and beta releases and all dependencies. | ExtendCli.exe download -a <extension id> ExtendCli.exe download --absolute-latest <extension id> | ExtendCli.exe download -a com.castsoftware.reactjs |
-f | --latest-funcrel | This option allows you to download the most recent funcrel release of an extension and all dependencies. | ExtendCli.exe download -f <extension id> ExtendCli.exe download --latest-funcrel <extension id> | ExtendCli.exe download -f com.castsoftware.reactjs |
-l | --latest-lts | This option allows you to download the most recent LTS release of an extension and all dependencies. | ExtendCli.exe download -l <extension id> ExtendCli.exe download --latest-lts <extension id> | ExtendCli.exe download -l com.castsoftware.reactjs |
-v | --version | This option allows you to download a specific release of an extension and all dependencies. | ExtendCli.exe download -v <release><extension id> ExtendCli.exe download --version <release><extension id> | ExtendCli.exe download -v 1.1.4-funcrel com.castsoftware.reactjs |
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):
install | <extensionId> [--version <version>] [--ignore-dependencies] [--username <username>] [--password <password>] | Use this option to specify an extension that you want to download on to your local machine. Note that you may also need to specify the --username and --password options if the remote server requires authentication
|
SHA256 data integrity checks
- Available in ≥ 3.1.0.
- An integrity check is only performed if the source Extend 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 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
uninstall | extensionId [--version <version>] | Use this option to specify an extension that you have downloaded to your machine and that you now want to remove from your machine:
Note that:
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 api key:
extendCli.exe config set api-key w9876xyz-d999-32ii-9fb0-0123cde45
Set the CAST Extend URL:
ExtendCli.exe config set extend-url "Your URL"
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"
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