Introduction

Starting a Spring Boot application from the command line is the most direct way to validate builds, run services in CI, and reproduce production startup behavior locally. You can launch either from source using Maven or Gradle, or from a packaged jar using java -jar. A clean command line workflow also makes profile and environment debugging much easier.

Verify Tooling and Project State

Before startup, confirm Java and build tooling versions to avoid hidden environment mismatch.

java -version
mvn -v
./gradlew -v

At project root, verify that one of these files exists:

• pom.xml for Maven.
• build.gradle or build.gradle.kts for Gradle.

Also ensure your main class has @SpringBootApplication and is reachable by package scanning.

Run Directly from Source During Development

Running from source gives fast feedback for code changes.

Maven:

mvn spring-boot:run

Gradle:

./gradlew bootRun

Pass profile and custom properties during startup:

mvn spring-boot:run -Dspring-boot.run.profiles=dev -Dspring-boot.run.arguments="--server.port=8081"

For Gradle:

./gradlew bootRun --args='--spring.profiles.active=dev --server.port=8081'

Use this mode when you need rapid iteration and do not require packaging artifacts.

Package and Run as Executable Jar

For CI and production-like validation, build once and run the artifact.

Maven package:

mvn clean package -DskipTests
java -jar target/myapp-0.0.1-SNAPSHOT.jar

Gradle package:

./gradlew clean bootJar
java -jar build/libs/myapp-0.0.1-SNAPSHOT.jar

Running jar mode helps catch issues related to packaging, classpath, and startup scripts that may not appear in source run mode.

Configure Environment and Secrets Safely

Spring Boot reads configuration from command args, environment variables, and application files. Keep secrets out of shell history when possible.

Example with environment variables:

1export SPRING_PROFILES_ACTIVE=prod
2export SPRING_DATASOURCE_URL='jdbc:postgresql://db.internal:5432/appdb'
3export SPRING_DATASOURCE_USERNAME='app_user'
4export SPRING_DATASOURCE_PASSWORD='change_me'
5
6java -jar target/myapp-0.0.1-SNAPSHOT.jar

For one off overrides, pass command line properties:

java -jar target/myapp-0.0.1-SNAPSHOT.jar \
  --server.port=9090 \
  --logging.level.root=INFO

Prefer externalized config files for repeatable deploys.

Monitor Startup and Verify Health

After launch, inspect logs for profile, port, and datasource messages. Then verify health endpoint if Actuator is enabled.

curl -fsS http://localhost:8080/actuator/health

Check open port when debugging collisions:

lsof -i :8080

If startup hangs, run with debug condition report:

java -jar target/myapp-0.0.1-SNAPSHOT.jar --debug

This report is useful for diagnosing auto configuration conflicts.

Run in the Background for Local Service Testing

For integration tests that need the app running in background, use nohup and capture logs.

nohup java -jar target/myapp-0.0.1-SNAPSHOT.jar > app.log 2>&1 &
echo $! > app.pid

Stop later:

kill "$(cat app.pid)"

Keep background process management simple and explicit to avoid orphan processes.

Add JVM Options for Production-Like Runs

When startup behavior differs between environments, run the jar with explicit JVM settings to reduce ambiguity. This is useful for memory diagnostics and reproducible performance tests.

1java \
2  -Xms512m \
3  -Xmx1024m \
4  -XX:+UseG1GC \
5  -jar target/myapp-0.0.1-SNAPSHOT.jar \
6  --spring.profiles.active=prod

Keep JVM flags in versioned run scripts so team members and CI jobs execute the same runtime profile.

Common Pitfalls

• Running with one Java version locally and another in CI.
• Assuming bootRun behavior matches packaged jar behavior exactly.
• Hard coding secrets in command history or source files.
• Ignoring profile activation and debugging wrong config values.
• Forgetting to verify startup health before running dependent services.

Summary

• Use spring-boot:run or bootRun for fast source based development.
• Use packaged jar startup to validate production like runtime behavior.
• Pass profiles and properties explicitly to avoid configuration ambiguity.
• Verify startup through logs, port checks, and health endpoints.
• Keep process and secret management disciplined for reliable CLI workflows.
• Keep JVM options documented for reproducible operations.