Automation - Command Line Interface (CLI)

Overview

The CAST Imaging CLI (Command Line Interface) automation tool enables automated application analysis through the CAST Imaging API, eliminating the need for manual interaction with the UI. The Command Line Interface automation tool supports the following operations:

initial fast scan (process source code without running analysis)
deep analysis and results publication in Viewer/Dashboards (fast scans must be completed)
results publication in Viewer/Dashboards (deep analysis must be completed)
application onboarding (all operations listed above in one)
transaction configuration actions on fully analyzed results (not included in application onboarding operation)
export application action on an existing application (not included in application onboarding operation)
import application action on an existing file created by running export application (not included in application onboarding operation)

Fully compatible with both Microsoft Windows and Linux via Docker installations of CAST Imaging v3. The Command Line Interface automation tool itself can also be run as a Docker container - see Running the Command Line Interface with Docker.

Requirements

Software

Java Runtime Environment (JRE) or Java Development Kit (JDK): Version 8 or higher. Not required when you run the tool with Docker.

CAST Imaging installation

Before using the Command Line Interface, ensure you have:

CAST Imaging installation: A properly configured and accessible CAST Imaging v3 instance - see Global installation guide for CAST Imaging 3.x
API Token: API access via the Command Line Interface tool requires authentication using a user-specific API key. Generate a key using the CAST Imaging UI in the Profile section.
Source code preparation: Prepare your source code for analysis using one of these methods:
- Archive file (.zip or tar.gz)
- Path pointing to a Source Folder Location configured in the CAST Imaging UI

Where can I get the Command Line Interface automation tool?

The Command Line Interface automation tool is provided in an extension which you can download from CAST Extend

Unzip the extension anywhere on your local disk. The Command Line Interface tool is provided as aip-console-tools-cli.jar.

The tool is also provided as a Docker image on Docker Hub , which includes the Java runtime - see Running the Command Line Interface with Docker.

The com.castsoftware.aip.console.tools extension and the Docker image are versioned and you must always use the specific release that matches the release of CAST Imaging you are currently running.

What’s new?

See the com.castsoftware.aip.console.tools release notes.

Where should I run the Command Line Interface automation tool?

You can run the Command Line Interface automation tool:

on the machine on which the CAST Imaging imaging-services component is installed
on any machine that has network access to the machine where the CAST Imaging imaging-services component is installed

All parameters which take a value (i.e. --apikey) can use either of the following syntaxes:

--parameter="value"
--parameter value CAST recommends using --parameter="value" to ensure any special characters or white spaces are correctly interpreted.

Fast-Scan / FastScan

Creates a new application or updates an existing one
Performs the initial source code fast scan for a new application or refreshes source code content for an existing application

java -jar .\aip-console-tools-cli.jar Fast-Scan --apikey="valid.key" --app-name="my app" -L="<license key for my app>" --domain-name="Your Domain" --file-path="C:\folder\some-location\sources-file.zip" --sleep-duration="2" --exclude-patterns="tmp/, temp/, *test, tests, target/, .svn/, .git/, _Macosx/, test/"

Parameters

The following parameters are specific to the command. Other parameters are listed in Common parameters below.

