validate admin

The validate admin command administers integration projects and builds. In order to use some of the following command options, you may need to have a specific permission level. See Enabling access to Klocwork projects for more information.

Usage

 validate admin [<common_options>] <subcommand> [<subcommand_options>]

where

<common_options> are any of the options found in Options that apply to all validate admin subcommands
<subcommand> is any of the validate admin subcommands covered in subsequent sections
<subcommand_options> are any of the options for the specified subcommand

You can also specify an arguments file for validate admin or for validate admin subcommands:

validate admin @<arguments_file>

validate admin <subcommand> @<arguments_file>

You can create an arguments file to specify your command line arguments. Each argument must be specified on a separate line. (If the arguments file contains multibyte characters, the file must be UTF-8 encoded.)

Example

validate admin --url http://server01.acme.com:8080 list-projects

Options that apply to all validate admin subcommands

The options in the table below apply to all of the subcommands. Subsequent sections provide information on validate admin subcommands and the options that apply to each. These options are to be placed before the subcommand.

Name	Description
@<arguments_file>	specifies a text file containing validate admin subcommands and options. Allows a very long command line (for example, when you need to specify a list of jar files for `validate admin set-project-property`).
--help	display the software version, copyright information and help for the command
--url http(s)://<validate_server_host>:<validate_server_port>/	URL for the Validate Server. Use https:// if a secure Validate Server connection has been configured. <host> specifies the host machine running the Validate Server you want to connect to. The default is the last host validate admin successfully connected to, or localhost, if validate admin has not yet connected to the Validate Server. <port> specifies the port used by the Validate Server you want to connect to. The default is the last port validate admin successfully connected to, or 8080, if validate admin has not yet connected to the Validate Server. Use https:// if a secure Validate Server connection has been configured.
--verbose	print verbose information about program execution, which can help to troubleshoot errors
--version	get version information

validate admin create-project

Use validate admin create-project to create a new project with the specified name. The newly created project does not contain data until it is analyzed (built).

validate admin create-project <project_name> [options]

where:

<project_name> is the name of the project you want to create. Project and build names must start with a letter or a digit. Period (.), minus sign (-), white space and the underscore character are also allowed in project and build names. Each cannot be longer than 64 characters.

To reference a project on the command line, you must specify the project using the correct case (since project names are case sensitive). You must also specify the exact, current name of the project as it appears in Validate Static Code Analysis.

Example

validate admin create-project Toolbus

Using validate admin create-project to create a stream

You can also use validate admin create-project to create a new stream of an existing project. Note that the parent project and any specified parent streams must already exist before creating a child stream. You must also specify the exact, current name of the project and/or stream as it appears in Validate Static Code Analysis.

Example

validate admin create-project myProj/stream1

Options

Name	Description
--encoding <arg>	encoding of the source files used in the project. The default is your system encoding. Use the `--list` option of kwconv to find the list of acceptable values. For more information, see the `--encoding` option of kwbuildproject.

validate admin delete-build

Use this command to remove a project build from the builds list and the database.

Once deleted, this build data is unrecoverable.

validate admin delete-build <project_name> <build_name>

where:

<project_name> is the name of the project whose build you want to delete
<build_name> is the name of the build you want to delete

Example

validate admin delete-build Toolbus build_9

validate admin delete-ci-build

Use this command to remove a continuous integration build from the CI builds list and the database.

Once deleted, this CI build data is unrecoverable.

validate admin delete-ci-build <project_name> <ci_build_name>

where:

<project_name> is the name of the project whose build you want to delete
<ci_build_name> is the name of the build you want to delete

Example

validate admin delete-ci-build demothenes ci_build_2

validate admin delete-config

Use this command to remove a project-level or system configuration file. See validate admin import-config for more information on managing configuration files.

validate admin delete-config <project_name> <config-file_name>

where:

<project_name> is the name of the project whose configuration file you want to delete.

CAUTION:

If you remove a configuration file in this way, the file is actually deleted from the file system.

If you specify a project name of "workspace", this indicates that the configuration file should be deleted from the default list of project configuration files.

<config-file_name> is the name of the configuration file you want to delete. Do not specify the path to the file, just the file name.

Examples

validate admin delete-config Toolbus metrics_custom.mconf

validate admin delete-config workspace OurMetrics.mconf

validate admin delete-project

Use this command to remove the specified project and all its builds from the projects list and the database.

CAUTION:

Once deleted, this project data is unrecoverable.

validate admin delete-project <project_name>

where

<project_name> is the name of the project you want to delete

