#1457: Improve CLI error messages with suggestions by KarimALotfy · Pull Request #1858 · devonfw/IDEasy

KarimALotfy · 2026-04-27T08:22:41Z

Improve CLI error messages with suggestions

This PR fixes #1457

Implemented changes:

Add clearer messages when a command requires IDEasy project context.
Detect unknown options or invalid arguments and values, and suggest the closest valid option (Did you mean ...).
Suggest closest commandlet name for unknown commands.
Suggesting available installation versions, when the entered version cannot be matched
(Reused from PR : "#1643 improve ux on syntax error #1856" of improve UX on CLI syntax error #1643 by @satorus )
Add tests for the new suggestion flows

Checklist for this PR

Make sure everything is checked before merging this PR. For further info please also see
our DoD.

When running mvn clean test locally all tests pass and build is successful
PR title is of the form #«issue-id»: «brief summary» (e.g. #921: fixed setup.bat). If no issue ID exists, title only.
PR top-level comment summarizes what has been done and contains link to addressed issue(s)
PR and issue(s) have suitable labels
Issue is set to In Progress and assigned to you or there is no issue (might happen for very small PRs)
You followed all coding conventions
You have added the issue implemented by your PR in CHANGELOG.adoc unless issue is labeled
with internal

- Add clearer messages when a command requires IDEasy project context. - Detect unknown options and suggest the closest valid option (Did you mean ...). - Suggest closest commandlet name for unknown commands. - Add tests for the new suggestion flows

coveralls · 2026-04-27T08:27:31Z

Coverage Report for CI Build 26649937969

Coverage increased (+0.09%) to 71.203%

Details

Coverage increased (+0.09%) from the base build.
Patch coverage: No coverable lines changed in this PR.
239 coverage regressions across 5 files.

Uncovered Changes

No uncovered changes found.

Coverage Regressions

239 previously-covered lines in 5 files lost coverage.

File	Lines Losing Coverage	Coverage
com/devonfw/tools/ide/context/AbstractIdeContext.java	175	66.83%
com/devonfw/tools/ide/property/Property.java	33	72.59%
com/devonfw/tools/ide/version/VersionIdentifier.java	23	81.12%
com/devonfw/tools/ide/validation/ValidationState.java	5	85.96%
com/devonfw/tools/ide/version/VersionSegment.java	3	88.19%

Coverage Stats


Relevant Lines:	15872
Covered Lines:	11796
Line Coverage:	74.32%
Relevant Branches:	7148
Covered Branches:	4595
Branch Coverage:	64.28%
Branches in Coverage %:	Yes
Coverage Strength:	3.15 hits per line

💛 - Coveralls

…nvalid-args-or-commandlets

-Added Error handling for Invalid Arguments -Added in ClI Error the installable Versions as a suggestion when an unfound version is entered

…-invalid-args-or-commandlets"

…-or-commandlets' of https://github.com/KarimALotfy/IDEasy into feature/1457-improve-CLI-error-messages-on-invalid-args-or-commandlets

MarvMa

Nice Work! This will help users in the future to understand incorrect inputs better and even get a recommendation. I tested the functionality on Windows using the following tests:

delete settings file -> run ide update -> the expected warning is beeing printed
run ide udpate -> a suggestion is beeing printed

I left some comments regarding the naming of boolean methods and a comment on a nested if else clause. Except that everything looks fine to me 🚀

- Refactored methods in CliSuggester to match coding-conventions - Improved readability in run method in AbstractIdeContext by reducing nested code - Change in CHANGELOG.adoc

…r-messages-on-invalid-args-or-commandlets"

…nvalid-args-or-commandlets

MarvMa

Looks really clean, Nice Job 💯

…nvalid-args-or-commandlets

hohwille

@KarimALotfy Wow. Thank you for your great PR. I looked at your test and immediately saw the beauty of your solution that brings great UX. Digging in your implementation I found that you used established IT algorithm (levenshtein distance) as a pattern to this problem. Awesome job 🥇
I really want to get this merged.
Sorry that I still have some review-comments and one is just a stupid question where I could not understand something. Typically, we can just resolve that thread but hopefully you can answer the question quickly to enlighten me. 😄

hohwille · 2026-05-29T15:59:29Z

      if (cmd.isIdeHomeRequired() && (this.ideHome == null)) {
        throw new CliException(getMessageNotInsideIdeProject(), ProcessResult.NO_IDE_HOME);
      } else if (cmd.isIdeRootRequired() && (this.ideRoot == null)) {
        throw new CliException(getMessageIdeRootNotFound(), ProcessResult.NO_IDE_ROOT);
      }


shouldn't we log better feedback here?
We are throwing an exception here.
If I am not mistaken, this is not handled to invoke isMissingProjectContextHandled or am I missing something?

Seems I am missing something. I was expecting that when we iterate over each commandlet and found one that is matching but has no project but requires one we would throw an exception here that is not catched in the while loop over all commandlets and therefore your new code after that loop is never executed.
However, my assumption since your test is green.
For today I want to complete the review and will not be able to debug and find it out but this confused me and maybe this should indicate we should rework something that is slightly odd.

hohwille · 2026-05-29T16:05:14Z

+
+    String name = commandlet.getName();
+
+    step.error("The {} commandlet requires to be an IDEasy project to work.", name);


Message sounds confusing (a commandlet is never an IDEasy project).
You maybe should also add this to the log message:

IDEasy/cli/src/main/java/com/devonfw/tools/ide/context/AbstractIdeContext.java

Lines 393 to 396 in be13f96

private String getMessageNotInsideIdeProject() {

return "You are not inside an IDE project: " + formatArgument(this.cwd);

}

Suggested change

step.error("The {} commandlet requires to be an IDEasy project to work.", name);

step.error("The {} commandlet requires an IDEasy project to work.", name);

Sorry, I just saw that I wrote this grammatically wrong message as suggestion in the story. So my bad and thanks for improving anyway 🙏

hohwille · 2026-05-29T16:25:13Z

+  /**
+   * Finds the {@link Commandlet} with the given name.
+   *
+   * @param name the name of the {@link Commandlet} to find.
+   * @return the {@link Commandlet} with the given name or {@code null} if no such {@link Commandlet} exists.
+   */
+  private Commandlet findCommandletByName(String name) {
+    if (name == null) {
+      return null;
+    }
+    for (Commandlet c : this.commandletManager.getCommandlets()) {
+      if (name.equals(c.getName())) {
+        return c;
+      }
+    }
+    return null;
+  }


Why not using this that gives us the same result in O(1) (from a map)?

IDEasy/cli/src/main/java/com/devonfw/tools/ide/commandlet/CommandletManagerImpl.java

Lines 232 to 235 in be13f96

public Commandlet getCommandlet(String name) {

return this.commandletNameMap.get(name);

}

…nvalid-args-or-commandlets

github-project-automation Bot added this to IDEasy board Apr 27, 2026

github-project-automation Bot moved this to 🆕 New in IDEasy board Apr 27, 2026

Merge branch 'main' into feature/1457-improve-CLI-error-messages-on-i…

69f2d9d

…nvalid-args-or-commandlets

KarimALotfy self-assigned this Apr 27, 2026

KarimALotfy moved this from 🆕 New to Team Review in IDEasy board Apr 27, 2026

Merge branch 'main' into feature/1457-improve-CLI-error-messages-on-i…

9e06ac6

…nvalid-args-or-commandlets

satorus mentioned this pull request Apr 28, 2026

#1643 improve ux on syntax error #1856

Closed

15 tasks

KarimALotfy moved this from Team Review to 🏗 In progress in IDEasy board Apr 30, 2026

KarimALotfy added 3 commits April 30, 2026 14:30

devonfw#1788:

2813996

-Added Error handling for Invalid Arguments -Added in ClI Error the installable Versions as a suggestion when an unfound version is entered

Merge branch "main" into "(feature/1457-improve-CLI-error-messages-on…

540e766

…-invalid-args-or-commandlets"

Merge branch 'feature/1457-improve-CLI-error-messages-on-invalid-args…

ab8d3e2

…-or-commandlets' of https://github.com/KarimALotfy/IDEasy into feature/1457-improve-CLI-error-messages-on-invalid-args-or-commandlets

KarimALotfy moved this from 🏗 In progress to Team Review in IDEasy board Apr 30, 2026

KarimALotfy added enhancement New feature or request CLI IDEasy command-line-interface (parsing args, etc.) labels Apr 30, 2026

AdemZarrouki assigned MarvMa May 6, 2026

MarvMa approved these changes May 6, 2026

View reviewed changes

Comment thread cli/src/main/java/com/devonfw/tools/ide/cli/CliSuggester.java

Comment thread cli/src/main/java/com/devonfw/tools/ide/context/AbstractIdeContext.java Outdated

Comment thread CHANGELOG.adoc Outdated

KarimALotfy added 2 commits May 7, 2026 17:21

devonfw#1457: Refactoring

f7542b5

- Refactored methods in CliSuggester to match coding-conventions - Improved readability in run method in AbstractIdeContext by reducing nested code - Change in CHANGELOG.adoc

devonfw#1457: Merge branch "main" into "feature/1457-improve-CLI-erro…

f96fc29

…r-messages-on-invalid-args-or-commandlets"

KarimALotfy moved this from Team Review to 👀 In review in IDEasy board May 8, 2026

KarimALotfy moved this from 👀 In review to Team Review in IDEasy board May 8, 2026

KarimALotfy moved this from Team Review to 👀 In review in IDEasy board May 11, 2026

Merge branch 'main' into feature/1457-improve-CLI-error-messages-on-i…

cd45c1e

…nvalid-args-or-commandlets

MarvMa reviewed May 12, 2026

View reviewed changes

laim2003 mentioned this pull request May 13, 2026

Implement levenshtein distance for matching potential commands against (accidental) wrongful inputs #1934

Closed

KarimALotfy added 2 commits May 18, 2026 10:42

Merge branch 'main' into feature/1457-improve-CLI-error-messages-on-i…

9d92840

…nvalid-args-or-commandlets

Merge branch 'main' into feature/1457-improve-CLI-error-messages-on-i…

0e9b7d7

…nvalid-args-or-commandlets

hohwille approved these changes May 29, 2026

View reviewed changes

hohwille added this to the release:2026.06.001 milestone May 29, 2026

Merge branch 'main' into feature/1457-improve-CLI-error-messages-on-i…

5bf2c49

…nvalid-args-or-commandlets

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

#1457: Improve CLI error messages with suggestions#1858

#1457: Improve CLI error messages with suggestions#1858
KarimALotfy wants to merge 12 commits into
devonfw:mainfrom
KarimALotfy:feature/1457-improve-CLI-error-messages-on-invalid-args-or-commandlets

KarimALotfy commented Apr 27, 2026 •

edited

Loading

Uh oh!

coveralls commented Apr 27, 2026 •

edited

Loading

Uh oh!

MarvMa left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

MarvMa left a comment

Uh oh!

hohwille left a comment

Uh oh!

hohwille May 29, 2026

Uh oh!

hohwille May 29, 2026

Uh oh!

hohwille May 29, 2026

Uh oh!

hohwille May 29, 2026

Uh oh!

Uh oh!

hohwille May 29, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants


		String name = commandlet.getName();

		step.error("The {} commandlet requires to be an IDEasy project to work.", name);

	private String getMessageNotInsideIdeProject() {

	return "You are not inside an IDE project: " + formatArgument(this.cwd);
	}

	step.error("The {} commandlet requires to be an IDEasy project to work.", name);
	step.error("The {} commandlet requires an IDEasy project to work.", name);

	public Commandlet getCommandlet(String name) {

	return this.commandletNameMap.get(name);
	}

Conversation

KarimALotfy commented Apr 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

This PR fixes #1457

Implemented changes:

Checklist for this PR

Uh oh!

coveralls commented Apr 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Coverage Report for CI Build 26649937969

Coverage increased (+0.09%) to 71.203%

Details

Uncovered Changes

Coverage Regressions

Coverage Stats

💛 - Coveralls

Uh oh!

MarvMa left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

MarvMa left a comment

Choose a reason for hiding this comment

Uh oh!

hohwille left a comment

Choose a reason for hiding this comment

Uh oh!

hohwille May 29, 2026

Choose a reason for hiding this comment

Uh oh!

hohwille May 29, 2026

Choose a reason for hiding this comment

Uh oh!

hohwille May 29, 2026

Choose a reason for hiding this comment

Uh oh!

hohwille May 29, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

hohwille May 29, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

KarimALotfy commented Apr 27, 2026 •

edited

Loading

coveralls commented Apr 27, 2026 •

edited

Loading