Parameter	Aliases	Required	Description
`--domain-name`	-	❌	Domain name for organizing applications (created if does not exist)
`--exclude-patterns`	`-exclude`	❌	Comma-separated glob patterns for file exclusion, e.g. `tmp/, temp/`
`--exclusion-rules`	-	❌	Comma-separated project exclusion rules. See Exclusion rules below.
`--file-path`	`-f`	✅	Path to local `.zip` or `tar.gz` file, e.g. `C:\folder\some-location\sources-file.zip` / `/home/user/folder/sources-file.zip` or path to a source folder location defined in the UI `S:\some-share\` / `/opt/cast/shared/common-data/<some-folder>`. See Configuring source code delivery from a folder.
`--exclusion-templates`	`-templates`	❌	Comma-separated exclusion template names to apply in addition to `--exclude-patterns`.
`--node-name`	-	❌	Target analysis node name for application creation.
`--license`	`-L`	❌	The application’s license is required for the first onboarding when license strategy is set to: Named Application License.

Exclusion rules

The --exclusion-rules parameter accepts the following comma-separated mnemonics (no spaces):

Mnemonic	Description
`EXCLUDE_EMPTY_PROJECTS`	Exclude all empty projects
`PREFER_FULL_DOT_NET_TO_BASIC_DOT_NET_WEB`	Exclude ASP .NET web projects when a Visual C#/Basic .NET project also exists
`PREFER_DOT_NET_WEB_TO_ASP`	Exclude ASP projects when a .NET web project also exists
`PREFER_FULL_JAVA_PROJECTS_TO_BASIC_JSP`	Exclude basic JSP projects when a full JEE project exists for the same web.xml file
`PREFER_MAVEN_TO_ECLIPSE`	Exclude Eclipse Java projects when a Maven project also exists
`PREFER_ECLIPSE_TO_MAVEN`	Exclude Maven Java projects when an Eclipse project also exists
`EXCLUDE_EMBEDDED_ECLIPSE_PROJECTS`	Exclude Eclipse projects inside the output folder of another Eclipse project
`EXCLUDE_ECLIPSE_PROJECT_WITH_DUPLICATED_NAME`	Exclude Eclipse projects with duplicate names
`EXCLUDE_DUPLICATE_DOT_NET_PROJECT_IN_SAME_FOLDER`	Exclude duplicate .NET projects in the same source folder
`EXCLUDE_TEST_CODE`	Exclude test code

Example:

--exclusion-rules="EXCLUDE_EMPTY_PROJECTS,PREFER_FULL_DOT_NET_TO_BASIC_DOT_NET_WEB,PREFER_DOT_NET_WEB_TO_ASP,PREFER_FULL_JAVA_PROJECTS_TO_BASIC_JSP,PREFER_MAVEN_TO_ECLIPSE,EXCLUDE_EMBEDDED_ECLIPSE_PROJECTS,EXCLUDE_ECLIPSE_PROJECT_WITH_DUPLICATED_NAME,EXCLUDE_DUPLICATE_DOT_NET_PROJECT_IN_SAME_FOLDER,EXCLUDE_TEST_CODE"

Deep-Analyze / DeepAnalyze

Executes a deep analysis on an existing application with delivered source code (fast scan must be completed)
Publishes results in Viewer and Dashboards (can be disabled)

java -jar .\aip-console-tools-cli.jar Deep-Analyze --apikey="valid.key" --app-name="my app" --enable-security-dataflow --module-option="one_per_au" --objectives="BLUEPRINT,DATA_SAFETY_CHECKS_GDPR,DATA_SAFETY_CHECKS_PCI" --sleep-duration="2" --timeout="5000" --custom-maven-dependency=true --maven-dependency-depth=2 --maven-dependency-max-artifact-before-loop-factor=10 --maven-dependency-max-artifacts-factor=3

Parameters

The following parameters are specific to the command. Other parameters are listed in Common parameters below.

Parameter	Aliases	Required	Description
`--enable-security-dataflow`	`--security-dataflow`	❌	Activates security dataflow for the application. Omit to preserve the already configured value.
`--module-option`	-	❌	Generates a user defined module option for either technology module or analysis unit module. Possible value is one of: `full_content`, `one_per_au`, `one_per_techno`. The default value is: `full_content`.
`--objectives`	-	❌	Comma-separated objectives: `DATA_SAFETY`, `BLUEPRINT`, `DATA_SAFETY_CHECKS_GDPR`, `DATA_SAFETY_CHECKS_PCI`. Values are case-insensitive.
`--process-imaging`	-	❌	`true\|false`: publish results to Viewer. The default value is: `true`. When used without a value, the parameter defaults to `true`.
`--publish-engineering`	-	❌	`true\|false`: publish results to Dashboards. The default value is: `true`. When used without a value, the parameter defaults to `true`.
`--snapshot-name`	`-S`	❌	Defines the name of the snapshot to create/re-generate. A default value is used if the parameter is omitted.
`--custom-maven-dependency`	-	❌	Only use this flag when application should run with dedicated Maven dependency settings. This option can be use alone to indicate whether application should use its own settings (true) or not (false).
`--maven-dependency-depth`	-	❌	Maximum depth of transitive Maven dependencies to extract. If not specified, the AIP Console default is used.
`--maven-dependency-max-artifacts-factor`	-	❌	Factor used to compute the maximum number of Maven artifacts to extract. If not specified, the AIP Console default is used.
`--maven-dependency-max-artifact-before-loop-factor`	-	❌	Factor used to compute the maximum number of artifacts allowed before a dependency loop is detected. If not specified, the AIP Console default is used.

While setting maven-dependency-xxx options consider following:

The command can be run without any of them to let the server configured options take place.
only --custom-maven-dependency parameter can be use alone when required.
All three others parameters should be set in the same time.
The configuration is only updated after the first deep-Analyze command.
Options will be take into account during the next incoming JEE packaging process

Onboard-Application / OnboardApplication

Performs the following actions in one go:

Fast-Scan
Deep-Analyze

java -jar .\aip-console-tools-cli.jar Onboard-Application --apikey="valid.key" --app-name="my app" --file-path="zip file full path" --domain-name="Your Domain" --snapshot-name="snapshot name" --sleep-duration="5" --module-option="one_per_techno"

Parameters

All parameters for the Fast-Scan and Deep-Analyze commands are available and described above. Other parameters are listed in Common parameters below.

Publish-Imaging / PublishImaging

Publishes an existing analyzed application’s results to Viewer and/or Dashboards.

java -jar .\aip-console-tools-cli.jar Publish-Imaging --apikey="valid ApiKey" --server-url="URL" --app-name="my app" --upload-application --process-imaging=true --verbose=true --sleep-duration=1

Parameters

The following parameters are specific to the command. Other parameters are listed in Common parameters below.

Parameter	Aliases	Required	Description
`--process-imaging`	-	❌	`true\|false`: trigger Generate Views step and upload application to CAST Imaging Viewer. Default: `true`. When used without a value, the parameter defaults to `true`.
`--publish-engineering`	-	❌	`true\|false`: upload and publish results to Dashboards. Default: `false`. When used without a value, the parameter defaults to `true`.
`--upload-application`	-	❌	`true\|false`: when `false`, prevents consolidating snapshot or publishing to Management Dashboard. Default: `false`. When used without a value, the parameter defaults to `true`.

Delete-Application / delete

Available in ≥ 3.6.4-funcrel

Deletes an existing application that the user has been granted access to.

java -jar .\aip-console-tools-cli.jar delete --server-url="Imaging Console URL" --apikey="valid API Key" --app-name="application name" --sleep-duration=30 --timeout=10000 --verbose=true

Parameters

The following parameters are specific to the command. Other parameters are listed in Common parameters below.

Parameter	Aliases	Required	Description
`--retain-backup-data`	`-retain-backup`	❌	Keeps any existing backup data files associated with the application. When used without a value, the parameter defaults to `true`.
`--retain-css-data`	`-retain-css`	❌	Keeps application data files such as delivery folder, triplets schemas and deploy folder. When used without a value, the parameter defaults to `true`.

export-application / export

Available in ≥ 3.6.7-funcrel

Exports an existing application data that user has been granted access to

java -jar .\aip-console-tools-cli.jar export --server-url="Imaging Console URL" --apikey="valid API Key" --app-name="application name" --output="optional folder where to store application data" --sleep-duration=30 --timeout=10000 --verbose=true

Parameters

The following parameters are specific to the command. Other parameters are listed in Common parameters below.

Parameter	Aliases	Required	Description
`--app-name`	`-n`	❌	The Name of the application to export.
`--output-path`	`--output` `-o`	❌	(optional) Provide a folder path where to store the exported application result file. The exported file is stored in the current folder when this option is missing.

import-application / import

Available in ≥ 3.6.7-funcrel

Import an existing application data file (already exported using export command) into Imaging Console.

java -jar .\aip-console-tools-cli.jar import --server-url="Imaging Console URL" --apikey="valid API Key" --file-path="full path to exported application data file" -css="target database connection" --sleep-duration=30 --timeout=10000 --verbose=true

Parameters

The following parameters are specific to the command. Other parameters are listed in Common parameters below.

Parameter	Aliases	Required	Description
`--file-path`	`-f`	❌	A full file path to imaging export file representing the already exported application data file (with respect to the original format and contents).
`--css-server`	`-css`	❌	(optional) PostgreSQL instance that will host the application data: Format will be host:port/databaseName and can be checked on Imaging Console’s Global Configuration page.

TCC

Performs transaction configuration actions on fully analyzed results. This command requires sub commands (listed below) to specify which action to take.

Parameters

All parameters for the TCC command are listed in Common parameters below unless specified below in Sub commands.

Sub commands

The following subcommands are available (at least one must be used with TCC):

compute-function-points
compute-transactions
list-rules
check-content
check-all-content
view-settings
update-settings

compute-function-points

Compute function points for an application.

Additional parameters:

--wait / --no-wait (optional): Wait for computation to complete.

Example:

$ java -jar ./aip-console-tools-cli.jar TCC compute-function-points --apikey="valid.key" --app-name="my app" --wait

compute-transactions

Compute transactions for an application.

Additional parameters:

--wait / --no-wait (optional): Wait for computation to complete

Example:

$ java -jar ./aip-console-tools-cli.jar TCC compute-transactions --apikey="valid.key" --app-name="my app" --wait

list-rules

List available configuration rules, optionally filtered by type.

Additional parameters:

--ruleType="value" (optional): Filter rules by specific type

Examples:

# List all rules
$ java -jar ./aip-console-tools-cli.jar TCC list-rules --apikey="valid.key" --app-name="my app"

# List rules by type
$ java -jar ./aip-console-tools-cli.jar TCC list-rules --apikey="valid.key" --app-name="my app" --ruleType="Data Functions"

check-content

View content for a specific rule.

Additional parameters:

--rule="value" (required): Rule ID to inspect

Example:

$ java -jar ./aip-console-tools-cli.jar TCC check-content --apikey="valid.key" --app-name="my app" --rule="121"

check-all-content

View content for all rules of a specific type.

Additional parameters:

--ruleType="value" (optional): Rule type to inspect

Example:

$ java -jar ./aip-console-tools-cli.jar TCC check-all-content --apikey="valid.key" --app-name="my app" --ruleType="entry"

view-settings

Display function point computation settings with current and possible values.

Example:

$ java -jar ./aip-console-tools-cli.jar TCC view-settings --apikey="valid.key" --app-name="my app"

update-settings

Update function point computation settings.

Additional parameters:

--new-settings (required): Comma-separated setting="value" pairs

Example:

$ java -jar ./aip-console-tools-cli.jar TCC update-settings --apikey="valid.key" --app-name="my app" --new-settings="FILTER_LOOKUP_TABLES=true,DF_DEFAULT_TYPE=EIF"

Common parameters

Each command listed above has a set of common parameters as follows:

Parameter	Aliases	Required	Description
`--help`	`-h`	❌	Display help message and exit.
`--apikey` / `--apikey:env`	-	✅	API Key for authentication OR environment variable name containing the API key. Generate a key using the CAST Imaging UI in the Profile section.
`--initial-retry-interval`	-	❌	Initial interval between retries in milliseconds (specified with `--max-retries`). The default value is: 1000.
`--max-retries`	-	❌	Maximum number of retry attempts to reconnect to CAST Imaging. The default value is: 5.
`--app-name`	`-n`	✅	Application name to create or existing application name.
`--server-url`	`-s`	❌	CAST Imaging URL and port, with http/https protocol (default: `http://localhost:8090`).
`--sleep-duration`	-	❌	Polling interval in seconds for job status (default: 1s).
`--timeout`	-	❌	The timeout in seconds for calls to CAST Imaging. The default value is: 90s.
`--user`	-	❌	(Deprecated) Username for authentication. Use `--apikey` instead.
`--version`	`-V`	❌	Print version information and exit.
`--verbose`	-	❌	`true\|false`: whether the command log should be output to the console or not, defaults to `true` if omitted.