Example

validate admin delete-project Toolbus --force

validate admin delete-project Toolbus_2 --delete-inactive-project

If a project has any streams associated with it, you must include the --force option to delete the project and all related streams.

You must use the --delete-inactive-project flag to delete projects in an inactive state.

Options

Name (and short name)	Description
--delete-inactive-project	use this flag to delete inactive projects
--force	use this option to forcibly delete a project along with any associated streams

validate admin duplicate-project

Use this command as a shortcut to creating a new project. It duplicates a project's settings, the views, modules, users and permissions associated with the project, pointers to source type locations, and configuration files. The builds of the original project are not duplicated.

validate admin duplicate-project <existing_project_name> <new_project_name>

where:

<existing_project_name> is the name of the existing project you want to duplicate
<new_project_name> is the name of the project you want to create. Project and build names must start with a letter or a digit. Period (.), minus sign (-), white space and the underscore character are also allowed in project and build names. Each cannot be longer than 64 characters.

To reference a project on the command line, you must specify the project using the correct case (since project names are case sensitive). You must also specify the exact, current name of the project as it appears in Validate Static Code Analysis.

Example

validate admin duplicate-project Toolbus New_Toolbus

If the .conf file of the project you want to duplicate contains manually configured properties or settings, you must restart that project's Validate server (or it must have been restarted after the changes were originally configured) in order to ensure that the properties and their values will be copied during the duplicate-project operation.

validate admin get-build-properties

Use this command to display the properties of the specified project build. For a complete list of build properties, see Reference for integration project and build properties.

To display the properties of a specific project build, type the following command:

