skip to content

Command Line Runs

3 roadmaps12 questions

The command that actually starts a load run: the flags naming the plan, the results file and the logs, plus the flags that push values in so one JMX serves every environment.

on this pageshow

explore

questions

12

What does each flag in the JMeter command `jmeter -n -t plan.jmx -l results.jtl` do?

level: juniorimportance: must knowfreq 88%

answer

  1. Three flags carry almost the whole line
  2. One of them takes no value
  3. Two of the three name a file
  4. Their long forms appear in jmeter -?

basics

~10 s

-n runs JMeter without its GUI, -t names the .jmx test plan to load and run, and -l names the JTL file that every sample result is written to.

solid answer

~40 s

`-n` (long form `--nongui`) takes no argument and switches JMeter out of GUI mode; without it JMeter opens the Swing window instead. `-t` (`--testfile`) names the `.jmx` plan and is mandatory once `-n` is given — a `-n` run with no `-t` prints `Incorrect Usage:Non-GUI runs require a test plan` and stops. `-l` (`--logfile`) is optional: it makes JMeter build a `ResultCollector`, point it at that JTL file and add it on top of the loaded tree, so it records samples **in addition to** any listeners saved in the plan. Passing `-n` also makes the launcher set `java.awt.headless=true`, so the run needs no display. On the console you get the built-in Summariser's `summary` lines, `Created the tree successfully using plan.jmx` and `Starting standalone test @ ...`.

code

bash · 9 lines
bash
jmeter -n -t plan.jmx -l results.jtl -j nightly.log

# Creating summariser <summary>
# Created the tree successfully using plan.jmx
# Starting standalone test @ 2026 Sep 9 02:00:00 GMT+02:00 (1788912000000)
# Waiting for possible Shutdown/StopTestNow/HeapDump/ThreadDump message on port 4445
# summary +   1200 in 00:00:30 =   40.0/s Avg:   118 Min:    41 Max:  2011 Err:     0 (0.00%) Active: 50 Started: 50 Finished: 0
# Tidying up ...    @ 2026 Sep 9 02:10:00 GMT+02:00 (1788912600000)
# ... end of run

go deeper

for a junior

Be able to type the line from memory and say what each of -n, -t and -l names. Knowing that -n takes no value is half the marks.

for a middle

Explain that -l attaches an extra ResultCollector on top of the tree rather than replacing the plan's listeners, and that -n also forces headless AWT.

for a senior

Show what the run prints and what it does not: the Summariser lines, the UDP shutdown port, and the two silent-ish failures when -t is missing or unreadable.

for a principal

Own the decision that this line, not the GUI, is how load is driven in your organisation, and that its artefact paths are part of the standard rather than each engineer's habit.

## The three flags that make a load run `jmeter -n -t plan.jmx -l results.jtl` is the line the JMeter project itself prints as the recommended way to drive load, and it is three independent decisions: | Flag | Long form | Argument | What it does | |---|---|---|---| | `-n` | `--nongui` | none | Runs without the Swing window. `CLOptionDescriptor.ARGUMENT_DISALLOWED`, so `-n true` is a parse error. | | `-t` | `--testfile` | required | The `.jmx` file to load. Mandatory once `-n` is given. | | `-l` | `--logfile` | required | The JTL file every sample result is written to. Optional. | `jmeter -?` prints the whole option list; `jmeter -h` prints the usage text; `jmeter -v` prints the version banner. ## What `-n` changes besides hiding the window - The launcher scans the raw argument array before JMeter proper starts. If it sees `-n`, `-s` or `-g` and `java.awt.headless` is not already set, it sets it to `true` — so a CLI run needs no display and no X server. - `startNonGui` sets the system property `JMeter.NonGui` to `"true"`, which samplers and scripts can read to tell the two modes apart. - The GUI-mode banner (`Don't use GUI mode for load testing !`) is printed by `JMeterGuiLauncher`, so it does **not** appear on a `-n` run. - `FileServer.setBaseForScript` is called with the `-t` file, which makes the plan's own relative file names resolve against the directory holding the `.jmx`. ## What `-l` adds, and what it does not remove `-l` is not a listener switch. JMeter builds a `ResultCollector`, points it at the file you named and adds it to the top of the already-loaded tree. Everything the plan itself carries still runs: 1. Listeners saved in the `.jmx` keep writing to their own configured files. 2. The `-l` collector writes one row per sample on top of that. 3. If `-l` is omitted altogether, no collector is added at all and the run leaves no JTL. That is why the project's own "reducing resource requirements" advice is to delete or disable the GUI listeners in the plan and rely on `-l` alone. ## What the console shows A CLI run is not silent. Left at stock settings it prints, in order: - `Creating summariser <summary>` — `bin/jmeter.properties` ships `summariser.name=summary` uncommented, so the built-in Summariser is on by default in CLI mode. - `Created the tree successfully using plan.jmx` - `Starting standalone test @ <date> (<epoch millis>)` - `Waiting for possible Shutdown/StopTestNow/HeapDump/ThreadDump message on port 4445` — the UDP control listener, whose port comes from `jmeterengine.nongui.port` (default `4445`, searching upward to `jmeterengine.nongui.maxport`, default `4455`). - periodic `summary +` interval lines while the test runs, each ending with `Active:`, `Started:` and `Finished:` thread counts, then `summary =` running totals. - `Tidying up ... @ <date>` and `... end of run` at the end. ## The rest of the line Other flags in the same family, all optional: - `-j` names JMeter's own run log (default `jmeter.log`), `-i` points at a `log4j2.xml` logging configuration, `-L` overrides a log level (`-Ljmeter.engine=DEBUG`, or bare `-LDEBUG` for the root logger). - `-f` deletes existing result files and the report folder before the run starts. - `-e` plus `-o` generate the HTML dashboard when the test finishes. - `-p` and `-q` point at property files; injecting individual properties is a separate subject and is not covered here. ## The two ways this line goes wrong - `-n` with no `-t`: `startNonGui` throws, the console shows `Incorrect Usage:Non-GUI runs require a test plan` followed by the option list, and nothing is sampled. - `-t` naming a file that is not there: the run fails with `The file <abs path> doesn't exist or can't be opened`. Neither of these is a JMeter bug — they are the two mistakes that produce an empty results directory and a job that looks like it ran.

  • What happens if you pass -n but leave out -t?
    No engine is ever started. JMeter throws an IllegalUserActionException, so the console shows `Incorrect Usage:Non-GUI runs require a test plan` followed by the full option list. No JTL is written and nothing is sampled, so a job that only checks for a crash will not notice.
  • Does -l switch off the listeners already saved in the plan?
    No. The `-l` collector is added on top of the loaded tree, so every listener in the `.jmx` still runs and still writes its own file. JMeter's own best-practice page tells you to delete or disable those GUI listeners and rely on `-l` alone.
  • Is -l required in CLI mode?
    No. If `-l` is absent JMeter adds no ResultCollector at all — only the Summariser, if `summariser.name` is set. The test runs and prints console totals, but leaves no results file behind unless a listener inside the plan writes one.