Exit codes

The Command Line Interface returns specific exit codes to indicate execution status:

Code	Status	Description
0	Success	Processing completed successfully (also returned for `--help` and `--version`)
1	Authentication Error	API key missing (not provided in command or environment variable)
2	Login Error	Unable to authenticate with provided API key
3	Upload Error	Error occurred during upload to CAST Imaging
4	Job Creation Error	Failed to create Add Version job or retrieve job status
5	Job Failed	Add Version job terminated in unexpected state
6	Missing Parameter	Application name or GUID not provided
7	Application Not Found	Specified application name or GUID doesn’t exist
8	Source Folder Not Found	Source folder not found on the analysis node
9	No Version	Application has no version for the requested operation
10	Version Not Found	Specified version doesn’t exist or no version matches request criteria
1000	Unexpected Error	Unhandled error occurred (check output for details)

Running the Command Line Interface with Docker

Available in ≥ 3.6.8-funcrel

The Command Line Interface automation tool is also provided as a Docker image on Docker Hub:

castimaging/console-automation-tool:<version>

<version> is the release of the com.castsoftware.aip.console.tools extension, in the same format, e.g. castimaging/console-automation-tool:3.6.8. Always use the image tag that matches the release of CAST Imaging you are currently running.

The image contains aip-console-tools-cli.jar and the Java runtime it needs, so no Java installation is required on the machine. It is built on a hardened base image (no shell, no package manager) and runs as a non-root user (UID 65532).

