ExtendCli

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) and is 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.

An interface exists in CAST Extend (the live version available at https://extend.castsoftware.com) to create a new "bundle" containing the extensions you require, however, this interface only allows official CAST AIP extensions (known as "product" extensions) to be included. As a result, the ExtendCli tool has been developed to allow the integration of User Community and Labs extensions, as well as Product extensions (see Contributor types for more information about the types of extensions that are available) into CAST Extend local server/Offline.

ExtendCli does not replace CAST Extension Downloader - a tool used to download Extensions from CAST Extend (live or offline).
CAST recommends using the interface available in https://extend.castsoftware.com to create new bundles for "product" extensions - see also: Update CAST Extend local server with new content / Update CAST Extend Offline with new content
All predefined bundles available in https://extend.castsoftware.com can also be packaged using ExtendCli.
All dependent extensions of a given extension will be included when using ExtendCli.

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

Using ExtendCli

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

open a command prompt, and run the tool from where the tool is located
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
download	Download extensions in the current bundle as .nupkg files	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	Allows the addition of all production extensions into a template bundle. Available in ≥ 1.1.0-funcrel.	ExtendCli.exe bundle template add product
		ExtendCli.exe bundle template add <template id>	The template id refers to one of the predefined bundles available in CAST Extend.	ExtendCli.exe bundle template add 14
		ExtendCli.exe bundle template list	Lists the seven predefined bundles: Id = 1 → All product extensions (note that this is deprecated from ≥ 1.1.0-funcrel - you should use "product" instead) Id = 4 → Microsoft .NET Id= 5 → Mobile Id = 6 → Web Id = 14 → Data Id = 16 → Java / JEE Id = 17 → Security (this bundle provides support for Security analysis for all technologies) Id = product (from ≥ 1.1.0-funcrel) Id = labs (from ≥ 1.1.0-funcrel) Id = community (from ≥ 1.1.0-funcrel)	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
set	Setup the CAST Extend (online) connection parameters.	ExtendCli.exe config set [extend-url]	[extend-url] is optional. It 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"

download

This option allows you to download an extension in .nupkg format:

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	This option allows you to download the most recent stable release of an extension, for example LTS or funcrel and all dependencies.	ExtendCli.exe download -s <extension id> ExtendCli.exe download --latest-stable <extension id>	ExtendCli.exe download -s 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

Option	Description
<extensionId>	This option allows you to specify a particular extension for download using its ID - this is a mandatory option. The ID of a CAST AIP extension always takes the form com.castsoftware.<name>, without any version numbers. Note that the most recent versions of an extension's dependencies will always be downloaded alongside the extension, unless you are using the [--ignore-dependencies] option - see below.
[--version <version>]	This option allows you to specify a specific version of the extension for download using its version number. This option is not mandatory. When not included, the most recent version of the extension you require will always be downloaded.
[--ignore-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. This option is not mandatory. When not included, the most recent versions of an extension's dependencies will always be downloaded.
[--username <username>] [--password <password>]	When connecting to a server that requires authentication (for example https://extend.castsoftware.com:443/api) to download an extension (with the install option), use these two options to specify your credentials. You will require an account on the remote server to authenticate when using CAST Extend. You can find out about registering for an account in CAST Extend website.

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:

Option	Description
extensionId	This option allows you to specify a particular extension for removal using its ID - this is a mandatory option. The ID of a CAST AIP extension always takes the form com.castsoftware.<name>, without any version numbers.
[--version <version>]	This option allows you to specify a specific version of the extension for download using its version number. This option is not mandatory. When not included, the most recent version of the extension you require will always be deleted from your machine.

Note that:

removing an extension will only delete the extension files on the local machine. It does not remove the extension from any CAST AIP databases/schemas that it has been installed to.
removing an extension only removes the specific extension. Any dependencies are left on the machine as other extensions may require them.
removing an extension from your machine will cause the following log message to be displayed in CAST Server Manager when CAST AIP databases/schemas that use the extension are detected:

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

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:

Page tree