This is an automated email from the ASF dual-hosted git repository. davsclaus pushed a commit to branch feature/CAMEL-23722-cli-docs-restructure in repository https://gitbox.apache.org/repos/asf/camel.git
commit 6d2d9da89df0f07bb15d0c38b69edfdd2f314479 Author: Claus Ibsen <[email protected]> AuthorDate: Tue Jun 9 20:55:12 2026 +0200 CAMEL-23722: Add AI Tools page and document missing CLI commands New page: camel-jbang-ai.adoc covering camel ask, explain, and harden. Document previously missing commands in existing pages: - Getting Started: camel shell, camel doctor - Installation: camel wrapper - Managing: camel restart, route-diagram, route-topology, cmd span, thread-dump - Data Transformation: camel eval expression Co-Authored-By: Claude Opus 4.6 <[email protected]> Signed-off-by: Claus Ibsen <[email protected]> --- docs/user-manual/modules/ROOT/nav.adoc | 1 + .../modules/ROOT/pages/camel-jbang-ai.adoc | 146 +++++++++++++++++++++ .../ROOT/pages/camel-jbang-getting-started.adoc | 24 ++++ .../ROOT/pages/camel-jbang-installation.adoc | 21 ++- .../modules/ROOT/pages/camel-jbang-managing.adoc | 81 ++++++++++++ .../ROOT/pages/camel-jbang-transforming.adoc | 21 +++ .../modules/ROOT/pages/camel-jbang.adoc | 3 + 7 files changed, 296 insertions(+), 1 deletion(-) diff --git a/docs/user-manual/modules/ROOT/nav.adoc b/docs/user-manual/modules/ROOT/nav.adoc index 9bd32e97eced..709ec4a344c5 100644 --- a/docs/user-manual/modules/ROOT/nav.adoc +++ b/docs/user-manual/modules/ROOT/nav.adoc @@ -12,6 +12,7 @@ *** xref:camel-jbang-dev-services.adoc[Dev Services] *** xref:camel-jbang-transforming.adoc[Data Transformation] *** xref:camel-jbang-devtools.adoc[Development Tools] +*** xref:camel-jbang-ai.adoc[AI Tools] *** xref:camel-jbang-debugging.adoc[Debugging] *** xref:camel-jbang-managing.adoc[Managing Integrations] *** xref:camel-jbang-projects.adoc[Export to Maven] diff --git a/docs/user-manual/modules/ROOT/pages/camel-jbang-ai.adoc b/docs/user-manual/modules/ROOT/pages/camel-jbang-ai.adoc new file mode 100644 index 000000000000..177eb7df62ca --- /dev/null +++ b/docs/user-manual/modules/ROOT/pages/camel-jbang-ai.adoc @@ -0,0 +1,146 @@ += Camel CLI - AI Tools + +The Camel CLI includes AI-powered commands that use large language models (LLMs) +to help you understand, troubleshoot, and secure your integrations. + +All three commands work with local models (Ollama) or cloud APIs (OpenAI, Anthropic). +The CLI auto-detects the LLM provider from environment variables or a locally running Ollama instance. + +== Ask — chat with a running integration + +The `camel ask` command is an AI agent that can inspect and interact with a live Camel process. +It has access to routes, health checks, metrics, tracing, endpoints, and more — and can +answer questions about what your integration is doing right now. + +[source,bash] +---- +camel ask "what routes are running?" +camel ask "why is my route failing?" --name=myApp +camel ask "are there any blocked exchanges?" +---- + +Start an interactive chat session by running without a question: + +[source,bash] +---- +camel ask +---- + +This opens a `ask>` prompt where you can have a multi-turn conversation, +with the AI maintaining context across questions. + +=== What the AI can do + +The agent has access to tools that let it: + +* Inspect the running process — routes, health, endpoints, consumers, properties, inflight/blocked exchanges +* Read route source code and dump route definitions as YAML or XML +* Show route structure as a processor tree +* Find the slowest processors with top statistics +* Enable, disable, and dump message tracing +* Start, stop, suspend, and resume individual routes +* Search the Camel component catalog and read component documentation +* List and read built-in CLI examples +* Discover and run any CLI command +* Read and write files in the current directory + +Use `--show-tools` to see tool calls and results as they happen: + +[source,bash] +---- +camel ask "show me the route structure" --show-tools +---- + +=== Connecting to a specific process + +When multiple Camel processes are running, specify which one to inspect: + +[source,bash] +---- +camel ask "check health" --name=myApp +camel ask "check health" --name=12345 +---- + +Without `--name`, the CLI auto-detects when exactly one Camel process is running. + +NOTE: The catalog, example, file, and CLI tools work even without a running Camel process. + +== Explain — understand a route + +The `camel explain` command reads route files from disk and uses an LLM to explain +what they do — step by step. + +[source,bash] +---- +camel explain hello.yaml +camel explain my-routes.java --format=markdown +camel explain route1.yaml route2.xml +---- + +Use `--verbose` for detailed technical information, or `--catalog-context` to enrich +the prompt with Camel component and EIP documentation: + +[source,bash] +---- +camel explain hello.yaml --verbose --catalog-context +---- + +TIP: Use `--format=markdown` for structured output with headers, lists, and code blocks. + +== Harden — security analysis + +The `camel harden` command analyzes route files for security concerns and suggests hardening measures. +It covers authentication, encryption, secrets management, input validation, secure configuration, +and logging. + +[source,bash] +---- +camel harden hello.yaml +camel harden my-routes.java --verbose +camel harden *.yaml --format=markdown +---- + +Findings are prioritized by severity (Critical, High, Medium, Low). +Use `--catalog-context` to include security-specific notes for each component detected in your routes: + +[source,bash] +---- +camel harden my-routes.yaml --catalog-context +---- + +NOTE: `camel harden` currently supports Ollama and OpenAI-compatible APIs only (no Anthropic). + +== Choosing an LLM provider + +All commands auto-detect the LLM provider. The detection order is: + +1. `ANTHROPIC_API_KEY` environment variable → Anthropic API (`ask` and `explain` only) +2. `CLOUD_ML_REGION` + `ANTHROPIC_VERTEX_PROJECT_ID` → Vertex AI (`ask` and `explain` only) +3. `OPENAI_API_KEY` or `LLM_API_KEY` → OpenAI-compatible API +4. Ollama running via `camel infra` → local Ollama +5. Ollama at `localhost:11434` → local Ollama + +Override with explicit options: + +[source,bash] +---- +camel ask "check health" --api-type=anthropic --api-key=sk-... +camel ask "check health" --api-type=openai --model=gpt-4 +camel ask "check health" --api-type=ollama --model=llama3.1 +---- + +=== Using a local model with Ollama + +Start Ollama as a dev service and the CLI detects it automatically: + +[source,bash] +---- +camel infra run ollama +camel ask "what routes are running?" +---- + +The default model is `llama3.2`. When using Ollama, the CLI checks what models are available +locally and auto-selects a suitable one if a better model is installed. + +TIP: For best results with the `ask` command's tool-calling capabilities, +use a model that supports function calling well (e.g., `llama3.1`, `qwen3`, `mistral-nemo`). diff --git a/docs/user-manual/modules/ROOT/pages/camel-jbang-getting-started.adoc b/docs/user-manual/modules/ROOT/pages/camel-jbang-getting-started.adoc index 7cb3d3e771c4..b0311bac1df9 100644 --- a/docs/user-manual/modules/ROOT/pages/camel-jbang-getting-started.adoc +++ b/docs/user-manual/modules/ROOT/pages/camel-jbang-getting-started.adoc @@ -193,6 +193,30 @@ To make it permanent: echo 'source <(camel completion)' >> ~/.bashrc ---- +== Interactive shell + +Launch an interactive shell with command history, autocompletion, and alias support: + +[source,bash] +---- +camel shell +---- + +All CLI commands are available inside the shell without the `camel` prefix. +The shell stores history in `~/.camel-jbang-history` and aliases in `~/.camel-jbang-aliases`. + +== Check your environment + +Run the doctor to verify that your environment is set up correctly: + +[source,bash] +---- +camel doctor +---- + +This checks Camel and Java versions, JBang availability, Maven repository connectivity, +container runtime (Docker/Podman), and disk space. + == Explore commands Every command supports `--help`: diff --git a/docs/user-manual/modules/ROOT/pages/camel-jbang-installation.adoc b/docs/user-manual/modules/ROOT/pages/camel-jbang-installation.adoc index c8bef74971f9..742e9f0aff7a 100644 --- a/docs/user-manual/modules/ROOT/pages/camel-jbang-installation.adoc +++ b/docs/user-manual/modules/ROOT/pages/camel-jbang-installation.adoc @@ -59,7 +59,26 @@ jbang app install --force --fresh \ The catalog URL points to a specific release tag, so JBang will not pull a newer version. -=== Option 3: Use the Camel Launcher +=== Option 3: Use the Camel Wrapper + +Similar to the Maven Wrapper, the Camel Wrapper creates version-pinning scripts in your project directory: + +[source,bash] +---- +camel wrapper +---- + +This creates a `.camel/camel-wrapper.properties` file and launcher scripts +so anyone working on the project uses the same Camel CLI version — no manual install needed. + +Pin a specific version: + +[source,bash] +---- +camel wrapper --camel-version=4.18.0 +---- + +=== Option 4: Use the Camel Launcher The xref:camel-jbang-launcher.adoc[Camel CLI Launcher] is a self-contained executable JAR that runs without JBang entirely. diff --git a/docs/user-manual/modules/ROOT/pages/camel-jbang-managing.adoc b/docs/user-manual/modules/ROOT/pages/camel-jbang-managing.adoc index 0ad15e733c2e..fc2e3201ee40 100644 --- a/docs/user-manual/modules/ROOT/pages/camel-jbang-managing.adoc +++ b/docs/user-manual/modules/ROOT/pages/camel-jbang-managing.adoc @@ -30,6 +30,13 @@ Stopping running Camel integration (pid: 62506) NOTE: The name is matched as a prefix — `camel stop d` stops all integrations starting with _d_. To stop exactly one when names overlap (e.g., `dude` and `dude2`), use the PID or append `!`: `camel stop dude!` +Restart an integration (stop + re-launch): + +[source,bash] +---- +camel restart dude +---- + Stop all integrations (omit the name): [source,bash] @@ -150,6 +157,38 @@ camel top route 14242 MyCamel hello timer://hello?period=2000 Started 31m41s 948 0 0 0 0 4 0s ---- +== Visualizing routes + +Render a visual diagram of routes in a running integration: + +[source,bash] +---- +camel cmd route-diagram myApp +---- + +This prints a Unicode route diagram in the terminal. Use `--theme=ascii` for plain text, +or `--output=diagram.png --theme=light` to save as an image. + +You can also render diagrams directly from source files (no running process needed): + +[source,bash] +---- +camel cmd route-diagram my-route.yaml +---- + +Show how routes connect to each other and to external systems with the topology view: + +[source,bash] +---- +camel cmd route-topology myApp +camel cmd route-topology myApp --external +---- + +The `--external` flag includes external systems (Kafka, databases, etc.) as nodes in the graph. +Both commands include live metrics by default — use `--metric=false` to disable. + +TIP: The xref:camel-jbang-tui.adoc[Camel TUI] shows route diagrams and topology interactively. + == Starting and stopping routes Stop all routes in an integration: @@ -406,6 +445,31 @@ camel trace --action=stop Use `--action=clear` to discard already-traced messages. +=== OpenTelemetry spans + +When OpenTelemetry tracing is enabled, view collected spans: + +[source,bash] +---- +camel cmd span myApp +---- + +Filter by trace ID, route, component, or exchange ID: + +[source,bash] +---- +camel cmd span myApp --filter=route1 +---- + +Show a waterfall timeline for a specific trace: + +[source,bash] +---- +camel cmd span myApp --trace=abc123 +---- + +Use `--flat` for a flat list of individual spans instead of grouped traces. + == Health checks View health check status: @@ -575,6 +639,23 @@ camel jolokia 62506 --stop TIP: Run `camel hawtio --help` for options. +== Thread dump + +List threads in a running Camel integration: + +[source,bash] +---- +camel cmd thread-dump myApp +---- + +By default only Camel-related threads are shown. Use `--filter=all` for all JVM threads, +or `--state=BLOCKED` to find blocked threads. Add `--trace` to include stack traces: + +[source,bash] +---- +camel cmd thread-dump myApp --filter=all --state=BLOCKED --trace +---- + == See Also * xref:camel-jbang-kubernetes.adoc[Camel Kubernetes Plugin] — deploy and manage Camel integrations on Kubernetes diff --git a/docs/user-manual/modules/ROOT/pages/camel-jbang-transforming.adoc b/docs/user-manual/modules/ROOT/pages/camel-jbang-transforming.adoc index a2e18d16f06c..fc46c1663b84 100644 --- a/docs/user-manual/modules/ROOT/pages/camel-jbang-transforming.adoc +++ b/docs/user-manual/modules/ROOT/pages/camel-jbang-transforming.adoc @@ -404,6 +404,27 @@ $ camel transform message --body=file:daltons.csv --dataformat=csv --option=capt NOTE: Some data formats require complex options that cannot be set from the command line. +== Evaluating expressions + +Quickly evaluate a Camel expression without writing a route: + +[source,bash] +---- +camel eval expression --language=simple --template='Hello ${body}' --body='World' +camel eval expression --language=jq --template='.name' --body=file:data.json +camel eval expression --language=jsonpath --template='$.store.book[0].title' --body=file:store.json +---- + +This runs the expression in an isolated process. To evaluate against a running integration +(using its Exchange context), specify the process name or PID: + +[source,bash] +---- +camel eval expression myApp --language=simple --template='${header.myHeader}' +---- + +Use `--predicate` to evaluate as a boolean predicate instead of a value expression. + == Transforming route DSL format The `camel transform route` command converts between YAML and XML DSL formats — diff --git a/docs/user-manual/modules/ROOT/pages/camel-jbang.adoc b/docs/user-manual/modules/ROOT/pages/camel-jbang.adoc index 6ba3f17f82c6..6bf7f66f5988 100644 --- a/docs/user-manual/modules/ROOT/pages/camel-jbang.adoc +++ b/docs/user-manual/modules/ROOT/pages/camel-jbang.adoc @@ -94,6 +94,9 @@ TIP: You can also install without JBang using the xref:camel-jbang-launcher.adoc | Sending and receiving messages, JDBC configuration, terminal scripting, IDE editing, validate plugin. +| xref:camel-jbang-ai.adoc[AI Tools] +| Ask questions about running integrations, explain routes, and get security hardening suggestions — powered by local or cloud LLMs. + | xref:camel-jbang-debugging.adoc[Debugging] | Camel route debugging from the CLI, IDE integration (VSCode, IDEA), Java-level debugging.