Think of it as a printer job: -n says do not open the preview window, -t is the document, -l is the receipt the job leaves behind.

saying these in an interview costs you the question

  • Says -n takes a value, such as -n true
  • Thinks -l names JMeter's own run log rather than the sample results
  • Claims -t is optional once -n is given
  • Assumes a CLI run still needs a display or an X server
  • Believes -l disables the listeners saved in the plan
open as a page

Why does Apache JMeter print a banner telling you not to load test in GUI mode?

level: juniorimportance: must knowfreq 74%

basics

~20 s

JMeter prints it on every GUI launch because the GUI is for creating and debugging a plan, not for driving load. The banner also gives the command line to use instead: jmeter -n -t [jmx file] -l [results file] -e -o [report folder].

open as a page

In Apache JMeter, what do the -J and -D command-line flags each define?

level: juniorimportance: must knowfreq 68%

basics

~10 s

JMeter's -J flag defines a JMeter property inside the running JMeter instance; -D defines a Java system property in the JVM. Both take name=value, may be repeated, and are applied while JMeter starts up.

open as a page

Which JMeter CLI flag stops a nightly `-l results.jtl` run from appending to last night's rows?

level: middleimportance: should knowfreq 52%

basics

~20 s

The -f flag, long form --forceDeleteResultFile. It deletes existing results files and the web report folder before the test starts. Without it, JMeter opens an existing CSV results file in append mode and never rewrites the header.

open as a page

Why does JMeter, not the JVM, handle a -D flag typed on the jmeter command line?

level: middleimportance: should knowfreq 41%

basics

~10 s

The bin/jmeter launcher places everything you type after -jar ApacheJMeter.jar, so the JVM treats it as an application argument. JMeter's own parser matches -D and calls System.setProperty during its startup.

open as a page

What does JMeter's -p flag replace, and what does -q add on top of it?

level: middleimportance: should knowfreq 34%

basics

~10 s

JMeter's -p names the base property file to load instead of bin/jmeter.properties and may appear only once. -q names an extra property file merged on top of the current set, and may be repeated.

open as a page

Why does night two of `jmeter -n -t plan.jmx -l r.jtl -e -o report` fail before any sampling?

level: seniorimportance: should knowfreq 46%

basics

~20 s

The -o folder must not exist or must be empty. JMeter checks it before loading the plan, so the first night's dashboard files make the second night abort with 'Cannot write to ... as folder is not empty' and exit status 1.

open as a page

A JMeter run with -Jenv.host=prod.internal -q staging.properties still hits staging. Why?

level: seniorimportance: should knowfreq 27%

basics

~10 s

JMeter applies command-line property options in the order they appear. The -q file is read after the -J flag and copies its own env.host over the value the flag had just set.

open as a page

How would you standardise the JMeter CLI line and artefact paths a team's nightly load run uses?

level: principalimportance: should knowfreq 36%

basics

~20 s

Fix one canonical invocation: absolute paths or a fixed working directory, an explicit .jmx rather than LAST, clean artefacts each run via -f or a fresh name, -e paired with -l and an empty -o folder, and the run log kept somewhere readable.

open as a page

One JMeter plan serves staging and production. Which values would you pass as -J flags and which in a -q file?

level: principalimportance: should knowfreq 32%

basics

~20 s

Put each environment's stable values in a reviewable -q property file per environment, and reserve -J for the few values that genuinely vary run to run. Keep credentials out of -J, whose value JMeter logs verbatim.

open as a page

What does Apache JMeter resolve the special file name `LAST` to in `-t LAST`?

level: middleimportance: nice to knowfreq 22%

basics

~20 s

The most recently opened test plan from the JMeter GUI's Open Recent list, which lives in the Java user preferences node for LoadRecentProject. On a host where that user never ran the GUI it resolves to nothing.

open as a page

In JMeter, what does the -G flag do with an argument that contains no equals sign?

level: seniorimportance: nice to knowfreq 19%

basics

~20 s

JMeter reads the whole argument as a path to a properties file and loads every key in it into the global property set. If that path cannot be read, JMeter does nothing and logs nothing.

open as a page