All commands and parameters are identical to those of java -jar aip-console-tools-cli.jar described on this page - only the start of the command line changes.

Docker requirements

Docker Engine 20.10 or higher (Linux) or Docker Desktop (Microsoft Windows)
Network access from the machine running Docker to the CAST Imaging imaging-services component, and to Docker Hub to pull the image

General syntax

$ docker run --rm --pull always \
  [-e CAST_API_KEY] \
  [-v <local folder>:/sources] \
  [--user $(id -u):$(id -g)] \
  castimaging/console-automation-tool:<version> <command> [parameters]

Docker option	Required	Description
`--rm`	❌	Removes the container when the command ends.
`--pull always`	❌	Downloads the image again if a newer build of the same tag is available on Docker Hub.
`-e CAST_API_KEY`	❌	Passes the `CAST_API_KEY` environment variable of your shell to the container. Use it with the `--apikey:env=CAST_API_KEY` parameter so the API key does not appear on the command line.
`-v <local folder>:/sources`	❌	Makes a local folder available in the container as `/sources`. Required whenever the command reads or writes a local file (`--file-path` with a local archive, `export`, `import`).
`--user $(id -u):$(id -g)`	❌	Linux only: runs the container with your own user so it can write into the mounted folder. Required for `export`.
`<command> [parameters]`	✅	Any command listed in Available commands, with its parameters.

