Master Spring Boot Command-Line Arguments: Usage, Retrieval, and Source Code

Overview

Spring Boot applications can be started with java -jar and accept command‑line arguments for configuration. These arguments come in three forms—option parameters, non‑option parameters, and system parameters—and have different precedence and injection mechanisms.

Command‑Line Parameter Usage

Typical usage to change the server port: java -jar xxx.jar --server.port=8081 The option parameter --server.port=8081 overrides the default port 8080 and has higher priority than properties defined elsewhere.

Parameter Types

Option parameters (e.g., --name=value)

Non‑option parameters (plain arguments without --)

System parameters (prefixed with -D)

Option Parameters

Format: --name=value. Equivalent to setting server.port=8081 in application.properties.

Non‑Option Parameters

java -jar xxx.jar abc def

Here abc and def are non‑option arguments.

System Parameters

java -jar -Dserver.port=8081 xxx.jar

System parameters are passed to the JVM and become system properties.

Retrieving Parameter Values

Both option and non‑option parameters can be accessed via the ApplicationArguments interface. Inject it into a component:

@RestController
public class ArgumentsController {
    @Resource
    private ApplicationArguments arguments;
}

Methods such as getOptionNames(), getOptionValues(name), and getNonOptionArgs() provide the values.

Option parameters can also be injected directly with @Value:

@RestController
public class ParamController {
    @Value("${server.port}")
    private String serverPort;
}

System parameters are accessible via System.getProperty("server.port"):

String systemServerPort = System.getProperty("server.port");

Key Differences

When using -D, the system parameter must appear before the JAR name; otherwise the JVM throws an Unrecognized option error or the parameter is ignored. Also, @Value can resolve both option and system parameters, while System.getProperty only retrieves system parameters.

ApplicationArguments Implementation

During SpringApplication.run(...), the raw String[] args are wrapped in a DefaultApplicationArguments instance, which implements ApplicationArguments. The relevant snippet:

public ConfigurableApplicationContext run(String... args) {
    ApplicationArguments applicationArguments = new DefaultApplicationArguments(args);
    // ...
}

DefaultApplicationArguments

stores the original arguments and delegates parsing to an inner Source class, which extends SimpleCommandLinePropertySource. That class creates a SimpleCommandLineArgsParser to split arguments based on the -- prefix and = separator.

class SimpleCommandLineArgsParser {
    public CommandLineArgs parse(String... args) {
        CommandLineArgs commandLineArgs = new CommandLineArgs();
        for (String arg : args) {
            if (arg.startsWith("--")) {
                // parse option
                String optionText = arg.substring(2);
                String optionName;
                String optionValue = null;
                if (optionText.contains("=")) {
                    optionName = optionText.substring(0, optionText.indexOf('='));
                    optionValue = optionText.substring(optionText.indexOf('=') + 1);
                } else {
                    optionName = optionText;
                }
                commandLineArgs.addOptionArg(optionName, optionValue);
            } else {
                commandLineArgs.addNonOptionArg(arg);
            }
        }
        return commandLineArgs;
    }
}

This simple rule distinguishes option arguments (starting with --) from non‑option arguments.

Injection into Spring Context

After creating the ApplicationArguments object, Spring registers it as a singleton named springApplicationArguments in the bean factory:

private void prepareContext(ConfigurableApplicationContext context,
                           ConfigurableEnvironment environment,
                           SpringApplicationRunListeners listeners,
                           ApplicationArguments applicationArguments,
                           Banner printedBanner) {
    ConfigurableListableBeanFactory beanFactory = context.getBeanFactory();
    beanFactory.registerSingleton("springApplicationArguments", applicationArguments);
}

Thus, any bean can @Resource‑inject ApplicationArguments and access the parsed command‑line data.

Conclusion

The article provides a complete walkthrough of how Spring Boot handles command‑line arguments: from the syntax used when launching a JAR, through retrieval via ApplicationArguments, @Value, or System.getProperty, to the underlying source‑code classes that parse and inject these arguments into the application context.