# PMD CLI reference

Full reference for PMD's command-line interface, including options, output formats and supported languages

## Options

The tool comes with a rather extensive help text, simply running with `--help`!

Option | Description | Default value | Applies to
--- | --- | --- | ---
`--rulesets <refs>` `-R <refs>` | Required Comma-separated list of ruleset or rule references. | `` |
`--dir <path>` `-d <path>` | Required Root directory for sources to be analyzed. This can be a single file name, a directory, or a jar or zip file containing the sources. | `` |
`--format <format>` `-f <format>` | Output format of the analysis report. The available formats are described here. | `text` |
`--aux-classpath <cp>` | Specifies the classpath for libraries used by the source code. This is used to resolve types in source files. The platform specific path delimiter (":" on Linux, ";" on Windows) is used to separate the entries. Alternatively, a single `file:` URL to a text file containing path elements on consecutive lines can be specified. | `` | Java
`--benchmark` `-b` | Enables benchmark mode, which outputs a benchmark report upon completion. The report is sent to standard error. | `` |
`--cache <filepath>` | Specify the location of the cache file for incremental analysis. This should be the full path to the file, including the desired file name (not just the parent directory). If the file doesn't exist, it will be created on the first run. The file will be overwritten on each run with the most up-to-date rule violations. This can greatly improve analysis performance and is highly recommended. | `` |
`--debug` `--verbose` `-D` `-V` | Debug mode. Prints more log output. | `` |
`--encoding <charset>` `-e <charset>` | Specifies the character set encoding of the source code files PMD is reading. The valid values are the standard character sets of `java.nio.charset.Charset`. | `UTF-8` |
`--fail-on-violation <bool>` | Specifies whether PMD exits with non-zero status if violations are found. By default PMD exits with status 4 if violations are found. Disable this feature with `--fail-on-violation false` to exit with 0 instead and just output the report. | `true` |
`--file-list <filepath>` | Path to file containing a list of files to analyze, one path per line. If this is given, then you don't need to provide `--dir`. | `` |
`--force-language <lang>` | Force a language to be used for all input files, irrespective of file names. When using this option, the automatic language selection by extension is disabled and PMD tries to parse all files with the given language `<lang>`. Parsing errors are ignored and unparsable files are skipped. Use `--use-version` to specify the language version to use, if it is not the default. This option allows to use the xml language for files, that don't use xml as extension. See example below. | `` |
`--ignore-list <filepath>` | Path to file containing a list of files to ignore, one path per line. This option can be combined with `--dir` and `--file-list`. This ignore list takes precedence over any files in the file-list. | `` |
`--help` `-h` `-H` | Display help on usage. | `` |
`--use-version <lang-version>` | The specific language version PMD should use when parsing source code for a given language. Values are in the format of language-version. This option can be repeated to configure several languages for the same run. Note that this option does not change how languages are assigned to files. It only changes something if the project you analyze contains some files that PMD detects as the given language. Language detection is only influenced by file extensions and the `--force-language` option. See also Supported Languages. | `` |
`-language <lang>` `-l <lang>` | Specify the language PMD should use. Used together with `-version`. See also Supported Languages. Deprecated since PMD 6.52.0. Use `--use-version` instead. | `` |
`--minimum-priority <num>` `-min <num>` | Rule priority threshold; rules with lower priority than configured here won't be used. | `5` |
`--no-ruleset-compatibility` | Disable automatic fixing of invalid rule references. Without the switch, PMD tries to automatically replace rule references that point to moved or renamed rules with the newer location if possible. Disabling it is not recommended. | `` |
`--no-cache` | Explicitly disables incremental analysis. This switch turns off suggestions to use Incremental Analysis, and causes the `--cache` option to be discarded if it is provided. | `` |
`--property <name>=<value>` `-P <name>=<value>` | Specifies a property for the report renderer. The option can be specified several times. | `[]` |
`--relativize-paths-with <path>` `-z <path>` | Path relative to which directories are rendered in the report. This option allows shortening directories in the report; without it, paths are rendered as mentioned in the source directory (option "--dir"). The option can be repeated, in which case the shortest relative path will be used. If the root path is mentioned (e.g. "/" or "C:\\"), then the paths will be rendered as absolute. This option replaces `--short-names` since PMD 6.54.0. | `` |
`--report-file <path>` `-r <path>` | Path to a file to which report output is written. The file is created if it does not exist. If this option is not specified, the report is rendered to standard output. | `` |
`--short-names` | Prints shortened filenames in the report. Deprecated since PMD 6.54.0. Use `--relativize-paths-with` instead. | `` |
`--show-suppressed` | Causes the suppressed rule violations to be added to the report. | `` |
`--stress` `-S` | Performs a stress test. | `` |
`--suppress-marker <marker>` | Specifies the comment token that marks lines which PMD should ignore. | `NOPMD` |
`--threads <num>` `-t <num>` | Sets the number of threads used by PMD. Set threads to `0` to disable multi-threading processing. | `1` |
`--uri <uri>` `-u <uri>` | Database URI for sources. If this is given, then you don't need to provide `--dir`. | `` | PLSQL
`--version` | Display current version of PMD and exit without performing any analysis. | `` |
`-version <version>` `-v <version>` | Specify the version of a language PMD should use. Used together with `-language`. See also Supported Languages. Deprecated since PMD 6.52.0. Use `--use-version` instead. | `` |

