Kwadmin

The kwadmin 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

 kwadmin [<common_options>] <subcommand> [<subcommand_options>]

where

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

You can also specify an arguments file for kwadmin or for kwadmin subcommands:

kwadmin @<arguments_file>

kwadmin <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

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

Options that apply to all kwadmin subcommands

The options in the table below apply to all of the subcommands. Subsequent sections provide information on kwadmin 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 kwadmin subcommands and options. Allows a very long command line (for example, when you need to specify a list of jar files for `kwadmin 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 kwadmin successfully connected to, or localhost, if kwadmin 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 kwadmin successfully connected to, or 8080, if kwadmin 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

kwadmin create-project

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

kwadmin 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.

Important: 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.

Example

kwadmin create-project Toolbus

Using kwadmin create-project to create a stream

You can also use kwadmin 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.

Example

kwadmin 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.

kwadmin delete-build

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

Important: Once deleted, this build data is unrecoverable.

kwadmin 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

kwadmin delete-build Toolbus build_9

kwadmin delete-ci-build

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

Important: Once deleted, this CI build data is unrecoverable.

kwadmin 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

kwadmin delete-ci-build demothenes ci_build_2

kwadmin delete-config

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

kwadmin 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

kwadmin delete-config Toolbus metrics_custom.mconf

kwadmin delete-config workspace OurMetrics.mconf

kwadmin 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.

kwadmin delete-project <project_name>

where

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

Example

kwadmin delete-project Toolbus --force

kwadmin delete-project Toolbus_2 --delete-inactive-project

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

Restriction: 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

kwadmin 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.

kwadmin 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.

Important: 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.

Example

kwadmin 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 Klocwork 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.

kwadmin 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:

kwadmin [--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

kwadmin get-build-properties Toolbus build_2

kwadmin 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:

kwadmin [--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

kwadmin get-project-properties Toolbus

kwadmin get-projects-root

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

kwadmin get-projects-root

Example

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

kwadmin import-config

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

kwadmin 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

kwadmin import-config Toolbus C:\Klocwork\OurMetrics.mconf

kwadmin import-config Toolbus C:\Klocwork\Toolbus_ownership.sow

kwadmin import-config workspace C:\Klocwork\OurMetrics.mconf

See Managing configuration files for integration projects for more information.

kwadmin export-config

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

kwadmin 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

kwadmin export-config Toolbus ExportedOurMetrics.mconf C:\Klocwork\OurMetrics.mconf

kwadmin export-config Toolbus ExportedOurMetrics.mconf C:\Klocwork\

kwadmin list-builds

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

kwadmin list-builds <project_name>

where:

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

Example

kwadmin 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>

kwadmin list-ci-builds

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

kwadmin list-ci-builds <project_name>

where:

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

Example

kwadmin 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>

kwadmin list-config-files

Use kwadmin list-config-files to list the configuration files used for the specified project. See also "Configuration files for Klocwork projects".

kwadmin list-config-files <project_name>

where:

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

Example

kwadmin list-config-files Toolbus

kwadmin list-config-types

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

kwadmin list-config-types

Example

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

kwadmin list-projects

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

kwadmin list-projects

Example

kwadmin --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

kwadmin load

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

kwadmin 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 Klocwork 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

kwadmin load Toolbus /my/tables/directory

Example 2: Path to stream

kwadmin 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.
--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

kwadmin lock-project-version

Use this command when you want to load builds from an earlier version of Klocwork into a later version of the Validate Server. When you run this command on the build machine that is running the older version of Klocwork, 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.

kwadmin 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

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

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

kwadmin rename-build

Use this command to rename a build.

kwadmin 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.

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

Example

kwadmin rename-build demosthenes buidl_6 build_6

kwadmin rename-ci-build

Use this command to rename a CI build.

kwadmin 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

kwadmin rename-ci-build demosthenes buidl_2 build_2

kwadmin rename-project

Use this command to rename a project.

kwadmin 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. 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

kwadmin rename-project myProj/demosthenes demosthenes-new

kwadmin 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.

kwadmin --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 kwadmin
<value> is a value for a project property

Example

The following example shows how to change the default setting for issue grouping so that the system persistently shows server issues with grouping off.

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

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 Klocwork, 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.

kwadmin set-project-state

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

kwadmin 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

kwadmin set-project-state project_1 active

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

kwadmin 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 Klocwork with your project. After you run this command, Klocwork 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).

kwadmin 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

kwadmin 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 kwadmin 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 kwadmin load command returns exit code 1, you can check the build.log file.