CodeNarc - Run From Command-Line


CodeNarc can be run from the command-line as a Java application. The org.codenarc.CodeNarc class provides the application entry-point.

CodeNarc Command-Line Parameters

Usage: java org.codenarc.CodeNarc [OPTIONS] where OPTIONS are zero or more command-line parameters of the form “-NAME[=VALUE]

All command-line parameters are optional. If no parameters are supplied, CodeNarc runs from the current directory with reasonable defaults, as described below.

Parameter Description Example  
basedir=DIR The base (root) directory for the source code to be analyzed. Defaults to the current directory (“.”). -basedir=src/main/groovy  
includes=PATTERNS The comma-separated list of Ant-style file patterns specifying files that must be included. Patterns can match against the full source file path or relative to basedir. Defaults to **/**.groovy. -includes=**/**.gr  
excludes=PATTERNS The comma-separated list of Ant-style file patterns specifying files that must be excluded. Patterns can match against the full source file path or relative to basedir. No files are excluded when omitted. -excludes=**/templates/**,**/**Test.**  
sourcefiles=FILENAMES The comma-separated list of files we want to analyze. If set, -includes and -exclude arguments are ignored. -sourcefiles=mygroovy1.groovy,subdir/anotherfile.groovy,subdir/subdir2/otherfile.groovy  
rulesetfiles=FILENAMES The path to the Groovy, XML or JSON RuleSet definition file(s). This can be a single file path, or multiple paths separated by commas. By default, the paths specified are relative to the classpath. But these paths may be optionally prefixed by any of the valid prefixes, such as “file:” (to load from a relative or absolute path on the filesystem), or “http:”. If it is a URL, its path may be optionally URL-encoded. That can be useful if the path contains any problematic characters, such as comma (‘,’) or hash (‘#’). For instance: “file:src/test/resources/RuleSet-,#.txt” can be encoded as: “file:src%2Ftest%2Fresources%2FRuleSet-%2C%23.txt” See URLEncoder#encode(java.lang.String, java.lang.String). Defaults to “rulesets/basic.xml”. -rulesetfiles=rulesets/imports.xml,rulesets/naming.xml  
ruleset=JSON_STRING String containing a JSON ruleset content.
The string must be URL-encoded in UTF-8 before being sent as argument to CodeNarc
-ruleset=”{ ‘Println’: { } }”  
excludeBaseline=FILENAME The filename of the optional baseline. If not set, no baseline will be used. -excludeBaseline=file:codenarc/codenarc-baseline.xml  
properties=FILENAME The filename of the rule configuration properties files (e.g. “”). By default the specified filename is relative to the classpath, but it may be optionally prefixed by any of the valid prefixes, such as “file:” (to load from a relative or absolute filesystem path). Optional. -properties=file:codenarc/  
report=REPORT-TYPE[FILENAME|stdout]   The definition of the report to produce. The option value is of the form TYPE[:FILENAME\ |stdout], where TYPE is one of the predefined type names: “html”, “xml”, “text”, “json”, “console” or else the fully-qualified class name of a class (accessible on the classpath) that implements the interface. And FILENAME is the filename (with optional path) of the output report filename. If the TYPE is followed by :stdout (e.g. html:stdout, json:stdout), then the report is written to standard out. If the report filename is omitted, the default filename for the report type is used (“CodeNarcReport.html” for “html”, “CodeNarcXmlReport.xml” for “xml”, “CodeNarcJsonReport.json”). If no report option is specified, default to a single “html” report with the default filename. -report=html
maxPriority1Violations=MAX The maximum number of priority 1 violations allowed (int). -maxPriority1Violations=0  
maxPriority2Violations=MAX The maximum number of priority 2 violations allowed (int). -maxPriority2Violations=0  
maxPriority3Violations=MAX The maximum number of priority 3 violations allowed (int). -maxPriority3Violations=0  
title=REPORT TITLE The title for this analysis; used in the output report(s), if supported by the report type(s). Optional. -title=”My Project”  
plugins=PLUGINS The list of CodeNarcPlugin class names to register, separated by commas. Optional. -plugins=org.acme.MyPlugin,org.acme.MyOtherPlugin  
failOnError=true/false Whether to terminate and fail the task if any errors occur parsing source files (true), or just log the errors (false). It defaults to false. Optional. -failOnError=true  
help Display the command-line help. If present, this must be the only command-line parameter. -help  

Executing CodeNarc from the Command-Line

Make sure that the following are included your CLASSPATH:

  1. The Groovy-all jar, e.g. (for Groovy 3.0.x).

  2. The CodeNarc jar. Use a published CodeNarc release or else build the jar from source (see below).

  3. The SLF4J api/implementation jars, e.g. Logback.

  4. The directories containing (or relative to) CodeNarc config files such as “” or ruleset files.

The CodeNarc command-line application sets an exit status of zero (0) if the command successfully executes, and an exit status of one (1) if an error occurs executing CodeNarc, or if an invalid command-line option is specified.

Here is an example BAT file for running CodeNarc on Windows. It assumes the jars are in the current directory.

    @set GROOVY_JAR="groovy-all-2.4.15.jar"
    @set CODENARC_JAR="CodeNarc-1.6.1.jar"
    @set SLF4J_JAR="slf4j-api-1.7.25.jar"
    java -classpath $GROOVY_JAR;$CODENARC_JAR;$SLF4J_JAR org.codenarc.CodeNarc %*

Here is the equivalent Linux command.

    export GROOVY_JAR="groovy-all-2.4.15.jar"
    export CODENARC_JAR="CodeNarc-1.6.1.jar"
    export SLF4J_JAR="slf4j-api-1.7.25.jar"
    java -classpath $GROOVY_JAR:$CODENARC_JAR:$SLF4J_JAR org.codenarc.CodeNarc $*

Running From a Gradle Script

Here is an example Gradle script to run CodeNarc using its command-line interface. It assumes that there is a codenarc.ruleset ruleset file in the current directory.

    apply plugin: 'groovy'

    repositories {

    dependencies {
        // To use a published CodeNarc version
        implementation 'org.codenarc:CodeNarc:3.2.0'
        // OR to use a locally built CodeNarc jar; adjust the relative path and jar filename    
        //implementation files('../../CodeNarc/build/libs/CodeNarc-3.2.0.jar')

        implementation 'ch.qos.logback:logback-classic:1.2.3'

    task runCodeNarc(type:JavaExec) {
        main = "org.codenarc.CodeNarc"
        classpath = sourceSets.main.runtimeClasspath

        args "-rulesetfiles=file:codenarc.ruleset"


See CodeNarc - Docker.

Build the CodeNarc Jar From Source

To build the CodeNarc jar from source:

  1. Clone the GitHub repository, e.g git clone
  2. From within the project root directory, execute: ./gradlew jar. That will create a CodeNarc jar within the build/libs directory.