The exit code of docker run is the exit code of the command - see Exit codes.

API key

Use an environment variable rather than --apikey="...":

$ export CAST_API_KEY="<your API key>"
$ docker run --rm -e CAST_API_KEY castimaging/console-automation-tool:<version> <command> --apikey:env=CAST_API_KEY ...

-e CAST_API_KEY without a value copies the variable from your shell into the container.

Server URL

In a container, localhost refers to the container itself, not to your machine. Set --server-url to the host name or IP address of the CAST Imaging imaging-services component, e.g. --server-url="http://imaging-host:8090". On Linux, if CAST Imaging runs on the same machine, you can also add --network host to the Docker options.

Local files and folders

The container only sees the folders you mount with -v <local folder>:/sources. Inside the container, reference files by their path under /sources:

On your machine	Docker option	Value of `--file-path`
`/home/user/apps/sources-file.zip`	`-v /home/user/apps:/sources`	`/sources/sources-file.zip`
`C:\apps\sources-file.zip` (Docker Desktop)	`-v C:\apps:/sources`	`/sources/sources-file.zip`

Mount a folder, not a file. Mounting a file on /sources fails with Are you trying to mount a directory onto a file (or vice-versa)?.
Use an absolute path for the local folder. A relative path such as -v apps:/sources is read as the name of a Docker volume and fails with includes invalid characters for a local volume name.
No mount is needed when --file-path points to a Source Folder Location configured in the CAST Imaging UI: that path is read by CAST Imaging, not by the container.

