How to automate your local code analyses

Overview

The CAST Imaging Analyzer tool is downloaded and installed on your local machine and allows you to analyze your source code locally in “UI mode” before uploading your results to CAST Imaging on Cloud. Bundled with this UI tool is an equivalent command line tool that CAST provides to allow you to automate your local analyses. Below is a description of the options available for this command line tool and an explanation of how to use it.

Where can I get the command line tool?

The command line tool can be found on your local machine after running the CAST Imaging Analyzer installer, in the following location:

%PROGRAMFILES%\CAST\CAST Imaging Analyzer\CAST-Imaging-CLI.exe

How can I list all command options?

Use the following command:

CAST-Imaging-CLI.exe -h

Then for each available option, you can run the -h command, for example:

CAST-Imaging-CLI.exe run -h

What can the command line tool do?

The tool has various operating modes/options, as described below:

Mode/Option	Description
`run`	Run a complete analysis on your chosen source code and upload the results to CAST Imaging on Cloud if you choose (this mode runs all other options listed below.)
`fastscan`	Run the `fastscan`step on your chosen source code and upload the results to CAST Imaging on Cloud if you choose. This is a source code “discovery” process where your source code will be scanned to determine the different languages, technologies and frameworks that are included, along with the number of files and the total number of code lines. This is not a full analysis.
`analysis`	Run the `analysis` step on your chosen source code and upload the results to CAST Imaging on Cloud if you choose. This is a full analysis and requires that you have already run the `fastscan` step.
`upload`	Runs the `upload` step to upload results of the `fastscan`and/or `analysis` steps to CAST Imaging on Cloud.

What is the difference between online and offline mode?

The command line tool can be run in two different ways, online (with internet access) and offline (without internet access):

online: All required analysis resources are automatically downloaded during the analysis. Results are automatically uploaded to your account in CAST Imaging on Cloud. This mode is the default and should be used where possible.
offline: All required analysis resources must already exist on the local machine. Results are not uploaded to CAST Imaging on Cloud and are retained in the output folder. This mode is recommended only for those that are working in a secure environment without internet access and can be enabled using the -of, --offline flag. See How to run local code analyses in offline mode.

What flags are available?

