Skip to content
Tutorials Center
My learning

Topics

Lesson 14 of 41 ยท Lifecycle and Plugins

The Command Line Toolbox

Learn the Maven command-line options you use daily: -D, -P, -pl, -am, -T, -o, -q, -X, -DskipTests, -rf and -ntp, and how to read logs and stack traces.

Once you know the lifecycle, most of your daily Maven work is choosing the right phase and the right flags. Flags change what is built (-pl), how it is built (-T, -o), how much output you see (-q, -X) and which settings apply (-D, -P). Knowing a dozen of them saves minutes every day, and reading the output correctly saves hours.

Maven cannot run on this site, so every command in this lesson is read-only. The TryIts are Java stand-ins: an argument parser that sorts a Maven command line into phases, goals, properties, profiles and options, and a small log reader. They model the idea only; the real parser is part of Maven.

Anatomy of a command

mvn The program.
Phases and goals What to run.
Options How to run it.
-Dkey=value Properties for this run.
1 / 2

The shape of a command

Terminal
mvn [options] [<goal(s)>] [<phase(s)>]

You can mix phases (clean, package), goals (dependency:tree) and options (anything starting with -). They run in the order you write them. Property assignments such as -DskipTests are options too.

Properties and profiles

-D sets a user property for this run: -Dname=value, or just -Dname which means true. It overrides properties in the POM (see Properties and Build Settings).

Terminal
mvn package -Dmaven.compiler.release=21
mvn test -Dtest=OrderServiceTest
mvn deploy -DskipTests

-P activates a profile by id; separate several with commas, and prefix with ! to deactivate one.

Terminal
mvn verify -Pci
mvn package -Pprod,!local

Profiles have their own lesson, Profiles and Environments.

Skipping tests

There are two properties, and the difference matters.

Flag Effect
-DskipTests Compiles tests, but does not run them.
-Dmaven.test.skip=true Does not even compile tests, and skips testResources.

Use -DskipTests normally, since test code is still checked for compile errors. Use -Dmaven.test.skip=true only when test code cannot compile at the moment, or when a build creates a test JAR you do not need. Skipping tests in a release build is a bad habit; do it for quick local experiments.

Choosing what to build in a multi-module project

In a project with several modules (see Multi-Module Builds and the Reactor), these flags narrow the work:

Flag Meaning
-pl a,b Build only modules a and b (also -pl :artifactId).
-am Also make: also build the modules the selected ones depend on.
-amd Also make dependents: build modules that depend on the selected ones.
-rf :b Resume from module b after a failure.
-N Non-recursive: build only the project in the current folder.
-f path/pom.xml Use another POM file.
Terminal
mvn package -pl service -am        # service plus the libraries it needs
mvn test -pl :core -amd            # core plus everything that depends on it
mvn package -rf :service           # continue where the last build stopped

Speed

  • -T 4 (or -T 1C, meaning one thread per CPU core) builds independent modules in parallel. Plugins must be thread-safe; most official ones are. See Maven in CI and Faster Builds.
  • -o (offline) never contacts remote repositories. It works only if everything is already in ~/.m2.
  • -DskipTests removes the slowest phase.
  • -U forces Maven to re-check remote repositories for updated snapshots and for artifacts that failed earlier.

Output control

Flag Effect
-q Quiet: only errors.
-e Show full stack traces for build errors.
-X Debug: very verbose, including the resolved classpath and plugin parameters.
-B Batch mode: no colors or interactive questions, as used in CI.
-ntp No transfer progress: hides the download progress lines (long form --no-transfer-progress).
-V Show the Maven and Java version at the start, then continue.
-s file Use a specific settings.xml.

For CI you will typically see mvn -B -ntp verify, which gives clean logs without progress bars. When something fails and the message is not enough, re-run with -e, and as a last resort with -X, then search the output for the first sign of trouble.

Failure behaviour

By default Maven stops at the first failing module (fail-fast). You can change that.