validate admin [--url http(s)://<host>:<port>/] get-build-properties <project_name> <build_name>

where

<host>:<port> specifies the host machine (default is localhost) and port (default is 8080) which the Validate Server is running
<project_name> is the name of the project whose build properties you want to view
<build_name> is the name of the build whose properties you want to view

Example

validate admin get-build-properties Toolbus build_2

validate admin get-project-properties

Use this command to display the properties of the specified project. Some of these properties are editable. For a complete list of project properties, see Reference for integration project and build properties.

To view the properties of an existing project, type the following command:

validate admin [--url http(s)://<host>:<port>/] get-project-properties <project_name>

where

<host>:<port> specifies the host machine (default is localhost) and port (default is 8080) which the Validate Server is running
<project_name> is the name of the project whose properties you want to view

Example

validate admin get-project-properties Toolbus

validate admin get-projects-root

Use this command to display the current projects_root (that is, the projects_root on which the Validate Server was started).

validate admin get-projects-root

Example

validate admin --url http://ServerXZY.acme.com:8080 get-projects-root

validate admin import-config

Use validate admin import-config to import configuration files into a single project or an entire projects_root.

validate admin import-config <project_name> <file>

where:

<project_name> is the name of the project into which you want to import the configuration file.

If you specify a project name of "workspace", this indicates that the configuration file should be imported into the default list of project configuration files for this projects_root directory.

<file> is the full path to the configuration file you want to import. The type of the configuration file is determined by its extension or name.

Examples

validate admin import-config Toolbus C:\Validate\OurMetrics.mconf

validate admin import-config Toolbus C:\Validate\Toolbus_ownership.sow

validate admin import-config workspace C:\Validate\OurMetrics.mconf

See Managing configuration files for integration projects for more information.

validate admin export-config

Use validate admin export-config to download configuration files from the server or a project to your local machine.

validate admin export-config [options] <project-name> <server-file> <local-file>

where:

<project_name> is the name of the project you want to download the configuration file from

<server-file> is the name of the server file you want to download
<local-file> is the name of the folder or file that is saved to your local machine

Examples

validate admin export-config Toolbus ExportedOurMetrics.mconf C:\Validate\OurMetrics.mconf

validate admin export-config Toolbus ExportedOurMetrics.mconf C:\Validate\

validate admin list-builds

Use this command to list the existing builds for the specified project.

validate admin list-builds <project_name>

where:

<project_name> is the name of the project whose builds you want to view

Example

validate admin list-builds Toolbus --detail

Adding the --detail option will print the date of the build, whether to not auto-delete the build, and a list of build tags, as follows:

date=<date of build> keep=<true/false>  tags=<list of build tags>

validate admin list-ci-builds

Use this command to list the existing CI builds for the specified project.

validate admin list-ci-builds <project_name>

where:

<project_name> is the name of the project whose CI builds you want to view

Example

validate admin list-ci-builds demosthenes --detail

Adding the --detail option will print the date of the build, whether to not auto-delete the build, and a list of build tags, as follows:

date=<date of build> keep=<true/false>  tags=<list of build tags>

validate admin list-config-files

Use validate admin list-config-files to list the configuration files used for the specified project. See also "Configuration files for Validate projects".

validate admin list-config-files <project_name>

where:

<project_name> is the name of the project whose configuration files you want to view

Example

validate admin list-config-files Toolbus

validate admin list-config-types

Use validate admin list-config-types to list the names and extensions of valid types of configuration files. See also Configuration files you can edit.

validate admin list-config-types

Example

validate admin --url http://myhost.acme.com:8080 list-config-types

validate admin list-projects

Use this command to display a list of existing projects in the current projects_root directory.

validate admin list-projects

Example

validate admin --url http://myserver.acme.com:8080 list-projects

Options

Name (and short name)	Description
--include-streams (-s)	include streams in the results
--prefix-filter (-x) <string>	limit results to projects and streams that start with the supplied prefix
--include-inactive (-i)	list all the projects, including those in an inactive state
--format-json (-f)	list all the projects with their details in JSON format

validate admin load

Use this command to load the Validate tables generated by kwbuildproject to the Validate Server.

validate admin load <project_name | path_to_stream> [<tables-directory>]

where

<project_name | path_to_stream> is the name of the project or the path to the stream whose build you want to load.
<tables-directory> is the path to the Validate tables generated by kwbuildproject. The tables directory must not be located in the projects_root directory. You must have read and write permissions on this directory.

Example 1: Project name

validate admin load Toolbus /my/tables/directory

Example 2: Path to stream

validate admin load Toolbus/variant1 /my/tables/directory

Options

Name (and short name)	Description
--file-overrides <file>	specify an overrides file to add, delete, or rename files. This option gives you better control over complex scenarios and reduce file mismatches. For more information on using file overrides file, see Recommended mechanisms for loading builds.
--force	start a new analysis even if a previous analysis is still in progress. Use this option only in the case in which the analysis was killed, but the build state is still listed as "In progress". Once a new analysis has successfully completed, the `--force` option is no longer needed.
--ignore-defect-threshold	ignore the configured defect threshold limit for a project and force a build to load even if it surpasses it
--name <build_name>	set a name for the build other than the default. The default is "build#," where # is 1, or one greater than the last created build. Numbers of deleted builds are not reused. Only digits (0 through 9), Latin letters (A through Z, a through z), dot (.), minus sign (-), white space and the underscore character are allowed in a build name. The <build_name> must not be longer than 64 characters.
--tags	specify a comma separated list of build tags

validate admin lock-project-version

Use this command when you want to load builds from an earlier version of Validate into a later version of the Validate Server. When you run this command on the build machine that is running the older version of Validate, the command creates a file that contains information about the engine and checker configuration on the build machine, including any custom checkers and whether checkers are enabled or disabled. The server uses this information as the base configuration for the project.

validate admin lock-project-version <project_name> --url http(s)://<host>:<port>/

where

<project_name> is the name of the project on the (newer) Validate Server
<host>:<port> specifies the host machine (default is localhost) and port (default is 8080) which the (newer) Validate Server is running

Example

validate admin lock-project-version myproject --url http://my2018server.acme.com:8084

For more information, see Cross-version support for builds.

validate admin rename-build

Use this command to rename a build.

validate admin rename-build <project_name> <build_name> <new_build_name>

where

<project_name> is the name of the project you want to rename
<build_name> is the name of the build you want to rename
<new_build_name> is the name you want to give your build

Project and build names must start with a letter or a digit. Period (.), minus sign (-), white space and the underscore character are also allowed in project and build names. Each cannot be longer than 64 characters.

To reference a project on the command line, you must specify the project using the correct case (since project names are case sensitive). You must also specify the exact, current name of the project as it appears in Validate Static Code Analysis.

When using white space or a dot, wrap the name in double quotes.

Example

validate admin rename-build demosthenes buidl_6 build_6

validate admin rename-ci-build

Use this command to rename a CI build.

validate admin rename-ci-build <project_name> <ci_build_name> <new_ci_build_name>

where

<project_name> is the name of the project you want to rename
<ci_build_name> is the name of the CI build you want to rename
<new_ci_build_name> is the name you want to give your CI build

Project and build names must start with a letter or a digit. Period (.), minus sign (-), white space and the underscore character are also allowed in project and build names. Each cannot be longer than 64 characters.

To reference a project on the command line, you must specify the project using the correct case (since project names are case sensitive). You must also specify the exact, current name of the project as it appears in Validate.

When using white space or a dot, wrap the name in double quotes.

Example

validate admin rename-ci-build demosthenes buidl_2 build_2

validate admin rename-project

Use this command to rename a project.

validate admin rename-project <path-to-project-or-stream> <new-project-or-stream-name>

where

<path-to-project-or-stream> is the full path to the project or stream you want to rename
<new-project-or-stream-name> is the name you want to give your project or stream

Project, streams, and build names must start with a letter or a digit. Period (.), minus sign (-), white space and the underscore character are also allowed in project and build names. Each cannot be longer than 64 characters.

To reference a project or stream on the command line, you must specify it using the correct case (since project and stream names are case sensitive). For projects, you must also specify the exact, current name as it appears in Validate Static Code Analysis. For streams, you must specify a full path to the stream, for example myProj/myStream1/subVariant.

When using white space or a dot, wrap the name in double quotes.

Example

validate admin rename-project myProj/demosthenes demosthenes-new

validate admin set-project-property

Use this command to set the properties for an existing project. The change applies to all subsequent analysis runs.

Prerequisite: all of the Validate Servers must be running. See Managing the Validate Servers.

validate admin --url http(s)://<server>:<port> set-project-property <project_name> <property> <value>

where

<project_name> is the name of an existing project
<property> is one of the properties shown in Project properties displayed by validate admin
<value> is a value for a project property

Examples

Change the default setting for issue grouping so that the system persistently shows server issues with grouping off:

validate admin --url http://myserver:8080/ set-project-property Toolbus grouping_on_default false

Set a threshold to fail a build when the files uploaded exceed the limit for the number of defects of the same kind in any single file:

validate admin set-project-property Toolbus same_kind_defect_per_file_threshold 5000

You can set a property value as the default for any new projects by using workspace instead of a specific project name. For example:

validate admin --url http://myserver:8080/ set-project-property workspace grouping_on_default false

validate admin set-project-property workspace same_kind_defect_per_file_threshold 5000

Notes

When adding a value to a property that consists of a comma-separated list of values, you must specify all of the existing values as well as the value you are adding (with no spaces between the values). Otherwise, the value you specify will overwrite the existing values.

The values you specify are not validated by Validate, so it is possible to set a property value that will cause an analysis to fail. If you set an invalid option, you must unset the option by running the command again, specifying all of the current values for the property except for the invalid one.

If any of the following conditions apply, enclose the entire property value in single quotation marks:

The value contains spaces.
The value is a comma-separated list of sub-values.
The value contains a command-line switch that begins with a double-dash.

For more information, see Reference for integration project and build properties.

validate admin set-project-state

Use this command to set the state for an existing project.

validate admin set-project-state <project_name> <value>

where

<project_name> is the name of an existing project
<value> is a value for a project state, either active or inactive

Example

validate admin set-project-state project_1 active

Only projects root admin can use the set-project-state command.

validate admin unlock-project-version

Use this command to undo the lock-project-version command, if you no longer want to use the checker configuration from an earlier version of Validate with your project. After you run this command, Validate uses the checker configuration for the Validate Server on which the build is loaded (which can be a different set of checkers from the analysis run on the build machine).

validate admin unlock-project-version <project_name> --url http(s)://<host>:<port>/

where

<project_name> is the name of the project on the (newer) Validate Server
<host>:<port> specifies the host machine (default is localhost) and port (default is 8080) which the (newer) Validate Server is running

Example

validate admin unlock-project-version myproject --url http://my2018server.acme.com:8084

For more information, see Cross-version support for builds.

Exit codes

When you run the validate admin command, the system generates one of two possible exit codes: if the command ran successfully and generated no errors, the exit code will be 0; the exit code will be 1 if

an error occurred
the subcommand was --help or --version

an error occurred, the exit code will be 1. The exit code For more information when the validate admin load command returns exit code 1, you can check the build.log file.

Build license consumption

Running the following validate admin sub-commands will consume a build license:

create-project: Create empty project with given name
delete-build: Delete build from project
delete-ci-build: Delete CI build from project
delete-config: Delete config file from project
delete-project: Delete project and all its builds
duplicate-project: Create duplicate of given project
import-config: Import config file into project
load: Load new build for selected project
lock-project-version: Lock Project Version
rename-build: Rename project build
rename-ci-build: Rename project CI build
rename-project: Rename project/stream
set-project-property: Set project property
set-project-state: Set project state
unlock-project-version: Unlock Project Version