apache · janhoy · Apr 5, 2026 · Apr 5, 2026 · Apr 5, 2026 · Apr 5, 2026
diff --git a/changelog/unreleased/SOLR-17697-picocli.yml b/changelog/unreleased/SOLR-17697-picocli.yml
@@ -0,0 +1,8 @@
+title: Add picocli as a dependency to enable migration of CLI tools away from commons-cli
+type: other
+authors:
+  - name: Jan Høydahl
+    url: https://home.apache.org/phonebook.html?uid=janhoy
+links:
+  - name: SOLR-17697
+    url: https://issues.apache.org/jira/browse/SOLR-17697
diff --git a/dev-docs/ref-guide/antora.adoc b/dev-docs/ref-guide/antora.adoc
@@ -45,6 +45,38 @@ Instead, update `antora.template.yaml`, and `gradlew buildLocalSite` will build
 
 The only reason you will likely need to change the `antora.template.yml` is if you are introducing new variables for dependency versions.
 
+== Auto-generated CLI Reference Pages
+
+The `bin/solr` command-line tool documentation is partially auto-generated from the picocli `@Command`, `@Option`, and `@Parameters` annotations in the Java source.
+
+=== How it works
+
+For each command registered in `org.apache.solr.cli.SolrCLI` that uses picocli annotations, a dedicated AsciiDoc page is generated by `picocli.codegen.docgen.manpage.ManPageGenerator` and committed to:
+
+----
+solr/solr-ref-guide/modules/deployment-guide/pages/cli/
+----
+
+The generated pages are post-processed to be Antora-compatible (correct page title, `:page-toclevels:` attribute, ASF license header, DO NOT EDIT notice).
+The navigation section in `deployment-nav.adoc` between the `// CLI-DOCS-START` and `// CLI-DOCS-END` markers is also updated automatically.
+
+The main landing page `solr-control-script-reference.adoc` provides an overview of the available tools with links to each man-page.
+
+=== Gradle targets
+
+`./gradlew :solr:solr-ref-guide:generateCliDocs`::
+Regenerates all pages under `pages/cli/` from the current picocli annotations and updates the nav.
+Run this after modifying any `@Command`, `@Option`, or `@Parameters` annotation in `solr/core/src/java/org/apache/solr/cli/`.
+
+`./gradlew :solr:solr-ref-guide:checkCliDocsUpToDate`::
+Verifies that the committed pages in `pages/cli/` are in sync with the current annotations.
+This target is wired into `gradlew check`, so CI will catch annotation changes that were not followed by a `generateCliDocs` run.
+
+=== Adding docs for a new tool
+
+The new command will automatically appear in the generated pages and the navigation when running `gradlew generateCliDocs`.
+You will need to tie it in to the `solr-control-script-reference.adoc` yourself.
+
 == Building the HTML Site
 
 A Gradle target `gradlew buildLocalSite` will build the full HTML site (found in `solr/solr-ref-guide/build/site`).