Flag	Description	Default value	Required?
`-h, --help`	Shows the help message and then exits.	-	❌
`-n, --name`	Defines the name of the application.	A randomly generated name	❌
`-o, --output`	Defines the folder where the results will be stored at the end of the process.	`%APPDATA%\CAST\CAST Imaging Analyzer\results\<application-name>`	❌
`-s, --source`	Defines the folder where the application source code is stored.	-	✔️
`-ak, --api-key`	The API key of the user that owns the application. An API key can be generated in CAST Imaging on Cloud by clicking the username in the upper right corner.	-	Required when uploading results to CAST Imaging on Cloud (online mode)
`-is, --imaging-server`	URL of CAST Imaging on Cloud.	`https://castimaging.io`	❌
`-cl, --clean-logs`	Reduces the number of log messages that are output.	Disabled	❌
`-nu, --no-upload`	Prevents any results from being uploaded to CAST Imaging on Cloud. Useful for testing the tool.	Disabled	❌
`-nb, --no-browser`	Prevents the default browser on the local machine from opening and displaying the results in CAST Imaging on Cloud.	Disabled	❌
`-of, --offline`	Forces the tool to function entirely without an internet connection and is recommended only for those that are working in a secure environment without internet access. Note that CAST extensions must already exist in `%PROGRAMDATA%\CAST\CAST-Imaging-CLI\carl\bin\extensions` or another location specified by `-sp, --storage-path`.	Disabled	❌
`-sp, --storage-path`	Used with `-of, --offline`, defines the location of the CAST extensions on the local disk. If not specified, the default value is used.	`%PROGRAMDATA%\CAST\CAST-Imaging-CLI\carl\bin\extensions`	❌
`-re, --rescan`	Defines the absolute path to `profiler\profiler-results.json` in the folder defined by the `-o, --output` flag from a previous `run` action and is used when you want to rerun the `run` action but do not want to reproduce all output files. For example when you want to define a new ignore patterns file.	-	❌
`-ip, --ignore-patterns`	Defines the absolute path to a text file (.txt) containing a list of ignore patterns, defining specific files and folders that should be excluded from the analysis. The ignore patterns are defined using glob pattern matching (see https://docs.oracle.com/javase/tutorial/essential/io/fileOps.html#glob). For example: `.txt` will exclude all files with the extension .txt `tests/` will exclude any folders named `tests` and everything inside them - e.g. `root_folder/tests`, `root_folder/another_folder/tests` `.Tests/` will exclude any folders whose name includes `.Tests` (for example `C:\Support\Delivery\Sample.Tests\sample\`) patterns starting with `/` will exclude starting only from the root folder. In other words, `/tests/` will exclude everything in the specific folder `root_folder/tests` but not `root_folder/another_folder/tests` Note that if a file called `ignore-patterns.txt` is placed in the root of the folder defined by `-s, –source`, any patterns defined in this file will be automatically taken into account. This file does not need to be defined by `-ip, –ignore-patterns`. The use of `-ip, –ignore-patterns` overrides the `ignore-patterns.txt` file and any patterns defined in it are ignored.	-	❌
`-es, --extend-server`	URL of an on premises CAST Extend server, i.e. for those that are not using https://extend.castsoftware.com. The option expects a URL, for example http://my-extend-server:8085.	https://extend.castsoftware.com	❌

Run mode example

Run a fastscan + analysis, store the results in a dedicated folder and then upload all results to CAST Imaging on Cloud:

CAST-Imaging-CLI.exe run -n "application1" -o "C:\CAST\cloud\application1\results1" -s "C:\CAST\source_code\application1" -ak "u9t2Dteq.1YYvvPCoMNp"

Run a fastscan + analysis, store the results in a dedicated folder, exclude some files/folders and then upload all results to CAST Imaging on Cloud:

CAST-Imaging-CLI.exe run -n "application1" -o "C:\CAST\cloud\application1\results1" -s "C:\CAST\source_code\application1" -ak "u9t2Dteq.1YYvvPCoMNp" -ip "C:\CAST\cloud\application1\exclusions.txt"

Rerun fastscan + analysis on a previous run results, without reproducing all output files, store the results in a dedicated folder, exclude some files/folders and then upload all results to CAST Imaging on Cloud:

CAST-Imaging-CLI.exe run -n "application1" -o "C:\CAST\cloud\application1\results2" -s "C:\CAST\source_code\application1" -ak "u9t2Dteq.1YYvvPCoMNp" -re "C:\CAST\cloud\application1\results2\profiler\profiler-results.json" -ip "C:\CAST\cloud\application1\exclusions_new.txt"

Fastscan mode example

Run a fastscan only, store the results in a dedicated folder and then upload all results to CAST Imaging on Cloud:

CAST-Imaging-CLI.exe fastscan -n "application2" -o "C:\CAST\cloud\application2\results1" -s "C:\CAST\source_code\application2" -ak "u9t2Dteq.1YYvvPCoMNp"

Rerun a fastscan on a previous run results, without reproducing all output files, store the results in a dedicated folder, exclude some files/folders and then upload all results to CAST Imaging on Cloud:

CAST-Imaging-CLI.exe fastscan -n "application2" -o "C:\CAST\cloud\application2\results2" -s "C:\CAST\source_code\application2" -ak "u9t2Dteq.1YYvvPCoMNp" -re "C:\CAST\cloud\application2\results2\profiler\profiler-results.json" -ip "C:\CAST\cloud\application2\exclusions_new.txt"

Analysis mode example

Note

Using the analysis mode requires that the fastscan mode has already been run.

Run an analysis only, store the results in a dedicated folder and then upload all results to CAST Imaging on Cloud:

CAST-Imaging-CLI.exe analysis -n "application2" -o "C:\CAST\cloud\application2\results1" -s "C:\CAST\source_code\application2" -ak "u9t2Dteq.1YYvvPCoMNp" -pr "C:\CAST\cloud\application2\results1\profiler\profiler-results.json"

Upload mode example

Upload the results of previous fastscan and analysis mode actions:

CAST-Imaging-CLI.exe upload -n "application2" -o "C:\CAST\cloud\application2\results1" -s "C:\CAST\source_code\application2" "u9t2Dteq.1YYvvPCoMNp" -pr "C:\CAST\cloud\application2\results1\profiler\profiler-results.json" -cr "C:\CAST\cloud\application2\results1\carl\carl"

Offline mode example

See How to run local code analyses in offline mode.