## Additional Java Runtime Options

PMD is executed via a Java runtime. In some cases, you might need to set additional runtime options, e.g. if you want to analyze a project, that uses one of OpenJDK’s Preview Language Features.

Just set the environment variable `PMD_JAVA_OPTS` before executing PMD, e.g.

    export PMD_JAVA_OPTS="--enable-preview"
    ./run.sh pmd -d ../../../src/main/java/ -f text -R rulesets/java/quickstart.xml

## Exit Status

Please note that if PMD detects any violations, it will exit with status 4 (since 5.3). This behavior has been introduced to ease PMD integration into scripts or hooks, such as SVN hooks.

0 | Everything is fine, no violations found
1 | Couldn't understand command-line parameters or PMD exited with an exception
4 | At least one violation has been detected, unless `--fail-on-violation false` is set.

## Supported Languages

The language is determined automatically by PMD from the file extensions. Some languages such as “Java” however support multiple versions. The default version will be used, which is usually the latest supported non-preview version. If you want to use an older version, so that e.g. rules that suggest usage of language features that are not available yet won’t be executed, you need to specify a specific version via the `--use-version` parameter.

These parameters are irrelevant for languages that don’t support different versions.

Example:

    ./run.sh pmd -d src/main/java -f text -R rulesets/java/quickstart.xml --use-version java-1.8

- apex (Salesforce Apex)
- ecmascript (JavaScript)
- html
- java
  - Supported Versions
- jsp
- modelica
- plsql
- pom (Maven POM)
- scala
  - Supported Versions: 2.10, 2.11, 2.12, 2.13 (default)
- vf (Salesforce VisualForce)
- vm (Apache Velocity)
- xml
- xsl

## Available Report Formats

PMD comes with many different renderers. All formats are described at PMD Report formats

## Examples

### Analyze other xml formats

If your xml language doesn’t use `xml` as file extension, you can still use PMD with `--force-language`:

    $ ./run.sh pmd -d /home/me/src/xml-file.ext -f text -R ruleset.xml --force-language xml

You can also specify a directory instead of a single file. Then all files are analyzed. In that case, parse errors are suppressed in order to reduce irrelevant noise:

    $ ./run.sh pmd -d /home/me/src/ -f text -R ruleset.xml --force-language xml

Alternatively, you can create a filelist to only analyze files with a given extension:

    $ find /home/me/src -name "*.ext" > /home/me/src/filelist.txt
    $ ./run.sh pmd --file-list /home/me/src/filelist.txt -f text -R ruleset.xml --force-language xml

Tags: userdocs