File permissions (Linux)

The container runs as a non-root user (UID 65532). On Linux, this user cannot write into a folder owned by your own user, so export fails with:

java.io.FileNotFoundException: /sources/<application>_<date>.imagingexport (Permission denied)

Add --user $(id -u):$(id -g) to the Docker options: the container then runs with your user and group, and the exported file belongs to you. Commands that only read files (Fast-Scan, Onboard-Application, import) do not need it as long as the files are readable by all users.

Docker examples

The examples below use a local folder /home/user/apps that contains the source archive and receives the exported file. Replace <version> with the tag matching your CAST Imaging release. Set the API key once:

$ export CAST_API_KEY="<your API key>"

Onboard-Application

$ docker run --rm --pull always -e CAST_API_KEY -v /home/user/apps:/sources \
  castimaging/console-automation-tool:<version> Onboard-Application \
  --server-url="http://imaging-host:8090" --apikey:env=CAST_API_KEY \
  --app-name="my app" --file-path="/sources/sources-file.zip" --domain-name="Your Domain" \
  --snapshot-name="Snapshot1" --enable-security-dataflow --module-option="one_per_au" \
  --objectives="blueprint,data_safety_checks_gdpr,data_safety_checks_pci" \
  --process-imaging --publish-engineering --sleep-duration="5"

CAST Imaging keeps working on the application for a short time after Onboard-Application (or Deep-Analyze) returns. If you run export or delete immediately afterwards, it can fail with exit code 5: wait about one minute and run it again.

export-application / export

The exported file is written into the folder given with --output, which must exist. Use the mounted folder /sources, otherwise the file is lost when the container stops.

$ docker run --rm --pull always --user $(id -u):$(id -g) -e CAST_API_KEY -v /home/user/apps:/sources \
  castimaging/console-automation-tool:<version> export \
  --server-url="http://imaging-host:8090" --apikey:env=CAST_API_KEY \
  --app-name="my app" --output="/sources" --sleep-duration="5" --timeout="10000"

The file my app_<date>.imagingexport is then available in /home/user/apps.

Delete-Application / delete

delete does not read or write local files, so no folder needs to be mounted.

$ docker run --rm --pull always -e CAST_API_KEY \
  castimaging/console-automation-tool:<version> delete \
  --server-url="http://imaging-host:8090" --apikey:env=CAST_API_KEY \
  --app-name="my app" --sleep-duration="15" --max-retries="50" --timeout="10000"

Removing an application can take several minutes. The command checks the job status --max-retries times (default: 20), every --sleep-duration seconds. If it ends with exit code 5 while the removal is still in progress, increase --sleep-duration and/or --max-retries, as in the example above (up to about 12 minutes).

import-application / import

Mount the folder that contains the exported file and give its path under /sources. The application is created again with the name it had when it was exported.

$ docker run --rm --pull always -e CAST_API_KEY -v /home/user/apps:/sources \
  castimaging/console-automation-tool:<version> import \
  --server-url="http://imaging-host:8090" --apikey:env=CAST_API_KEY \
  --file-path="/sources/my app_<date>.imagingexport" --sleep-duration="5" --timeout="10000"

Running in a CI/CD pipeline

You can use the image directly in a pipeline job that has access to Docker. Store the API key in a masked or secret variable of your CI/CD tool and pass it with -e CAST_API_KEY and --apikey:env=CAST_API_KEY. Check the exit code of each docker run to stop the pipeline when a command fails.