SOLR-18463: Rename Post Tool and Stream Tool to Post Command and Stream Command by serhiy-bzhezytskyy · Pull Request #4924 · apache/solr

serhiy-bzhezytskyy · 2026-09-20T13:08:13Z

https://issues.apache.org/jira/browse/SOLR-18463

Description

The ref guide has two pages, post-tool.adoc and stream-tool.adoc, that call bin/solr post and bin/solr stream "the Post Tool" and "the Stream Tool" (and, in two places, the one-word forms PostTool/StreamTool). Both used to be standalone tools, but are now bin/solr subcommands, so the "Tool" framing reads as if they were still separate products. The classes keep their Tool names; only what a user of bin/solr reads changes.

Solution

The pages are renamed to post-command.adoc and stream-command.adoc with the titles "Solr CLI Post Command" and "Solr CLI Stream Command". :page-aliases: keep post-tool.html and stream-tool.html working as redirects, and the navigation files point at the new pages. The prose says "Post command" / "Stream command" (lower case), with "Solr CLI Post command" on the first mention in tutorial-diy.adoc.
The text that bin/solr prints no longer says "Tool" or "Command": the --mode help of bin/solr post uses the wording suggested in review, the warning prefix PostTool: and the verbose completion message StreamTool -- Done. lose the class name. The --help output block on the Post Command page shows the same text.
All xref:...[] links to these pages use empty link text, so they pick up the new titles automatically.

Tests

./gradlew :solr:core:compileJava :solr:core:compileTestJava :solr:core:spotlessCheck -Pvalidation.errorprone=true is clean. PostToolTest (14 tests) and StreamToolTest (11 tests) pass. buildLocalAntoraSite and checkSiteLinks pass with no broken links; the only Antora messages are six (five warnings and one table-row error, in configsets-api, rule-based-authorization-plugin and document-enrichment-with-llms) that #4922 (SOLR-18464) fixed on main after this branch was cut; this PR does not touch those pages.

AI-assisted (Claude Sonnet 5).

…am Command Both were standalone tools historically and are now bin/solr subcommands, so calling them Tool alongside their own page titles and headings is no longer accurate. Left one occurrence untouched: the verbatim --help output on the Post Command page, which reflects the actual CLI text and would need a Java change, not a doc change.

serhiy-bzhezytskyy · 2026-09-20T13:08:22Z

@epugh tagging you since this is under SOLR-18459/SOLR-18463, which you filed.

epugh · 2026-09-21T21:02:15Z

 === Start an external Apache Tika Server

-Indexing binary files (PDF, DOCX, PPTX, etc.) with the Post Tool requires the Solr extraction module to be enabled and an external Apache Tika Server to be running. See xref:indexing-guide:indexing-with-tika.adoc#tika-server[Tika Server] for background. We will be running Tika Server using Docker.
+Indexing binary files (PDF, DOCX, PPTX, etc.) with the Post Command requires the Solr extraction module to be enabled and an external Apache Tika Server to be running. See xref:indexing-guide:indexing-with-tika.adoc#tika-server[Tika Server] for background. We will be running Tika Server using Docker.


if this is the first time we use "Post Command" can we do seomting like "Solr CLI Post command"?

Done — now reads "Solr CLI Post command" on first mention.

epugh · 2026-09-21T21:02:30Z


 Local Files with `bin/solr post`::
-If you have a local directory of files, the Post Tool (`bin/solr post`) can index a directory of files.
+If you have a local directory of files, the Post Command (`bin/solr post`) can index a directory of files.


command doesn't need to be capilized i don't htink?

Done — lowercased.

epugh · 2026-09-21T21:03:33Z

@@ -1,4 +1,4 @@
-= Post Tool
+= Post Command


Maybe Solr CLI Post Command? I think we should just keep post-tool for SEO... Though there is a redirect capablity in Ref Guide which means we could rename this somethin glike post-command.adoc??

Renamed to post-command.adoc with :page-aliases: post-tool.adoc, so post-tool.html still resolves — it redirects to the new page.

epugh · 2026-09-21T21:03:42Z

 // under the License.

-The Stream tool allows you to run a xref:streaming-expressions.adoc[] in Solr and see the results from the command line.
+The Stream Command allows you to run a xref:streaming-expressions.adoc[] in Solr and see the results from the command line.


same cmmand thing

Done — lowercased.

epugh · 2026-09-21T21:03:55Z

@@ -1,4 +1,4 @@
-= Stream Tool
+= Stream Command


Same "Solr CLI Stream Command"

Done — title is now "Solr CLI Stream Command".

epugh

Progress, I left feedback!

Rename post-tool.adoc/stream-tool.adoc to post-command.adoc/stream-command.adoc with page-aliases so the old SEO'd URLs keep resolving (via Antora's static redirect facility, confirmed by inspecting the built HTML). Prefix the page titles and each page's first mention with "Solr CLI" per review, and drop the capital "C" in "command" everywhere else it appears in running prose.

epugh · 2026-09-22T09:01:47Z

Great work @serhiy-bzhezytskyy ...... So looking at this more, and looking at the PostTool.java, and the fact that the name of the file is "PostTool" and then, looking at how we refer to things in #3254, for example "This tool does not yet support PicoCli", that then makes me feel like we need to either pick "Tool" or "Command" and then lean into the specific name, across BOTH the java code and the ref guide docs. That I think helps us the most, because we know how to grep for the code in both ref guide and source, etc.

For what it's worth, Picocli uses picocli.CommandLine.Command to annotate "this is a command"..... But again, we can use Tool...

@janhoy WDYT?

janhoy · 2026-09-22T09:25:41Z

