Spotless Command Line Interface CLI

Keep your code Spotless from the command line

Note

This project is a work in progress ⏳ and not yet released.

Please check back later for the first release. ❤️

spotless is a command line interface (CLI) for the spotless code formatter. It intends to be a simple alternative to its siblings: the plugins for gradle, maven and others. It supports formatting a plethora of file types and can be easily configured.

Example usage:

spotless --target '**/src/**/*.java' \
    google-java-format \
    license-header --header='/* (c) DiffPlug $YEAR */'

This command formats all java files in any src folder with the google-java-format and adds (or updates an existing) license header.

Using the above command line you go

From this	to this

Installation

Installation on macOS and Linux

To install with Homebrew on macOS or Linux:

brew install diffplug/tap/spotless-cli

# or if you prefer
brew tap diffplug/tap
brew install spotless-cli

Installation on Windows

To install with Chocolatey on Windows:

choco install spotless-cli

Alternatively, you can download the latest binary for your system from the releases page and add it to your PATH.

General usage

The general principle is to specify the files to format, configure global options and then add one or more formatter steps - with configuration if needed.

# general structure of the invocation
spotless --target [... more options] formatter1 [config-of-formatter1] formatter2 [config-of-formatter2] ...

Be aware that the order of the formatter steps is important. The formatters are applied in the order they are specified.

To see all available options and formatters, run:

spotless --help

This will show you the available options and formatters as such:

Available Formatter Steps

Spotless CLI supports the following formatter steps in alphabetical order:

• clang-format
• format-annotations
• google-java-format
• license-header
• palantir-java-format
• prettier

clang-format

Formats C/C++/Objective-C and more files according to the clang-format style guide.

To see usage instructions for the clang-format formatter, run: spotless clang-format --help

Example usage:

spotless --target '**/src/**/*.cpp' clang-format --clang-version=20.1.2 --style=Google

Important

Running a clang-format step requires a working installation of the clang-format binary.

format-annotations

In Java, type annotations should be on the same line as the type that they qualify. This formatter fixes this for you.

To see usage instructions for the format-annotations formatter, run: spotless format-annotations --help

Example usage:

spotless --target '**/src/**/*.java' format-annotations

# or add/remove annotations to the default set using list syntax
spotless --target '**/src/**/*.java' format-annotations \
    --add-type-annotation='MyAnnotation1,MyAnnotation2' \
    --remove-type-annotation='MyAnnotation3,MyAnnotation4'

# or add/remove annotations to the default set using repeated options
spotless --target '**/src/**/*.java' format-annotations \
    --add-type-annotation='MyAnnotation1' \
    --add-type-annotation='MyAnnotation2' \
    --remove-type-annotation='MyAnnotation3' \
    --remove-type-annotation='MyAnnotation4'

google-java-format

Formats Java files according to the google-java-format style guide.

To see usage instructions for the google-java-format formatter, run: spotless google-java-format --help

Example usage:

spotless --target '**/src/**/*.java' google-java-format --reorder-imports=true

license-header

Add or update a license header to the files.

To see usage instructions for the license-header formatter, run: spotless license-header --help

Example usage:

spotless --target '**/src/**/*.java' license-header --header='/* (c) DiffPlug $YEAR */'

palantir-java-format

Formats java files according to the palantir-java-format style guide. Palantir Java Format is a modern, lambda-friendly, 120 character Java formatter. It is based on the Google Java Format project.

To see usage instructions for the palantir-java-format formatter, run spotless palantir-java-format --help

Example usage:

spotless --target '**/src/**/*.java' palantir-java-format --format-javadoc=true

prettier

Prettier is an opinionated code formatter that supports many languages. Some are supported out of the box such as JavaScript, JSX, Angular, Vue, Flow, TypeScript, CSS, Less, SCSS, HTML, Ember/Handlebars, JSON, GraphQL, Markdown and YAML.

Even more languages can be supported by including prettier-plugins.

Important

Running a prettier formatter step requires a working installation of Node.js and npm.

To see usage instructions for the prettier formatter, run: spotless prettier --help

Example usage:

spotless --target '**/*.json' prettier

# or using a custom version and plugin (prettier <= 2)
spotless --target='src/**/*.java' prettier \
    --prettier-config-option='printWidth=120' \
    --dev-dependency='prettier=2.8.7' \
    --dev-dependency='prettier-plugin-java=2.1.0'

# or using a custom version and plugin (prettier 3+)
# → prettier 3 needs you to enable plugins explicitly (see 'plugins' config option)
spotless --target='src/**/*.java' prettier \
    --prettier-config-option='printWidth=120' \
    --prettier-config-option='plugins=["prettier-plugin-java"]' \
    --dev-dependency='prettier=3.0.3' \
    --dev-dependency='prettier-plugin-java=2.3.0'

Tipps & Tricks

Using a configuration file

Since spotless-cli is based on picocli, you can use configuration files to store long or complex command lines (called @files in picocli terminology).

👉 For details see picocli documentation

Example usage:

Store a configuration file /path/to/my/project/spotless-prettier-java.config with the following content:

--target 'src/**/*.java'
prettier
--prettier-config-option 'printWidth=120'
--prettier-config-option 'plugins=["prettier-plugin-java"]'
--dev-dependency 'prettier=3.0.3'
--dev-dependency 'prettier-plugin-java=2.3.0'
license-header
--header-file=/path/to/my/project/license-header.txt

Then you can run spotless-cli with just the following command:

spotless @/path/to/my/project/spotless-prettier-java.config

which behind the scenes will be expanded into:

spotless --target='src/**/*.java' \
    prettier \
        --prettier-config-option='printWidth=120' \
        --prettier-config-option='plugins=["prettier-plugin-java"]' \
        --dev-dependency='prettier=3.0.3' \
        --dev-dependency='prettier-plugin-java=2.3.0' \
    license-header \
        --header-file='/path/to/my/project/license-header.txt'