Flag Behaviour
-ff Fail fast (the default).
-fae Fail at end: skip modules that depend on the failed one, but build the rest.
-fn Fail never: always report success (use with care, for example for report generation).

A command-line sorter

The stand-in below reads an argument list, as Maven would, and sorts every item into phases, goals, user properties, profiles and options. Real Maven uses a library for this, and understands many more cases (for example -Dkey=value with spaces and quoting), but the categories are the same.

Java Sorting a Maven command line (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

The first line shows two phases, two profiles and two properties, with -DskipITs turning into true. The second shows -pl service and -T 1C as options with arguments. The third is a direct goal with a property that narrows the tree to one library.

Reading the log

Maven's output is regular enough to read quickly. Each line starts with a level: [INFO], [WARNING] or [ERROR]. A failed build ends with BUILD FAILURE and a block of [ERROR] lines. In a multi-module project, the Reactor Summary lists each module with SUCCESS, FAILURE or SKIPPED.

TEXT
[INFO] Reactor Summary for demo 1.0.0:
[INFO]
[INFO] demo-parent ........................................ SUCCESS [  0.2 s]
[INFO] demo-core .......................................... SUCCESS [  2.1 s]
[INFO] demo-service ....................................... FAILURE [  1.4 s]
[INFO] demo-app ........................................... SKIPPED
[INFO] BUILD FAILURE
[ERROR] Failed to execute goal org.apache.maven.plugins:maven-compiler-plugin:3.13.0:compile
(default-compile) on project demo-service: Compilation failure
[ERROR] /work/demo-service/src/main/java/com/example/Orders.java:[14,23] cannot find symbol

Reading order:

  1. Find the first [ERROR] line, not the last. Later errors are often consequences.
  2. Note the plugin and goal (maven-compiler-plugin:...:compile) and the module (demo-service). That tells you which step failed and where.
  3. Read the specific message below it. Compiler errors name a file and [line,column]; test failures name a test class and a report file in target/surefire-reports.
  4. If it says See the full stack trace by re-running Maven with the -e switch, do that.
  5. After fixing, resume with -rf :demo-service to skip modules that already built.

The stand-in below pulls that first error out of a log, which is the habit to build.

Java Find the first error in a log (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

It reports the first error (the missing method), the module that failed and the resume command.

A short daily toolbox

Situation Command
Clean, full build mvn clean verify
Quick compile check mvn -q compile
One module and its needs mvn -pl app -am package
Fast local build without tests mvn package -DskipTests
One test class mvn test -Dtest=OrderServiceTest
CI-friendly log mvn -B -ntp verify
Why did it fail? mvn verify -e
Check a property's effect mvn help:effective-pom -Dsome.property=value

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What is the difference between -DskipTests and -Dmaven.test.skip=true?

    -DskipTests still compiles test code so broken tests are noticed. maven.test.skip skips test compilation and test resources as well.
  2. 2. In a multi-module project you want to build module service and the modules it depends on. Which flags?

    -pl selects the module and -am (also make) adds the modules it depends on. -amd adds dependents instead, and -rf resumes after a failure.
  3. 3. Which flag removes the download progress lines, which is useful in CI logs?

    -ntp (--no-transfer-progress) hides transfer progress. -B is batch mode, -q is quiet and -o is offline mode.
  4. 4. A multi-module build fails. Which line should you read first?

    Later errors are often consequences. The first error normally names the failing goal, the module and the specific cause.
  5. 5. What does -fae do?

    fail-at-end skips dependents of a failed module but builds the rest, then reports failure.

Summary

  • A command is mvn [options] [goals] [phases]; phases, goals and options can be mixed.
  • -D sets properties for one run, -P activates profiles.
  • -DskipTests compiles but does not run tests; -Dmaven.test.skip=true skips test compilation too.
  • -pl, -am, -amd, -rf and -N select modules; -T runs modules in parallel; -o works offline.
  • -q, -e, -X, -B and -ntp control output; read the first [ERROR] line and the Reactor Summary.
  • The parser and log reader above are stand-ins that illustrate the categories.

Next, start working with libraries: Adding Dependencies.