For what it's worth, Picocli uses picocli.CommandLine.Command to annotate "this is a command"..... But again, we can use Tool...

These can be both tools and commands. The individual classes are tools, and they can be invoked either from the CLI in which case it makes sense to document it user-facing as a bin/solr command. But PostTool can also be run standalone or embedded in some other bootstrap I suppose (at least it could earlier). I think we should keep the Tool naming in the code but refer to them as commands in the context of bin/solr.

epugh · 2026-09-22T09:33:01Z

For what it's worth, Picocli uses picocli.CommandLine.Command to annotate "this is a command"..... But again, we can use Tool...

These can be both tools and commands. The individual classes are tools, and they can be invoked either from the CLI in which case it makes sense to document it user-facing as a bin/solr command. But PostTool can also be run standalone or embedded in some other bootstrap I suppose (at least it could earlier). I think we should keep the Tool naming in the code but refer to them as commands in the context of bin/solr.

I can get behind that. So then in places where we emit something via bin/solr, like the bin/solr post --help, we have some text that says "Which mode the Post tool is running". Maybe we need to look at the wording and see if we can do something work to avoid saying "Tool" or "Command" in that message. So, for the example I gave, we could change the help text to be:

Specifies how to run: 'files' crawls local directories, 'web' crawls websites, 'args' processes positional arguments, and 'stdin' reads standard input stream. Default: files.

I like that.

epugh · 2026-09-22T09:36:08Z

So, I hope this recasts where to go @serhiy-bzhezytskyy:

Let's be okay in change the java source, and see if the text that "bin/solr" dumps out can have some wordsmithing to avoid "Tool" or "Command" that isn't too crazy, lets do that.
I think we should okay with renaming the .adoc files.
can you add the http redirect in the ref guide so the old url still work?

The --mode help description, the warn() prefix, and the verbose completion message each named the class directly ("Post tool", "reads a command", "PostTool: WARNING:", "StreamTool -- Done."). None of that naming is needed for the text to make sense, so it is dropped rather than swapped for the other name. No other tool in this package prefixes its warnings with a class name.

serhiy-bzhezytskyy · 2026-09-22T11:36:32Z

Pushed a commit dropping the class-name wording from the printed text: the --mode help description, the warn() prefix, and the verbose completion message. No other tool in this package prefixes its warnings with a class name, so that's dropped rather than swapped for the other name.

The redirect for the third item is already live from the earlier commit - see the reply above on the post-tool.adoc:1 thread, post-tool.html/stream-tool.html redirect to the renamed pages.

…aming

…he guide The help text of bin/solr post --mode should not name the tool or the command, and the wording proposed in review does that. The Post Command page shows the printed help verbatim, so its --help block follows the new text; it still had the old sentence, the last "Post tool" left in the guide.

serhiy-bzhezytskyy · 2026-10-01T14:07:10Z

Used your wording for the --mode help text, and the --help block on the Post Command page shows it now. That block still had the old text after my last push, so it did not match what bin/solr post -h prints. The titles, the lower-case "command", the redirects from post-tool.html and stream-tool.html, and dropping the class names from the printed text were in the earlier commits.

epugh · 2026-10-01T20:22:43Z

          .argName("mode")
          .desc(
-              "Which mode the Post tool is running in, 'files' crawls local directory, 'web' crawls website, 'args' processes input args, and 'stdin' reads a command from standard in. default: files.")
+              "Which mode this runs in, 'files' crawls local directory, 'web' crawls website, 'args' processes input args, and 'stdin' reads from standard in. default: files.")


…am Command (#4924) (cherry picked from commit 6a25712)

…am Command (#4924) (cherry picked from commit 6a25712) (cherry picked from commit 2252e89)

github-actions Bot added the documentation Improvements or additions to documentation label Sep 20, 2026

epugh reviewed Sep 21, 2026

View reviewed changes

epugh requested changes Sep 21, 2026

View reviewed changes

github-actions Bot added the cat:cli label Sep 22, 2026

serhiy-bzhezytskyy added 2 commits October 1, 2026 17:05

Merge remote-tracking branch 'origin/main' into SOLR-18463-solr-cli-n…

a0aea57

…aming

epugh self-assigned this Oct 1, 2026

epugh added this to the 10.x milestone Oct 1, 2026

epugh reviewed Oct 1, 2026

View reviewed changes

epugh merged commit 6a25712 into apache:main Oct 1, 2026
5 of 6 checks passed

dsmiley pushed a commit that referenced this pull request Oct 3, 2026

SOLR-18463: Rename Post Tool and Stream Tool to Post Command and Stre…

2252e89

…am Command (#4924) (cherry picked from commit 6a25712)

asf-gitbox-commits pushed a commit that referenced this pull request Oct 6, 2026

SOLR-18463: Rename Post Tool and Stream Tool to Post Command and Stre…

04d5937

…am Command (#4924) (cherry picked from commit 6a25712) (cherry picked from commit 2252e89)

Conversation

serhiy-bzhezytskyy commented Sep 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Solution

Tests

Uh oh!

serhiy-bzhezytskyy commented Sep 20, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

epugh left a comment

Choose a reason for hiding this comment

Uh oh!

epugh commented Sep 22, 2026

Uh oh!

janhoy commented Sep 22, 2026

Uh oh!

epugh commented Sep 22, 2026

Uh oh!

epugh commented Sep 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

serhiy-bzhezytskyy commented Sep 22, 2026

Uh oh!

serhiy-bzhezytskyy commented Oct 1, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

serhiy-bzhezytskyy commented Sep 20, 2026 •

edited

Loading

epugh commented Sep 22, 2026 •

edited

Loading