Guillaume Nodet created CAMEL-23236:
---------------------------------------
Summary: camel-jbang - Improve beginner UX with interactive init,
top-level doc, and contextual shell help
Key: CAMEL-23236
URL: https://issues.apache.org/jira/browse/CAMEL-23236
Project: Camel
Issue Type: Improvement
Components: camel-jbang
Reporter: Guillaume Nodet
h2. Overview
This is an umbrella improvement to make the Camel JBang CLI more approachable
for beginners. The current CLI is powerful but assumes users already know what
they want — component names, template file extensions, command hierarchy. These
changes reduce the "I don't know where to start" friction without compromising
the experience for power users.
*Key principles:*
* _Opt-in interactivity_ — interactive features only activate when no arguments
are given; scripted/CI usage is never affected
* _Don't reinvent_ — build on existing infrastructure (CatalogDoc,
SuggestSimilarHelper, JLine 4 ShellBuilder, plugin system)
* _Keep commands flat_ — prefer top-level aliases over deeply nested subcommands
h2. Detailed Plan
h3. 1. {{camel doc}} as a top-level alias (trivial)
{{camel catalog doc kafka}} already works and is comprehensive (URI syntax,
path/query params, dependencies, "did you mean?" fuzzy matching, {{--open-url}}
for browser). The problem is discoverability — beginners don't think to look
under {{catalog}}.
*Change:* Register {{CatalogDoc}} as a top-level subcommand {{doc}} in
{{CamelJBangMain}}, in addition to its existing location under {{catalog}}.
This is a ~5-line change.
*Optionally:* Add a {{--example}} flag that prints a minimal working route
snippet for the given component (e.g., a timer-to-log YAML route for the
{{timer}} component). Data can come from the catalog or curated snippets.
h3. 2. Context-aware shell banner (low effort)
The shell already prints a banner on startup ("Apache Camel JBang Shell
v4.19.0"). Make it context-aware:
{code}
Apache Camel JBang Shell v4.19.0
No routes found in current directory.
Quick start: init MyRoute.yaml && run *
Templates: init --list
Docs: doc <component>
Need help? help
{code}
When routes *are* present, show a different hint:
{code}
Apache Camel JBang Shell v4.19.0
Found 3 routes in current directory.
Run: run *
Watch: run * --dev
{code}
This replaces the idea of a first-run wizard — it's non-blocking, informative,
and doesn't interrupt experienced users. Implementation lives in
{{Shell.printBanner()}}.
h3. 3. Interactive {{camel init}} template picker (medium effort)
When {{camel init}} is invoked with *no arguments* in an interactive terminal,
show an interactive template picker using JLine instead of printing an error.
*Behavior:*
* Present categories (Routes, Kamelets, Pipes, REST) with numbered options
* User picks a category, then a template
* Prompt for filename
* Generate the file and print "Next steps" instructions
*Non-interactive behavior is unchanged:* {{camel init MyRoute.yaml}} works
exactly as before. The interactive picker is only triggered when: no positional
arg is given AND stdin is a TTY AND not in CI.
*Consider also:* Recipe-style templates that produce working examples (e.g.,
"timer to log", "REST API with mock data", "file polling to Kafka") rather than
empty scaffolds. These would be additional {{.tmpl}} files selected through the
picker.
h3. 4. {{camel run --example}} — zero to running in one command (medium effort)
Allow running built-in examples without creating any files first:
{code}
camel run --example timer-log
camel run --example rest-api
camel run --example file-to-kafka
{code}
This is the absolute fastest on-ramp for beginners. Internally, these are
bundled route files (YAML or Java) that are extracted to a temp directory and
run. Combine with {{--dev}} mode for a "playground" experience.
{{camel run --example --list}} would show available examples.
h3. 5. Extend "did you mean?" to more commands (low effort)
{{SuggestSimilarHelper}} is already used in {{CatalogDoc}} for fuzzy matching
component/kamelet names. Extend its usage to:
* {{camel run}} — when a component fails to resolve at runtime
* {{camel get component <name>}} — when querying a non-existent component
* Any other command that takes component/kamelet names as arguments
h3. 6. {{camel doctor}} diagnostic command (medium effort)
A diagnostic command that checks the environment and reports issues:
{code}
camel doctor
Java: 21.0.2 (OK)
JBang: 0.119.0 (OK)
Camel: 4.19.0
Maven: reachable (OK)
Docker: running (OK)
Disk space: OK
Known issues: none
{code}
Checks to include:
* Java version (21+ required)
* JBang version
* Maven central reachability
* Docker daemon status (relevant for testcontainers)
* Common port conflicts (8080, etc.)
* Disk space in temp/cache directories
h3. 7. Camel-Kit discoverability (low effort)
camel-kit already works as a plugin ({{camel plugin add kit --gav
io.github.luigidemasi:camel-jbang-plugin-kit:0.3.1}}). The problem is no one
knows it exists.
*Changes:*
* Add a mention in {{camel init --help}} footer: "Tip: For AI-assisted project
scaffolding, try: camel plugin add kit"
* Mention in the shell banner when no routes are detected
* Consider adding {{kit}} to the {{PluginType}} enum so {{camel plugin get
--all}} shows it as a known plugin
*Do NOT bundle camel-kit* as a built-in dependency — it's an external project.
Keep the loose coupling via the plugin system.
h2. Implementation Order
||Priority||Item||Effort||Impact||
|1|{{camel doc}} top-level alias|Trivial|High|
|2|Context-aware shell banner|Low|High|
|3|Interactive {{camel init}} picker|Medium|High|
|4|{{camel run --example}}|Medium|Very High|
|5|Extend "did you mean?" suggestions|Low|Medium|
|6|{{camel doctor}} command|Medium|Medium|
|7|Camel-Kit discoverability|Low|Medium|
Items 1-2 can be done in a single PR. Items 3-4 are the highest-impact changes
and could be separate PRs. Items 5-7 are incremental improvements.
h2. Related
* PR [#22193|https://github.com/apache/camel/pull/22193] — Adds example usage
snippets to CLI help text (complements this work)
* PR [#22197|https://github.com/apache/camel/pull/22197] — TUI dashboards
(camel monitor, camel catalog-tui)
* [camel-kit|https://github.com/luigidemasi/camel-kit] — AI-assisted Camel
development plugin
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