diff --git a/gradle/java/javac.gradle b/gradle/java/javac.gradle
@@ -62,7 +62,8 @@ allprojects {
           "-Xlint:text-blocks",
           "-proc:none",  // proc:none was added because of LOG4J2-1925 / JDK-8186647
           "-Xlint:removal",
-          "--should-stop=ifError=FLOW" // error-prone 2.41
+          "--should-stop=ifError=FLOW", // error-prone 2.41
+          "-Aproject=${project.group}/${project.name}"
       ]
 
       if (propertyOrDefault("javac.failOnWarnings", true).toBoolean()) {

diff --git a/gradle/libs.versions.toml b/gradle/libs.versions.toml
@@ -184,6 +184,7 @@ ow2-asm = "9.10.1"
 owasp-dependencycheck = "12.2.2"
 # @keep for version alignment
 perfmark = "0.27.0"
+picocli = "4.7.6"
 prometheus-metrics = "1.1.0"
 quicktheories = "0.26"
 semver4j = "6.0.0"
@@ -504,6 +505,8 @@ ow2-asm-commons = { module = "org.ow2.asm:asm-commons", version.ref = "ow2-asm"
 ow2-asm-tree = { module = "org.ow2.asm:asm-tree", version.ref = "ow2-asm" }
 # @keep transitive dependency for version alignment
 perfmark-api = { module = "io.perfmark:perfmark-api", version.ref = "perfmark" }
+picocli = { module = "info.picocli:picocli", version.ref = "picocli" }
+picocli-codegen = { module = "info.picocli:picocli-codegen", version.ref = "picocli" }
 prometheus-metrics-expositionformats = { module = "io.prometheus:prometheus-metrics-exposition-formats", version.ref = "prometheus-metrics" }
 prometheus-metrics-model = { module = "io.prometheus:prometheus-metrics-model", version.ref = "prometheus-metrics" }
 quicktheories-quicktheories = { module = "org.quicktheories:quicktheories", version.ref = "quicktheories" }

diff --git a/solr/api/gradle.lockfile b/solr/api/gradle.lockfile
@@ -39,6 +39,7 @@ com.tdunning:t-digest:3.3=jarValidation,testRuntimeClasspath
 commons-cli:commons-cli:1.11.0=jarValidation,testRuntimeClasspath
 commons-codec:commons-codec:1.22.0=jarValidation,testRuntimeClasspath
 commons-io:commons-io:2.22.0=jarValidation,testCompileClasspath,testRuntimeClasspath
+info.picocli:picocli:4.7.6=jarValidation,testRuntimeClasspath
 io.dropwizard.metrics:metrics-core:4.2.39=jarValidation,testRuntimeClasspath
 io.github.classgraph:classgraph:4.8.184=swaggerBuild
 io.github.eisop:dataflow-errorprone:3.41.0-eisop1=annotationProcessor,errorprone,testAnnotationProcessor

diff --git a/solr/benchmark/gradle.lockfile b/solr/benchmark/gradle.lockfile
@@ -35,6 +35,7 @@ com.tdunning:t-digest:3.3=jarValidation,runtimeClasspath,testRuntimeClasspath
 commons-cli:commons-cli:1.11.0=jarValidation,runtimeClasspath,testRuntimeClasspath
 commons-codec:commons-codec:1.22.0=jarValidation,runtimeClasspath,testRuntimeClasspath
 commons-io:commons-io:2.22.0=compileClasspath,jarValidation,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
+info.picocli:picocli:4.7.6=jarValidation,runtimeClasspath,testRuntimeClasspath
 io.dropwizard.metrics:metrics-core:4.2.39=jarValidation,runtimeClasspath,testRuntimeClasspath
 io.github.eisop:dataflow-errorprone:3.41.0-eisop1=annotationProcessor,errorprone,testAnnotationProcessor
 io.github.java-diff-utils:java-diff-utils:4.12=annotationProcessor,errorprone,testAnnotationProcessor

diff --git a/solr/bin/solr b/solr/bin/solr
@@ -828,7 +828,11 @@ if [ $# -gt 0 ]; then
             shift 2
         ;;
         -h|--help)
-            print_usage "$SCRIPT_CMD"
+            if [[ "${SOLR_PICOCLI:-}" == "true" ]]; then
+                run_tool "$SCRIPT_CMD" --help
+            else
+                print_usage "$SCRIPT_CMD"
+            fi
             exit 0
         ;;
         -y|--no-prompt)

diff --git a/solr/bin/solr.cmd b/solr/bin/solr.cmd
@@ -417,8 +417,22 @@ IF "%1"=="--all" goto set_stop_all
 :parse_general_args
 
 REM Print usage of command in case help option included
-IF "%1"=="--help" goto usage
-IF "%1"=="-h" goto usage
+IF "%1"=="--help" goto check_picocli_help
+IF "%1"=="-h" goto check_picocli_help
+goto after_help_check
+
+:check_picocli_help
+IF "%SOLR_PICOCLI%"=="true" goto run_picocli_help
+goto usage
+
+:run_picocli_help
+"%JAVA%" %SOLR_SSL_OPTS% %AUTHC_OPTS% %SOLR_ZK_CREDS_AND_ACLS% %SOLR_TOOL_OPTS% -Dsolr.install.dir="%SOLR_TIP%" ^
+  -Dlog4j.configurationFile="file:///%DEFAULT_SERVER_DIR%\resources\log4j2-console.xml" ^
+  -classpath "%SOLR_TIP%\lib\*;%DEFAULT_SERVER_DIR%\solr-webapp\webapp\WEB-INF\lib\*;%DEFAULT_SERVER_DIR%\lib\ext\*" ^
+  org.apache.solr.cli.SolrCLI %SCRIPT_CMD% --help
+goto done
+
+:after_help_check
 
 REM other args supported by all special commands
 IF "%1"=="-p" goto set_port

diff --git a/solr/core/build.gradle b/solr/core/build.gradle
@@ -96,6 +96,8 @@ dependencies {
   implementation libs.commonscodec.commonscodec
 
   implementation libs.commonscli.commonscli
+  implementation libs.picocli
+  annotationProcessor libs.picocli.codegen
 
   implementation libs.locationtech.spatial4j
 
@@ -200,3 +202,23 @@ dependencies {
 
   testImplementation libs.opentelemetry.sdk.testing
 }
+
+// Expose a configuration for CLI doc generation in the solr-ref-guide project.
+// This bundles the full runtime classpath plus picocli-codegen (ManPageGenerator)
+// and the compiled CLI classes so that generateCliDocs can invoke ManPageGenerator.
+configurations {
+  cliDocsRuntime {
+    canBeResolved = true
+    canBeConsumed = true
+    // Inherit all runtime dependencies (implementation + runtimeOnly transitively)
+    extendsFrom configurations.runtimeClasspath
+  }
+}
+
+dependencies {
+  // picocli-codegen provides ManPageGenerator (not in runtime, only needed for doc gen)
+  cliDocsRuntime libs.picocli.codegen
+  // Include the compiled CLI classes themselves
+  cliDocsRuntime files(sourceSets.main.output.classesDirs)
+  cliDocsRuntime files(sourceSets.main.output.resourcesDir)
+}