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.
|
| --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.
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.
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.
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.
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.
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
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.
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. |
| --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 |
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.
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.
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.
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
Examples
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
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:
kwadmin set-project-property Toolbus same_kind_defect_per_file_threshold 5000
workspace instead of a specific project name. For example:kwadmin --url http://myserver:8080/ set-project-property workspace grouping_on_default false
kwadmin 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 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
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
- an error occurred
- the subcommand was --help or --version