You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@camel.apache.org by da...@apache.org on 2026/06/09 19:55:31 UTC
(camel) branch main updated: CAMEL-23722: Restructure Camel CLI documentation (#23892)
This is an automated email from the ASF dual-hosted git repository.
davsclaus pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/camel.git
The following commit(s) were added to refs/heads/main by this push:
new a186239592de CAMEL-23722: Restructure Camel CLI documentation (#23892)
a186239592de is described below
commit a186239592def2ccf46bdbbbd54d8150faab58a8
Author: Claus Ibsen <cl...@gmail.com>
AuthorDate: Tue Jun 9 21:55:24 2026 +0200
CAMEL-23722: Restructure Camel CLI documentation (#23892)
* CAMEL-23722: Restructure Camel CLI documentation into focused sub-pages
Co-Authored-By: Claude <no...@anthropic.com>
Signed-off-by: Claus Ibsen <cl...@gmail.com>
* CAMEL-23722: Reorder CLI docs sections and create focused sub-pages
Reorder sections within each page so the most important content comes
first and related content is grouped together. Create three new focused
sub-pages by extracting content from existing pages:
- Debugging: route debugging, IDE integration, Java debugging
- Data Transformation: message mapping, DSL conversion
- Dev Services: local infrastructure services (aligned with Spring Boot
and Quarkus terminology)
Cross-page section moves: Developer Console and History moved from
Running to Managing, Health Checks moved from DevTools to Managing,
Validate Plugin moved from Configuration to DevTools, Infrastructure
extracted from Projects to Dev Services.
Promote wrongly nested subsections in Managing from === to == level.
Update nav.adoc and main page feature table for the new pages.
Co-Authored-By: Claude Opus 4.6 <no...@anthropic.com>
Signed-off-by: Claus Ibsen <cl...@gmail.com>
* CAMEL-23722: Reorder CLI docs nav by importance
Move Dev Services up after Running Routes since infrastructure setup
is typically one of the first things developers do.
Co-Authored-By: Claude Opus 4.6 <no...@anthropic.com>
Signed-off-by: Claus Ibsen <cl...@gmail.com>
* CAMEL-23722: Rewrite getting started and remove Groovy DSL references
Rewrite getting-started page focused on the fast path: install, create,
run in under 30 lines. Move advanced install options (version-pinned,
offline, container) to new Installation Options sub-page.
Remove Groovy DSL references across all CLI docs since Groovy DSL is
no longer supported. Groovy expression language references are kept.
Move "Running a Maven based project" to Running Routes page.
Co-Authored-By: Claude Opus 4.6 <no...@anthropic.com>
Signed-off-by: Claus Ibsen <cl...@gmail.com>
* CAMEL-23722: Rename Running Routes to Running Camel
Co-Authored-By: Claude Opus 4.6 <no...@anthropic.com>
Signed-off-by: Claus Ibsen <cl...@gmail.com>
* CAMEL-23722: Tighten Installation Options page
Remove docker/podman duplication, improve prose, rename section
headings for clarity.
Co-Authored-By: Claude Opus 4.6 <no...@anthropic.com>
Signed-off-by: Claus Ibsen <cl...@gmail.com>
* CAMEL-23722: Split Running Camel into essentials and Tips page
Move power-user features (clipboard, GitHub routes, stub, inline code,
interactive prompt, HTTP upload, Maven config, Maven project migration)
to new Tips and Recipes sub-page. Running Camel now focuses on what
new users need: dev mode, properties, profiles, platform-http,
dependencies, runtimes, and Kamelets.
Remove deprecated Pipes/bind sections and trim verbose prose.
Co-Authored-By: Claude Opus 4.6 <no...@anthropic.com>
Signed-off-by: Claus Ibsen <cl...@gmail.com>
* CAMEL-23722: Move DI to own page, tighten Dev Services and Development Tools
- Extract Dependency Injection section from Development Tools into new
camel-jbang-dependency-injection.adoc sub-page
- Tighten Dev Services prose and add NOTE about camel infra = Dev Services
- Tighten Development Tools prose (536 -> 422 lines)
- Update nav.adoc and main feature table for new DI page
Co-Authored-By: Claude <no...@anthropic.com>
Signed-off-by: Claus Ibsen <cl...@gmail.com>
* CAMEL-23722: Tighten Debugging page prose
Co-Authored-By: Claude <no...@anthropic.com>
Signed-off-by: Claus Ibsen <cl...@gmail.com>
* CAMEL-23722: Tighten Data Transformation page prose
Co-Authored-By: Claude <no...@anthropic.com>
Signed-off-by: Claus Ibsen <cl...@gmail.com>
* CAMEL-23722: Tighten Managing Integrations page prose (893 -> 576 lines)
Co-Authored-By: Claude <no...@anthropic.com>
Signed-off-by: Claus Ibsen <cl...@gmail.com>
* CAMEL-23722: Tighten Projects and Catalog page prose (808 -> 283 lines)
Co-Authored-By: Claude <no...@anthropic.com>
Signed-off-by: Claus Ibsen <cl...@gmail.com>
* CAMEL-23722: Tighten Configuration page prose (192 -> 111 lines)
Co-Authored-By: Claude <no...@anthropic.com>
Signed-off-by: Claus Ibsen <cl...@gmail.com>
* CAMEL-23722: Tighten Testing Plugin page prose (353 -> 158 lines)
Co-Authored-By: Claude <no...@anthropic.com>
Signed-off-by: Claus Ibsen <cl...@gmail.com>
* CAMEL-23722: Tighten Kubernetes Plugin page prose (1758 -> 749 lines)
Co-Authored-By: Claude <no...@anthropic.com>
Signed-off-by: Claus Ibsen <cl...@gmail.com>
* CAMEL-23722: Tighten Launcher page prose (79 -> 53 lines)
Co-Authored-By: Claude <no...@anthropic.com>
Signed-off-by: Claus Ibsen <cl...@gmail.com>
* CAMEL-23722: Tighten MCP Server page prose (1024 -> 539 lines)
Co-Authored-By: Claude <no...@anthropic.com>
Signed-off-by: Claus Ibsen <cl...@gmail.com>
* CAMEL-23722: Add 10 missing MCP tools to documentation
Co-Authored-By: Claude <no...@anthropic.com>
Signed-off-by: Claus Ibsen <cl...@gmail.com>
* CAMEL-23722: Document Spans/Process tabs in TUI, add --example to Getting Started
Co-Authored-By: Claude <no...@anthropic.com>
Signed-off-by: Claus Ibsen <cl...@gmail.com>
* CAMEL-23722: Add Groovy transformation section, document TUI Spans and Process tabs
Co-Authored-By: Claude <no...@anthropic.com>
Signed-off-by: Claus Ibsen <cl...@gmail.com>
* CAMEL-23722: Move catalog to Getting Started, rename page to Export to Maven
Co-Authored-By: Claude <no...@anthropic.com>
Signed-off-by: Claus Ibsen <cl...@gmail.com>
* CAMEL-23722: Rename Dependency Injection to Java Beans, reorder TOC
- Rename page title and file: camel-jbang-dependency-injection.adoc -> camel-jbang-beans.adoc
- Move Data Transformation up in TOC (after Dev Services)
- Place Java Beans near Configuration as a reference topic
- Update all xrefs in nav, main page, and devtools
Co-Authored-By: Claude Opus 4.6 <no...@anthropic.com>
Signed-off-by: Claus Ibsen <cl...@gmail.com>
* CAMEL-23722: Add TUI cross-references to Getting Started, Managing, and Debugging
Co-Authored-By: Claude Opus 4.6 <no...@anthropic.com>
Signed-off-by: Claus Ibsen <cl...@gmail.com>
* CAMEL-23722: Mention TUI auto-install in tips
Co-Authored-By: Claude Opus 4.6 <no...@anthropic.com>
Signed-off-by: Claus Ibsen <cl...@gmail.com>
* 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 <no...@anthropic.com>
Signed-off-by: Claus Ibsen <cl...@gmail.com>
* CAMEL-23722: Fix asciidoctor warnings and simplify nav
- Fix section level in projects page (==== -> ===)
- Escape {{placeholder}} attributes in tips page
- Simplify nav to show only plugins/extensions (topical pages linked from main page)
Co-Authored-By: Claude Opus 4.6 <no...@anthropic.com>
Signed-off-by: Claus Ibsen <cl...@gmail.com>
* CAMEL-23722: Fix remaining placeholder attribute warning in tips page
Use passthrough macro to prevent AsciiDoc from resolving {{placeholder}}
as an attribute reference.
Co-Authored-By: Claude Opus 4.6 <no...@anthropic.com>
Signed-off-by: Claus Ibsen <cl...@gmail.com>
---------
Signed-off-by: Claus Ibsen <cl...@gmail.com>
Co-authored-by: Claude <no...@anthropic.com>
---
.../modules/ROOT/pages/camel-catalog.adoc | 2 +-
.../modules/ROOT/pages/camel-jbang-ai.adoc | 146 +
.../modules/ROOT/pages/camel-jbang-beans.adoc | 163 +
.../ROOT/pages/camel-jbang-configuration.adoc | 111 +
.../modules/ROOT/pages/camel-jbang-debugging.adoc | 128 +
.../ROOT/pages/camel-jbang-dev-services.adoc | 115 +
.../modules/ROOT/pages/camel-jbang-devtools.adoc | 422 ++
.../ROOT/pages/camel-jbang-getting-started.adoc | 252 +
.../ROOT/pages/camel-jbang-installation.adoc | 116 +
.../modules/ROOT/pages/camel-jbang-kubernetes.adoc | 1213 +----
.../modules/ROOT/pages/camel-jbang-launcher.adoc | 43 +-
.../modules/ROOT/pages/camel-jbang-managing.adoc | 662 +++
.../modules/ROOT/pages/camel-jbang-mcp.adoc | 685 +--
.../modules/ROOT/pages/camel-jbang-projects.adoc | 234 +
.../modules/ROOT/pages/camel-jbang-running.adoc | 271 ++
.../modules/ROOT/pages/camel-jbang-test.adoc | 266 +-
.../modules/ROOT/pages/camel-jbang-tips.adoc | 222 +
.../ROOT/pages/camel-jbang-transforming.adoc | 497 ++
.../modules/ROOT/pages/camel-jbang-tui.adoc | 35 +-
.../modules/ROOT/pages/camel-jbang.adoc | 4813 +-------------------
.../ROOT/pages/camel-upgrade-recipes-tool.adoc | 2 +-
.../modules/ROOT/pages/getting-started.adoc | 2 +-
22 files changed, 3750 insertions(+), 6650 deletions(-)
diff --git a/docs/user-manual/modules/ROOT/pages/camel-catalog.adoc b/docs/user-manual/modules/ROOT/pages/camel-catalog.adoc
index 8abb4c834264..b0bdedb75dae 100644
--- a/docs/user-manual/modules/ROOT/pages/camel-catalog.adoc
+++ b/docs/user-manual/modules/ROOT/pages/camel-catalog.adoc
@@ -34,7 +34,7 @@ The following tools uses the catalog in their editor:
The xref:camel-report-maven-plugin.adoc[Camel Maven validation] plugin uses the catalog during validation of all the
Camel endpoints found while scanning the source code.
-The xref:camel-jbang.adoc[Camel CLI] CLI uses the catalog in some of the commands and actions.
+The xref:camel-jbang.adoc[Camel CLI] uses the catalog in some of the commands and actions.
=== Layout of camel-catalog
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-beans.adoc b/docs/user-manual/modules/ROOT/pages/camel-jbang-beans.adoc
new file mode 100644
index 000000000000..a9a622ebad08
--- /dev/null
+++ b/docs/user-manual/modules/ROOT/pages/camel-jbang-beans.adoc
@@ -0,0 +1,163 @@
+= Camel CLI - Java Beans
+
+When running Camel integrations with the CLI, the runtime is `camel-main` based — there is no
+Spring Boot or Quarkus container. However, annotation-based dependency injection is supported
+across all three styles: Camel-native, Spring Boot, and Quarkus annotations.
+
+NOTE: There is basic support for including regular Java source files together with Camel routes.
+The CLI compiles them at runtime, so you can include utility classes, POJOs, processors, and
+other classes your application needs.
+
+== Using Camel dependency injection
+
+Camel-native annotations for standalone use:
+
+- `@BindToRegistry` on a class — creates an instance and registers it in the xref:registry.adoc[Registry]
+- `@Configuration` on a class — runs during Camel startup for custom setup code
+- `@BeanInject` on a field — injects a bean from the Registry
+- `@PropertyInject` on a field — injects a xref:using-propertyplaceholder.adoc[property placeholder] value
+- `@BindToRegistry` on a method — creates a bean by invoking the method
+- `@Converter` on a class — auto-registers xref:type-converter.adoc[type converters]
+
+IMPORTANT: `@BeanInject` can reference beans annotated with `@BindToRegistry`, but the dependency
+must be registered before the dependent bean.
+
+== Using Spring Boot dependency injection
+
+These Spring annotations work in Camel standalone (no Spring container required):
+
+- `@Component` or `@Service` on a class — registers an instance in the Registry
+- `@Autowired` on a field — injects a bean (`@Qualifier` specifies the bean id)
+- `@Value` on a field — injects a property placeholder
+- `@Bean` on a method — creates a bean by invoking the method
+
+== Using Quarkus dependency injection
+
+These Jakarta/MicroProfile annotations work in Camel standalone (no Quarkus container required):
+
+- `@ApplicationScoped` or `@Singleton` on a class — registers an instance (`@Named` specifies the bean id)
+- `@Inject` on a field — injects a bean (`@Named` specifies the bean id)
+- `@ConfigProperty` on a field — injects a property placeholder
+- `@Produces` on a method — creates a bean (`@Named` specifies the bean id)
+
+== Defining beans in XML DSL
+
+When using xref:components:others:java-xml-io-dsl.adoc[XML DSL], you can declare beans
+that are added to the xref:registry.adoc[Registry]:
+
+[source,xml]
+----
+<camel>
+
+ <bean name="beanFromMap" type="com.acme.MyBean">
+ <properties>
+ <property key="foo" value="bar" />
+ </properties>
+ </bean>
+
+</camel>
+----
+
+Properties can use nested `<property>` elements or dotted notation:
+
+[source,xml]
+----
+<camel>
+
+ <!-- nested properties style -->
+ <bean name="beanFromMap" type="com.acme.MyBean">
+ <properties>
+ <property key="field1" value="f1_p" />
+ <property key="nested">
+ <properties>
+ <property key="field1" value="nf1_p" />
+ </properties>
+ </property>
+ </properties>
+ </bean>
+
+ <!-- dotted properties style -->
+ <bean name="beanFromProps" type="com.acme.MyBean">
+ <properties>
+ <property key="field1" value="f1_p" />
+ <property key="nested.field1" value="nf1_p" />
+ </properties>
+ </bean>
+
+</camel>
+----
+
+== Using Spring Beans XML in Camel XML DSL
+
+You can use Spring Beans XML namespace inside Camel XML DSL. The beans are added to the
+xref:registry.adoc[Registry] — this does not require Spring Framework at runtime.
+
+Supported features:
+
+* Dependency injection
+* Constructor injection
+* Dependency cycles
+* Wiring existing Camel objects (like `CamelContext`)
+
+[source,xml]
+----
+<camel>
+
+ <beans xmlns="http://www.springframework.org/schema/beans">
+ <bean id="messageString" class="java.lang.String">
+ <constructor-arg index="0" value="Hello"/>
+ </bean>
+
+ <bean id="greeter" class="org.apache.camel.main.app.Greeter">
+ <property name="message">
+ <bean class="org.apache.camel.main.app.GreeterMessage">
+ <property name="msg" ref="messageString"/>
+ </bean>
+ </property>
+ </bean>
+ </beans>
+
+ <route id="my-route">
+ <from uri="direct:start"/>
+ <bean ref="greeter"/>
+ <to uri="mock:finish"/>
+ </route>
+
+</camel>
+----
+
+=== Predefined Camel beans
+
+These beans can be referenced without declaring them:
+
+* `CamelContext` — the current `org.apache.camel.CamelContext`
+* `MainConfiguration` — the `org.apache.camel.main.MainConfigurationProperties` instance
+
+For example:
+
+[source,xml]
+----
+<beans xmlns="http://www.springframework.org/schema/beans">
+ <bean id="greeter" class="org.apache.camel.main.app.Greeter">
+ <property name="camelContext" ref="CamelContext"/>
+ </bean>
+</beans>
+----
+
+=== Customizing Camel internals
+
+You can register beans that affect `CamelContext` configuration. For example, to replace the
+default UUID generator:
+
+[source,xml]
+----
+<camel>
+
+ <beans xmlns="http://www.springframework.org/schema/beans">
+ <bean id="customUUIDGenerator" class="org.apache.camel.support.ShortUuidGenerator" />
+ </beans>
+
+</camel>
+----
+
+Camel looks up known SPI types (like `UuidGenerator`) in the Registry and uses them automatically.
diff --git a/docs/user-manual/modules/ROOT/pages/camel-jbang-configuration.adoc b/docs/user-manual/modules/ROOT/pages/camel-jbang-configuration.adoc
new file mode 100644
index 000000000000..430cb5af1493
--- /dev/null
+++ b/docs/user-manual/modules/ROOT/pages/camel-jbang-configuration.adoc
@@ -0,0 +1,111 @@
+= Camel CLI - Configuration
+
+This page covers configuring the Camel CLI — available options, configuration commands, and how to set up your environment.
+
+// jbang options: START
+== Configuration Options
+The camel.jbang supports 48 options, which are listed below.
+
+[width="100%",cols="2,5,^1,2",options="header"]
+|===
+| Name | Description | Default | Type
+| *camel.jbang.camel-version* | The version of Apache Camel to use | | String
+| *camel.jbang.camelSpringBootVersion* | To use a custom Camel version when running or export to Spring Boot | | String
+| *camel.jbang.classpathFiles* | Additional files to add to classpath (Use commas to separate multiple files). | | String
+| *camel.jbang.compileWorkDir* | Work directory for compiler. Can be used to write compiled classes or other resources. | .camel-jbang/compile | String
+| *camel.jbang.console* | Developer console at /q/dev on local HTTP server (port 8080 by default) | false | boolean
+| *camel.jbang.dependencies* | Additional dependencies (Use commas to separate multiple dependencies). | | String
+| *camel.jbang.dependencies.main* | Additional dependencies for Camel Main runtime only | | String
+| *camel.jbang.dependencies.quarkus* | Additional dependencies for Quarkus runtime only | | String
+| *camel.jbang.dependencies.spring-boot* | Additional dependencies for Spring Boot runtime only | | String
+| *camel.jbang.download* | Whether to allow automatic downloading JAR dependencies (over the internet) | true | boolean
+| *camel.jbang.excludes* | Exclude files by name or pattern (Use commas to separate multiple files) | | String
+| *camel.jbang.exportDir* | Directory where the project will be exported | . | String
+| *camel.jbang.fresh* | Whether to force using fresh (i.e. non-cached) resources | false | boolean
+| *camel.jbang.gav* | Maven coordinate (groupId:artifactId:version) | | String
+| *camel.jbang.groovyFiles* | Additional groovy source files to export to src/main/resources/camel-groovy directory (Use commas to separate multiple files) | | String
+| *camel.jbang.health* | Health check at /observe/health on local HTTP server (port 8080 by default) | false | boolean
+| *camel.jbang.ignoreLoadingError* | Whether to ignore route loading and compilation errors (use this with care!) | false | boolean
+| *camel.jbang.javaVersion* | Java version | 21 | String
+| *camel.jbang.jfr* | Enables Java Flight Recorder saving recording to disk on exit | false | boolean
+| *camel.jbang.jfr-profile* | Java Flight Recorder profile to use (such as default or profile) | default | String
+| *camel.jbang.jib-maven-plugin-version* | Version to use for jib-maven-plugin if exporting to camel-main and have Kubernetes enabled (jkube.xxx options) | 3.4.5 | String
+| *camel.jbang.jkube-maven-plugin-version* | Version to use for jkube-maven-plugin if exporting to camel-main and have Kubernetes enabled (jkube.xxx options) | 1.19.0 | String
+| *camel.jbang.jkubeFiles* | Resource YAML fragments for Kubernetes using Eclipse JKube tool (Use commas to separate multiple files). | | String
+| *camel.jbang.kameletsVersion* | Apache Camel Kamelets version. By default the Kamelets are the same version as Camel. | | String
+| *camel.jbang.lazyBean* | Whether to use lazy bean initialization (can help with complex classloading issues) | false | boolean
+| *camel.jbang.localKameletDir* | Local file directory for loading custom Kamelets | | String
+| *camel.jbang.maven-apache-snapshot-enabled* | Whether downloading JARs from ASF Maven Snapshot repository is enabled | true | boolean
+| *camel.jbang.maven-central-enabled* | Whether downloading JARs from Maven Central repository is enabled | true | boolean
+| *camel.jbang.maven-settings* | Optional location of Maven settings.xml file to configure servers, repositories, mirrors, and proxies. If set to false, not even the default /.m2/settings.xml will be used. | | String
+| *camel.jbang.maven-settings-security* | Optional location of Maven settings-security.xml file to decrypt Maven Settings (settings.xml) file | | String
+| *camel.jbang.mavenWrapper* | Include Maven Wrapper files in the exported project | true | boolean
+| *camel.jbang.metrics* | Metrics (Micrometer and Prometheus) at /observe/metrics on local HTTP server (port 8080 by default) when running standalone Camel | false | boolean
+| *camel.jbang.openApi* | File name of open-api spec file (JSON or YAML) to generate routes from the swagger/openapi API spec file. | | String
+| *camel.jbang.packageScanJars* | Whether to automatic package scan JARs for custom Spring or Quarkus beans making them available for Camel CLI | false | boolean
+| *camel.jbang.prompt* | Allow user to type in required parameters in prompt if not present in application | false | boolean
+| *camel.jbang.quarkusArtifactId* | artifactId of Quarkus Platform BOM | | String
+| *camel.jbang.quarkusExtensionRegistryBaseUri* | The base URI of Quarkus Extension Registry | | String
+| *camel.jbang.quarkusGroupId* | groupId of Quarkus Platform BOM | | String
+| *camel.jbang.quarkusVersion* | version of Quarkus Platform BOM | | String
+| *camel.jbang.readmeFiles* | README files included with the integration (Use commas to separate multiple files) | | String
+| *camel.jbang.repos* | Additional Maven repositories for download on-demand (Use commas to separate multiple repositories) | | String
+| *camel.jbang.runtime* | Which runtime to use (camel-main, spring-boot, quarkus) | | String
+| *camel.jbang.scriptFiles* | Additional shell script files to export to src/main/scripts directory | | String
+| *camel.jbang.sourceDir* | Source directory for dynamically loading Camel file(s) to run. When using this, then files cannot be specified at the same time. | | String
+| *camel.jbang.springBootVersion* | Spring Boot version | | String
+| *camel.jbang.stub* | Stubs all the matching endpoint with the given component name or pattern. Multiple names can be separated by comma. (all = stub all endpoints, remote = stub only remote components). | | String
+| *camel.jbang.tlsFiles* | Additional SSL/TLS files to export to src/main/tls directory | | String
+| *camel.jbang.verbose* | Verbose output of startup activity (dependency resolution and downloading | false | boolean
+|===
+// jbang options: END
+
+== Configuration Commands
+
+Store frequently used CLI options so you don't have to specify them each time:
+
+[source,bash]
+----
+camel config set camel-version=3.18.4
+camel run *
+----
+
+=== Configuration locations
+
+Camel CLI uses two configuration files:
+
+- Global: `~/.camel-jbang-user.properties`
+- Local: `./camel-jbang-user.properties` (takes precedence)
+
+Commands target global by default. Use `--global=false` for local configuration.
+
+IMPORTANT: A set version via `camel config set` cannot be combined with `--camel-version` on the command line.
+
+=== Set, unset, list, and get
+
+[source,bash]
+----
+camel config set gav=com.foo:acme:1.0-SNAPSHOT
+camel config set runtime=spring-boot
+camel config unset runtime
+camel config list
+camel config get gav
+----
+
+=== Placeholder substitution
+
+Configuration values can be referenced as placeholders with `#optionName`:
+
+[source,bash]
+----
+camel config set repos=https://maven.repository.my.repo.com/ga
+camel run 'Test.java' --repos=#repos,https://packages.atlassian.com/maven-external
+----
+
+NOTE: Placeholders only work for options that the given command supports. Run `camel <command> --help` to see available options.
+
+== Troubleshooting
+
+JBang stores state and downloaded JARs in `~/.jbang`. Camel CLI downloads dependencies to `~/.m2`.
+If you encounter issues with outdated JARs, try deleting the relevant entries in these directories.
+
diff --git a/docs/user-manual/modules/ROOT/pages/camel-jbang-debugging.adoc b/docs/user-manual/modules/ROOT/pages/camel-jbang-debugging.adoc
new file mode 100644
index 000000000000..38da7147b32b
--- /dev/null
+++ b/docs/user-manual/modules/ROOT/pages/camel-jbang-debugging.adoc
@@ -0,0 +1,128 @@
+= Camel CLI - Debugging
+
+The Camel CLI provides built-in debugging capabilities — from Camel's own route debugger to standard Java debugging. For the full overview, see xref:camel-jbang.adoc[Camel CLI].
+
+TIP: Just type `camel tui` — the plugin auto-installs on first use.
+The xref:camel-jbang-tui.adoc[Camel TUI] includes a Spans tab that shows OpenTelemetry traces
+as a waterfall view — useful for understanding message flow and spotting slow processors.
+
+== Camel route debugging
+
+*Available since Camel 4.2*
+
+Debug Camel routes directly from the terminal:
+
+[source,bash]
+----
+camel debug hello.yaml
+----
+
+The integration runs in the background while the foreground shell acts as a CLI debugger.
+The top shows log output, the middle shows the current breakpoint with source context,
+and the bottom shows the message content:
+
+[source,text]
+----
+2023-11-03 18:15:06.715 INFO 33384 --- [ main] g.apache.camel.main.BaseMainSupport : [Command Line] camel.debug.loggingLevel=DEBUG
+2023-11-03 18:15:06.715 INFO 33384 --- [ main] g.apache.camel.main.BaseMainSupport : [Command Line] camel.debug.singleStepIncludeStartEnd=true
+2023-11-03 18:15:06.787 INFO 33384 --- [ main] mel.cli.connector.LocalCliConnector : Camel CLI enabled (local)
+2023-11-03 18:15:06.833 INFO 33384 --- [ main] el.impl.engine.AbstractCamelContext : Apache Camel 4.7.0 (foo) is starting
+2023-11-03 18:15:06.906 INFO 33384 --- [ main] g.apache.camel.main.BaseMainSupport : Property-placeholders summary
+2023-11-03 18:15:06.906 INFO 33384 --- [ main] g.apache.camel.main.BaseMainSupport : [application.properties] my-name=Donald Duck
+2023-11-03 18:15:06.924 INFO 33384 --- [ main] el.impl.engine.AbstractCamelContext : Routes startup (started:1)
+2023-11-03 18:15:06.924 INFO 33384 --- [ main] el.impl.engine.AbstractCamelContext : Started route-07a6 (timer://yaml)
+2023-11-03 18:15:06.924 INFO 33384 --- [ main] el.impl.engine.AbstractCamelContext : Apache Camel 4.7.0 (foo) started in 91ms (build:0ms init:0ms start:91ms)
+2023-11-03 18:15:11.951 INFO 33384 --- [ - timer://yaml] foo.camel.yaml:10 : Before:
+
+Source: foo.camel.yaml:13 History
+-------------------------------------------------------------------------------- ------------------------------------------------------------------------------------------
+ 10: - log: route-07a6/from-c041 (0ms) 4: uri: timer
+ 11: message: 'Before: ${body}' route-07a6/log1 (1ms) 10: - log:
+ 12: id: log1
+ 13: ---> - setProperty:
+ 14: name: myProp
+ 15: expression:
+ 16: constant:
+ 17: expression: '123'
+ 18: id: constant-4004
+
+
+2023-11-03 18:15:11.951 33384 --- [ thread #4 - timer://yaml] route-07a6/setProperty-321c : 3 - Breakpoint (4ms)
+ Exchange (DefaultExchange) InOnly D48642E54410AF9-0000000000000000
+ Message (DefaultMessage)
+ Body (null)
+
+
+ Breakpoint suspended. Press ENTER to continue.
+----
+
+=== Configuring breakpoints
+
+By default, breakpoints are added to every route. Use `--breakpoint` to target specific nodes.
+The option supports multiple match styles (comma-separated):
+
+- Exact or pattern match by node id (wildcard and regex)
+- EIP kind (`setHeader`, `setBody`, `choice`, `split`, etc.)
+- Source file and/or line number
+
+Examples:
+
+[source,bash]
+----
+camel debug hello.yaml --breakpoint=setHeader
+camel debug hello.yaml --breakpoint=18
+camel debug hello.yaml --breakpoint=18,34
+----
+
+=== Spring Boot route debugging
+
+*Available since Camel 4.14*
+
+Debug an existing Spring Boot Maven project by pointing at its `pom.xml`:
+
+[source,bash]
+----
+camel debug pom.xml
+----
+
+Camel CLI detects `camel-spring-boot-bom`, builds a fat JAR, and launches it in the background
+with debugging enabled — the same experience as debugging plain Camel files.
+
+== IDE route debugging
+
+The Camel route debugger is available by default via JMX at
+`service:jmx:rmi:///jndi/rmi://localhost:1099/jmxrmi/camel`.
+
+Supported IDE plugins:
+https://plugins.jetbrains.com/plugin/9371-apache-camel[IntelliJ],
+https://marketplace.visualstudio.com/items?itemName=redhat.vscode-debug-adapter-apache-camel[VS Code],
+https://marketplace.eclipse.org/content/textual-debugging-apache-camel[Eclipse Desktop].
+
+TIP: When exporting to a Maven project, use the `camel.debug` Maven profile to include
+the `camel-debug` JAR for IDE-based route debugging.
+
+== Java debugging
+
+Use `--jvm-debug` to open a standard Java debug socket (default port 4004):
+
+[source,bash]
+----
+camel run hello.yaml --jvm-debug
+Listening for transport dt_socket at address: 4004
+----
+
+Attach from
+https://www.jetbrains.com/help/idea/attaching-to-local-process.html#create-rc[IntelliJ],
+https://code.visualstudio.com/docs/java/java-debugging#_attach[VS Code], or
+https://www.vogella.com/tutorials/EclipseDebugging/article.html#remote-debugging[Eclipse].
+Port configuration is described in the https://www.jbang.dev/documentation/guide/latest/debugging.html[JBang Debugging] guide.
+
+=== JBang-level debugging
+
+Use JBang's `--debug` flag to debug any CLI command (not just `run`):
+
+[source,bash]
+----
+jbang --debug camel@apache/camel run hello.yaml
+Listening for transport dt_socket at address: 4004
+----
diff --git a/docs/user-manual/modules/ROOT/pages/camel-jbang-dev-services.adoc b/docs/user-manual/modules/ROOT/pages/camel-jbang-dev-services.adoc
new file mode 100644
index 000000000000..75c7cde7266d
--- /dev/null
+++ b/docs/user-manual/modules/ROOT/pages/camel-jbang-dev-services.adoc
@@ -0,0 +1,115 @@
+= Camel CLI - Dev Services
+
+The Camel CLI can start and manage local infrastructure services (databases, message brokers, etc.)
+for development and testing — similar to Spring Boot Dev Services and Quarkus Dev Services.
+Services are powered by Apache Camel test-infra and run in containers (Docker or Podman).
+
+NOTE: The CLI commands use `camel infra` (short for infrastructure). In the documentation we call
+this feature _Dev Services_ to align with Spring Boot and Quarkus terminology — they mean the same thing.
+
+== Listing available services
+
+[source,bash]
+----
+camel infra list
+----
+
+[source]
+----
+ALIAS IMPLEMENTATION
+ ignite
+ azure storage-queue
+ openldap
+ event-bridge
+ xmpp
+ kinesis
+ redis
+ ...
+----
+
+== Running a service
+
+[source,bash]
+----
+camel infra run $SERVICE
+----
+
+Some services offer multiple implementations — pass the implementation name as a second argument:
+
+[source,bash]
+----
+camel infra run kafka redpanda
+----
+
+Once running, the service prints its connection details as JSON:
+
+[source,bash]
+----
+$ camel infra run ftp
+
+Starting service ftp
+{
+ "getPort" : 52472,
+ "getFtpRootDir" : "file://path/to/current/directory/target/ftp/..."
+}
+----
+
+[source,bash]
+----
+$ camel infra run kafka redpanda
+
+Starting service kafka with implementation redpanda
+{
+ "getBootstrapServers" : "localhost:32771"
+}
+----
+
+== Stopping a service
+
+[source,bash]
+----
+camel infra stop arangodb
+----
+
+== Listing running services
+
+[source,bash]
+----
+$ camel infra ps
+ ALIAS IMPLEMENTATION DESCRIPTION
+ arangodb ArangoDB is a multi-model database for high-performance applications.
+----
+
+== Getting service details
+
+Retrieve connection details for a running service:
+
+[source,bash]
+----
+$ camel infra get openldap
+{
+ "getPort" : 32774,
+ "getSslPort" : 32775,
+ "getHost" : "localhost"
+}
+----
+
+== Viewing service logs
+
+Tail logs from all running services:
+
+[source,bash]
+----
+camel infra log
+----
+
+Or from a specific service:
+
+[source,bash]
+----
+camel infra log openldap
+----
+
+== See Also
+
+The xref:camel-jbang-devtools.adoc#_sending_messages_to_infrastructure_services[Sending messages to infrastructure services] feature in the Development Tools page can send messages directly to services started with `camel infra run`.
diff --git a/docs/user-manual/modules/ROOT/pages/camel-jbang-devtools.adoc b/docs/user-manual/modules/ROOT/pages/camel-jbang-devtools.adoc
new file mode 100644
index 000000000000..fe888368569b
--- /dev/null
+++ b/docs/user-manual/modules/ROOT/pages/camel-jbang-devtools.adoc
@@ -0,0 +1,422 @@
+= Camel CLI - Development Tools
+
+The Camel CLI includes a suite of development tools for sending and receiving messages, managing dependencies, scripting, and configuring beans and data sources.
+
+For debugging, see xref:camel-jbang-debugging.adoc[Debugging]. For data transformation, see xref:camel-jbang-transforming.adoc[Data Transformation].
+
+== Sending messages via Camel
+
+*Available since Camel 4*
+
+The `camel cmd send` command sends a message through a running Camel integration,
+reusing its existing endpoint configuration — a quick way to test routes without
+setting up external tooling for each protocol.
+
+For example, given a route that consumes from an MQTT broker:
+
+[source,yaml]
+----
+- route:
+ from:
+ uri: kamelet:mqtt5-source
+ parameters:
+ topic: temperature
+ brokerUrl: tcp://mybroker:1883
+ steps:
+ - transform:
+ expression:
+ jq:
+ expression: .value
+ - log:
+ message: The temperature is ${body}
+----
+
+Send a message to the running integration named `mqtt` (the payload is loaded from a file):
+
+[source,bash]
+----
+$ camel cmd send mqtt --body=file:payload.json mqtt
+----
+
+The last argument (`mqtt`) is the integration name — you can also use its PID.
+With a single route, the command automatically picks the `from` endpoint and reuses its configuration.
+For multiple routes, filter by route id or component with `--endpoint`:
+
+By route id:
+
+[source,bash]
+----
+$ camel cmd send mqtt --body=file:payload.json --endpoint=route1
+----
+
+By component:
+
+[source,bash]
+----
+$ camel cmd send mqtt --body=file:payload.json --endpoint=mqtt
+----
+
+TIP: Run `camel cmd send --help` for all options. Full example on https://github.com/apache/camel-jbang-examples/tree/main/mqtt[GitHub].
+
+=== Sending without a running integration
+
+*Available since Camel 4.12*
+
+Omit the integration name to start a temporary Camel instance and send directly.
+All configuration must be provided on the command line:
+
+[source,bash]
+----
+$ camel cmd send --body=file:payload.json --uri='paho-mqtt5:temperature?brokerUrl=tcp://mybroker:1883'
+----
+
+For complex components (Kafka, AWS, etc.), a Kamelet is often simpler:
+
+[source,bash]
+----
+$ camel cmd send --body=file:payload.json --uri='kamelet:mqtt-sink?brokerUrl=tcp://mybroker:1883&topic=temperature'
+----
+
+=== Sending to infrastructure services
+
+*Available since Camel 4.18*
+
+Use `--infra` to send to a service started with `camel infra run`.
+Connection details are read automatically from the service's JSON file in `~/.camel/`:
+
+[source,bash]
+----
+$ camel infra run nats
+$ camel cmd send --body=file:payload.json --infra=nats
+----
+
+TIP: See xref:camel-jbang-dev-services.adoc[Dev Services] for more on infrastructure services.
+
+==== Custom endpoint
+
+Without `--endpoint`, a default is created from the service type (e.g., `kafka:default`).
+Combine `--infra` with `--endpoint` to customize the destination:
+
+[source,bash]
+----
+$ camel cmd send --endpoint='kafka:myTopic' --body=file:payload.json --infra=kafka
+$ camel cmd send --endpoint='nats:mySubject' --body=file:payload.json --infra=nats
+----
+
+NOTE: Existing query parameters in the endpoint are not overridden by the service connection details.
+
+==== Automatic credential handling
+
+For services with authentication (artemis, ftp, sftp), credentials are appended automatically:
+
+[source,bash]
+----
+$ camel infra run artemis
+$ camel cmd send --endpoint='jms:myQueue' --body='Hello' --infra=artemis
+----
+
+The endpoint automatically includes `username` and `password=RAW(...)` parameters.
+
+==== Multiple service instances
+
+If multiple instances of the same service are running, the command reports an error.
+Stop the unwanted instance or specify its PID.
+
+=== Polling messages
+
+*Available since Camel 4.8*
+
+Use `--poll` to consume a message from a Kafka topic, JMS queue, FTP server, etc.
+(uses Camel consumer instead of producer — no body or headers are sent):
+
+[source,bash]
+----
+$ camel cmd send --poll --endpoint='activemq:cheese'
+----
+
+== Receiving messages via Camel
+
+*Available since Camel 4.9*
+
+The `camel cmd receive` command consumes messages from a remote endpoint and dumps them
+in the terminal — a quick way to verify what an external system has received.
+
+Receive messages from a specific endpoint:
+
+[source,bash]
+----
+$ camel cmd receive --endpoint='activemq:cheese'
+----
+
+You can also auto-discover endpoints from a running integration. Given this route:
+
+[source,java]
+----
+from("ftp:myserver:1234/foo")
+ .to("log:order")
+ .to("activemq:orders");
+----
+
+Start receiving from the first remote producer endpoint automatically:
+
+[source,bash]
+----
+$ camel cmd receive --action=start
+----
+
+Camel discovers the first remote producer with consumer support — in this case `activemq:orders`.
+
+Check status:
+
+[source,bash]
+----
+$ camel cmd receive
+ PID NAME AGE STATUS TOTAL SINCE ENDPOINT
+ 4364 foo 1m33s Enabled 18 2s activemq://orders
+----
+
+Dump received messages (streams continuously — press Ctrl+C to stop):
+
+[source,bash]
+----
+$ camel cmd receive --action=dump
+----
+
+Use `--follow=false` to dump once without tailing. Stop receiving with `--action=stop`.
+
+TIP: Run `camel cmd receive --help` for all options.
+
+== Scripting from terminal using pipes
+
+Camel route files can run as terminal scripts with pipes and filters.
+
+NOTE: Each execution starts a JVM, so this is best suited for tasks that benefit
+from Camel's connectors — sending or receiving data from external systems.
+
+Add the following shebang line at the top of the file:
+
+[source,text]
+----
+///usr/bin/env jbang --quiet camel@apache/camel script "$0" "$@" ; exit $?
+
+import org.apache.camel.builder.RouteBuilder;
+
+//Will upper-case the input
+public class UpperCase extends RouteBuilder {
+
+ @Override
+ public void configure() throws Exception {
+ from("stream:in")
+ .setBody()
+ .simple("${body.toUpperCase()}")
+ .to("stream:out");
+ }
+}
+----
+
+Make it executable and use it with pipes:
+
+[source,bash]
+----
+chmod +x UpperCase.java
+echo "Hello\nWorld" | ./UpperCase.java
+----
+
+Output:
+
+[source,text]
+----
+HELLO
+WORLD
+----
+
+Enable logging with `--logging=true` (writes to `.camel-jbang/camel-pipe.log`).
+
+=== Using stream:in with line vs. raw mode
+
+The xref:components::stream-component.adoc[Stream component] reads from _System in_ in two modes:
+
+- *line mode* (default): reads single lines. Body is a `String`.
+- *raw mode*: reads the entire stream until EOF. Body is a `byte[]`.
+
+Use `stream:in?readLine=false` for raw mode.
+
+== Editing code in an IDE
+
+Use `jbang edit` to set up a project with resolved dependencies for IDEA, VSCode, or Eclipse.
+Declare dependencies with https://www.jbang.dev/documentation/guide/latest/dependencies.html[JBang `//DEPS` comments] in Java source files:
+
+TIP: In YAML DSL, use `\#//DEPS` (YAML comment prefix).
+
+Example `foo.java`:
+
+[source,java]
+----
+//DEPS org.apache.camel:camel-bom:4.3.0@pom
+//DEPS org.apache.camel:camel-endpointdsl
+//DEPS org.apache.camel:camel-netty-http
+//DEPS org.apache.camel:camel-stream
+
+// add more dependencies here
+
+import org.apache.camel.builder.endpoint.EndpointRouteBuilder;
+import org.apache.camel.component.netty.http.NettyHttpMessage;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+public class foo extends EndpointRouteBuilder {
+
+ private static final Logger LOG = LoggerFactory.getLogger(foo.class);
+
+ @Override
+ public void configure() {
+ from(timer("trigger").period(5000).repeatCount(3))
+ .to(nettyHttp("https://random-data-api.com/api/v2/banks").keepAlive(true))
+ .process(e -> {
+ // use classes from camel-netty-http dependency in the source code
+ // and have jbang able to generate project with the dependencies ready
+ // to use in your IDE of choice
+ NettyHttpMessage msg = e.getMessage(NettyHttpMessage.class);
+ LOG.info("Netty HTTP response:\n\n\n{}\n\n\n", msg.getHttpResponse());
+ })
+ .log("Found bank:")
+ .to(stream("out"));
+ }
+}
+----
+
+The first `//DEPS` (`@pom`) sets the Camel BOM version; the rest declare individual components.
+
+Open in your IDE:
+
+[source,bash]
+----
+$ jbang edit -b foo.java
+----
+
+TIP: Use `camel dependency update foo.java` to keep `//DEPS` in sync with the components you actually use.
+
+== Updating dependencies
+
+Automatically insert or update JBang `//DEPS` lines in a Java source file:
+
+[source,bash]
+----
+$ camel dependency update foo.java
+----
+
+TIP: Use `--clean` to regenerate the dependency list from scratch.
+
+=== Maven projects
+
+The same command works on Maven projects — it scans routes for new Camel components
+and adds the corresponding dependencies to `pom.xml`:
+
+[source,bash]
+----
+$ camel dependency update pom.xml
+----
+
+NOTE: Only adding dependencies is supported (removal is manual).
+Only production code in `src/main` is scanned.
+
+== Dependency Injection
+
+The Camel CLI supports annotation-based dependency injection using Camel-native, Spring Boot,
+or Quarkus annotations — even though the runtime is standalone `camel-main` (no Spring or Quarkus container).
+
+See xref:camel-jbang-beans.adoc[Java Beans] for the full reference
+including XML DSL bean definitions and Spring Beans XML support.
+
+== Configuring JDBC DataSources
+
+Two approaches for JDBC connection pools:
+
+- *YAML/XML/Java DSL bean* — add the driver JAR and declare the data source as a bean
+- *Spring Boot style* (Camel 4.6+) — configure via `spring.datasource.*` in `application.properties` (uses Hikari)
+
+=== YAML DSL bean
+
+Declare a `DataSource` bean (e.g., for PostgreSQL):
+
+[source,yaml]
+----
+- beans:
+ - name: PostgresqlDataSource
+ properties:
+ databaseName: "postgres"
+ password: "postgres"
+ portNumber: "5432"
+ serverName: localhost
+ user: postgres
+ type: org.postgresql.ds.PGSimpleDataSource
+----
+
+Add the JDBC driver JAR: `--dep=org.postgresql:postgresql:42.7.3`
+
+=== Spring Boot style data source
+
+NOTE: The `spring.datasource.*` configuration is for prototyping and Spring Boot exports only.
+It is not supported when exporting to Camel Main or Quarkus.
+
+Configure in `application.properties`:
+
+[source,properties]
+----
+spring.datasource.url= jdbc:sqlserver://db.example.net:1433;databaseName=test_db
+spring.datasource.username=user
+spring.datasource.password=password
+spring.datasource.driverClassName=com.microsoft.sqlserver.jdbc.SQLServerDriver
+----
+
+The `DataSource` is registered as `springDataSource`. To use a custom name:
+
+[source,properties]
+----
+spring.datasource.name=myDataSourceNameHere
+----
+
+TIP: Some JDBC drivers are auto-detected. If not, add the JAR with `--dep`.
+
+Configure the Hikari connection pool:
+
+[source,properties]
+----
+spring.datasource.hikari.connection-timeout=30000
+spring.datasource.hikari.maximum-pool-size=10
+spring.datasource.hikari.minimum-idle=5
+spring.datasource.hikari.idle-timeout=600000
+spring.datasource.hikari.max-lifetime=1800000
+spring.datasource.hikari.pool-name=collection-pool
+----
+
+Enable Hikari debug logging to see the pool configuration:
+
+[source,properties]
+----
+logging.level.com.zaxxer.hikari = DEBUG
+----
+
+== Validate Plugin
+
+*Available since Camel 4.18*
+
+The validate plugin checks whether Camel source files (YAML, XML) are valid.
+
+[source,bash]
+----
+$ camel plugin add validate
+$ camel validate yaml cheese.yaml bad.yaml
+Validation error detected (errors:1)
+
+ File: bad.yaml
+ /0/from: required property 'steps' not found
+----
+
+When all files pass:
+
+[source,bash]
+----
+$ camel validate yaml cheese.yaml bad.yaml
+Validation success (files:2)
+----
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
new file mode 100644
index 000000000000..b0311bac1df9
--- /dev/null
+++ b/docs/user-manual/modules/ROOT/pages/camel-jbang-getting-started.adoc
@@ -0,0 +1,252 @@
+= Camel CLI - Getting Started
+
+Three commands. That is all it takes to go from zero to a running integration.
+
+== Install
+
+The Camel CLI runs on https://www.jbang.dev/[JBang].
+Install JBang first (see https://www.jbang.dev/download/[download instructions]),
+then install the Camel CLI:
+
+[source,bash]
+----
+jbang app install camel@apache/camel
+----
+
+Verify that it works:
+
+[source,bash]
+----
+camel version
+----
+
+[source]
+----
+Camel CLI version: 4.21.0
+----
+
+That is it. No Maven project, no POM file, no IDE required.
+
+NOTE: The CLI requires internet access to download dependencies on first use.
+If you are behind a proxy, see https://www.jbang.dev/documentation/jbang/latest/configuration.html#proxy-configuration[JBang proxy configuration].
+
+TIP: For version-pinned installs, offline-safe setups, container images, or installing without JBang,
+see xref:camel-jbang-installation.adoc[Installation Options].
+
+== Create your first route
+
+Use `camel init` to scaffold a new route. The file extension determines the DSL.
+
+=== YAML
+
+[source,bash]
+----
+camel init hello.yaml
+camel run hello.yaml
+----
+
+You should see Camel start up and begin logging:
+
+[source]
+----
+... Started hello (timer://yaml)
+... Hello Camel from route1
+... Hello Camel from route1
+----
+
+Press `Ctrl+C` to stop.
+
+=== Java
+
+[source,bash]
+----
+camel init Hello.java
+camel run Hello.java
+----
+
+Same workflow, same result — just a different DSL.
+XML works the same way (`camel init hello.xml`).
+
+== Dev mode — edit and reload instantly
+
+Run any route in dev mode to get live reload:
+
+[source,bash]
+----
+camel run hello.yaml --dev
+----
+
+Now edit the file in your editor and save.
+Camel detects the change and reloads the route automatically — no restart needed.
+This works for all DSLs (YAML, Java, XML).
+
+TIP: Dev mode is the fastest way to prototype integrations.
+Keep it running while you iterate on your routes.
+
+TIP: Want a visual overview of your running routes, message flow, and health status — right in the terminal?
+Just type `camel tui` — the plugin auto-installs on first use, no setup needed.
+See xref:camel-jbang-tui.adoc[Camel TUI] for details.
+
+== Try a built-in example
+
+Don't have a route yet? The CLI ships with a catalog of ready-to-run examples:
+
+[source,bash]
+----
+camel run --example
+----
+
+This lists all available examples grouped by difficulty (beginner, intermediate, advanced),
+with icons showing whether they are bundled (work offline), require Docker, or include Citrus tests.
+
+Run one directly:
+
+[source,bash]
+----
+camel run --example=timer-log
+camel run --example=rest-api --dev
+----
+
+TIP: Combine with `--dev` for live reload while exploring the example.
+
+=== Running multiple files
+
+You can run several files together, even mixing DSLs:
+
+[source,bash]
+----
+camel run one.yaml Hello.java
+----
+
+Or use wildcards to run everything in a directory:
+
+[source,bash]
+----
+camel run *.yaml
+camel run *
+----
+
+TIP: The CLI automatically picks up `application.properties` files in the same directory.
+
+== Browse the component catalog
+
+Discover what Camel offers — components, data formats, languages, and Kamelets:
+
+[source,bash]
+----
+camel catalog component
+camel catalog kamelet
+----
+
+TIP: Run `camel catalog --help` to see all sub-commands.
+
+=== Component documentation
+
+Show quick reference documentation (description + all configuration options):
+
+[source,bash]
+----
+camel doc kafka
+camel doc jackson
+camel doc aws-kinesis-sink
+----
+
+NOTE: This shows catalog-level documentation with option tables, not the full website documentation.
+
+If a component and data format share the same name, prefix with `dataformat:` (e.g., `camel doc dataformat:thrift`).
+
+Open the online documentation in a browser with `--open-url`, or get just the URL with `--url`:
+
+[source,bash]
+----
+camel doc kafka --open-url
+----
+
+Filter options by name, description, or group (producer, security, advanced, etc.):
+
+[source,bash]
+----
+camel doc kafka --filter=security
+camel doc kafka --filter=timeout
+----
+
+=== Open API
+
+Camel CLI supports contract-first REST development — each OpenAPI operation is bridged to
+a Camel route via `direct:<operationId>`.
+
+See the https://github.com/apache/camel-kamelets-examples/tree/main/jbang/open-api[open-api example] for details.
+
+== Enable shell completion
+
+Tab completion makes discovering commands much easier:
+
+[source,bash]
+----
+source <(camel completion)
+----
+
+To make it permanent:
+
+[source,bash]
+----
+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`:
+
+[source,bash]
+----
+camel run --help
+camel init --help
+----
+
+For the full list of commands, see the xref:jbang-commands/camel-jbang-commands.adoc[Command Reference].
+
+== What's next
+
+[cols="1,2"]
+|===
+| Next step | When to use it
+
+| xref:camel-jbang-running.adoc[Running Camel]
+| Dev mode options, profiles, properties, GitHub-hosted routes, Spring Boot and Quarkus runtimes.
+
+| xref:camel-jbang-dev-services.adoc[Dev Services]
+| Spin up databases, message brokers, and other infrastructure for your routes.
+
+| xref:camel-jbang-devtools.adoc[Development Tools]
+| Send and receive test messages, configure JDBC, set up dependency injection.
+
+| xref:camel-jbang-debugging.adoc[Debugging]
+| Step through routes with the built-in debugger or connect your IDE.
+
+| xref:camel-jbang-projects.adoc[Export to Maven]
+| Export to Spring Boot, Quarkus, or Camel Main for production. Manage dependencies and versions.
+|===
diff --git a/docs/user-manual/modules/ROOT/pages/camel-jbang-installation.adoc b/docs/user-manual/modules/ROOT/pages/camel-jbang-installation.adoc
new file mode 100644
index 000000000000..742e9f0aff7a
--- /dev/null
+++ b/docs/user-manual/modules/ROOT/pages/camel-jbang-installation.adoc
@@ -0,0 +1,116 @@
+= Camel CLI - Installation Options
+
+Alternative ways to install the Camel CLI — pinning a specific version,
+offline-safe setups, and running from a container image.
+
+For the standard installation, see xref:camel-jbang-getting-started.adoc[Getting Started].
+
+== Installing a specific version
+
+By default, `jbang app install` installs the latest Camel release.
+To pin a specific version (for example 4.14.1):
+
+[source,bash]
+----
+jbang app install --force --fresh -Dcamel.jbang.version=4.14.1 -Dcamel-kamelets.version=4.14.1 camel@apache/camel
+----
+
+The `--force` and `--fresh` flags ensure JBang bypasses its download cache.
+
+IMPORTANT: From Camel 4.17, Kamelets are optional and downloaded on demand.
+Set the version with `--kamelets-version` on `camel run`, or pre-configure it:
+`camel config set kamelets-version=4.17.0`.
+
+== Preventing automatic upgrades
+
+JBang occasionally checks upstream sources and may auto-update the installed CLI.
+If you need a stable, repeatable installation, use one of the options below.
+
+=== Option 1: Pin from a local `CamelJBang.java`
+
+This is the most deterministic approach — best for fully offline environments.
+
+1. Download https://github.com/apache/camel/blob/main/dsl/camel-jbang/camel-jbang-main/dist/CamelJBang.java[`CamelJBang.java`] to your local machine.
+2. Edit the file and set the Camel version you want.
+3. Install from the local file:
++
+[source,bash]
+----
+jbang app install CamelJBang.java
+----
+
+The file can be deleted after installation.
+
+=== Option 2: Pin from a version-tagged catalog
+
+Simpler than Option 1, but still prevents surprise upgrades:
+
+[source,bash]
+----
+CAMEL_VERSION="4.18.0"
+CAMEL_TAG="camel-${CAMEL_VERSION}"
+CAMEL_JBANG_CATALOG_URL="https://raw.githubusercontent.com/apache/camel/${CAMEL_TAG}/jbang-catalog.json"
+
+jbang app install --force --fresh \
+ -Dcamel.jbang.version="${CAMEL_VERSION}" \
+ -Dcamel-kamelets.version="${CAMEL_VERSION}" \
+ camel@"${CAMEL_JBANG_CATALOG_URL}"
+----
+
+The catalog URL points to a specific release tag, so JBang will not pull a newer version.
+
+=== 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.
+
+== Container image
+
+The Camel CLI is also available as a container image on https://hub.docker.com/r/apache/camel-jbang/[Docker Hub].
+
+NOTE: All examples below use `docker`. Replace with `podman` if you prefer — the commands are identical.
+
+Pull the image:
+
+[source,bash]
+----
+docker pull apache/camel-jbang:4.21.0
+----
+
+Verify it works:
+
+[source,bash]
+----
+docker run apache/camel-jbang:4.21.0 version
+----
+
+[source]
+----
+Camel CLI version: 4.21.0
+----
+
+Run a route by mounting your local directory:
+
+[source,bash]
+----
+docker run -v .:/integrations apache/camel-jbang:4.21.0 run /integrations/example.yaml
+----
diff --git a/docs/user-manual/modules/ROOT/pages/camel-jbang-kubernetes.adoc b/docs/user-manual/modules/ROOT/pages/camel-jbang-kubernetes.adoc
index f312635a520e..d5ba00f683b3 100644
--- a/docs/user-manual/modules/ROOT/pages/camel-jbang-kubernetes.adoc
+++ b/docs/user-manual/modules/ROOT/pages/camel-jbang-kubernetes.adoc
@@ -1,103 +1,38 @@
= Camel Kubernetes plugin
-This plugin helps you to get started with running Camel applications on Kubernetes.
-Please make sure to meet these prerequisites for running Camel integrations on Kubernetes:
+Export, build, push, and deploy Camel integrations to Kubernetes — develop locally with Camel CLI, then promote to any cluster.
-* Install a Kubernetes command line tooling (https://kubernetes.io/docs/tasks/tools/#kubectl[kubectl])
-* Connect to a running Kubernetes cluster where you want to run the Camel integration
+Prerequisites: https://kubernetes.io/docs/tasks/tools/#kubectl[kubectl] installed, connected to a Kubernetes cluster (remote, https://kind.sigs.k8s.io/docs/user/quick-start/[Kind], or https://minikube.sigs.k8s.io/docs/start/[Minikube]).
-You can connect to a remote Kubernetes cluster or set up a local cluster.
-To set up a local Kubernetes cluster, you have a variety of options.
-
-* https://kind.sigs.k8s.io/docs/user/quick-start/[Kind]
-* https://minikube.sigs.k8s.io/docs/start/[Minikube]
-
-Camel CLI is able to interact with any of these Kubernetes platforms (remote or local).
-
-Running Camel routes on Kubernetes is quite simple with Camel CLI.
-In fact, you can develop and test your Camel route locally with Camel CLI and then promote the same source to running it as an integration on Kubernetes.
-
-The Camel CLI Kubernetes functionality is provided as a command plugin.
-This means you need to enable the `kubernetes` plugin first to use the subcommands in Camel CLI.
+Enable the plugin:
[source,bash]
----
camel plugin add kubernetes
----
-You should see the `kubernetes` plugin listed as an installed plugin.
-
-[source,bash]
-----
-camel plugin get
-----
-
-[source,bash]
-----
- NAME COMMAND DEPENDENCY DESCRIPTION
- kubernetes kubernetes org.apache.camel:camel-jbang-plugin-kubernetes Run Camel applications on Kubernetes
-----
-
-Now Camel CLI is able to run the subcommands offered by the plugin.
-You can inspect the help page to see the list of available plugin subcommands.
-
-[source,bash]
-----
-camel kubernetes --help
-----
+TIP: Run `camel kubernetes --help` to see all subcommands.
== Kubernetes export
-The Kubernetes plugin works with the Camel CLI export functionality.
-The project export generates a proper Maven/Gradle project following one of the available runtime types Quarkus, SpringBoot or camel-main.
-
-In case you export the project with the Kubernetes plugin the exported project holds all information (e.g. sources, properties, dependencies, etc.) and is ready to build, push and deploy the application to Kubernetes, too.
-The export generates a Kubernetes manifest (kubernetes.yml) that holds all resources (e.g. Deployment, Service, ConfigMap) required to run the application on Kubernetes.
-
-You can create a project export with the following command.
+Export a Maven project with a Kubernetes manifest (`kubernetes.yml`) containing Deployment, Service, ConfigMap, and other resources:
[source,bash]
----
camel kubernetes export route.yaml --dir some/path/to/project
----
-The command receives one or more source files (e.g. Camel routes), and performs the export.
-As a result, you will find the Maven/Gradle project sources generated into the given project path.
-
-The default runtime of the project is Quarkus.
-You can adjust the runtime with an additional command option `--runtime=quarkus`.
-
-If you want to run this application on Kubernetes, you need to build the container image, push it to a registry and deploy the application to Kubernetes.
-
-TIP: The Camel CLI Kubernetes plugin provides a `run` command that combines these steps (export, container image build, push, deploy) into a single command.
-
-You can now navigate to the generated project folder and build the project artifacts for instance with this Maven command.
+The default runtime is Quarkus (`--runtime=quarkus`). Build and deploy:
[source,bash]
----
./mvnw package -Dquarkus.container-image.build=true
-----
-
-According to the runtime type (e.g., quarkus) defined for the export this builds and creates a Quarkus application artifact JAR in the Maven build output folder (e.g. `target/route-1.0-SNAPSHOT.jar`).
-
-The option `-Dquarkus.container-image.build=true` also builds a container image that is ready for deployment to Kubernetes.
-More precisely, the exported project uses the very same tooling and options as an arbitrary Quarkus/SpringBoot application would do.
-This means you can easily customize the container image and all settings provided by the runtime provider (e.g., Quarkus or SpringBoot) after the export.
-
-The Kubernetes deployment resources are automatically generated with the export, too.
-
-You can find the Kubernetes manifest in `src/main/kubernetes/kubernetes.yml`.
-
-For instance with the option `-Dquarkus.kubernetes.deploy=true` uses this manifest to trigger the Kubernetes deployment as part of the Maven build.
-
-[source,bash]
-----
./mvnw package -Dquarkus.kubernetes.deploy=true
----
-You will see the Deployment on Kubernetes shortly after this command has finished.
+TIP: The `camel kubernetes run` command combines export, build, push, and deploy into a single step.
-The Camel CLI Kubernetes export command provides several options to customize the exported project.
+The export command provides several options to customize the project:
[width="100%",cols="1m,3",options="header",]
|=======================================================================
@@ -170,59 +105,30 @@ The Camel CLI Kubernetes export command provides several options to customize th
|The target cluster type. Special configurations may be applied to different cluster types such as Kind or Minikube.
|--profile
-|The developer xref:manual::camel-jbang.adoc#_using_profiles[profile] to use a specific configuration in configuration files using the naming style `application-<profile>.properties`.
+|The developer xref:manual::camel-jbang-running.adoc#_using_profiles[profile] to use a specific configuration in configuration files using the naming style `application-<profile>.properties`.
|=======================================================================
-The Kubernetes plugin export command also inherits all options from the arbitrary Camel CLI export command.
+TIP: Run `camel kubernetes export --help` for all options (includes inherited Camel CLI export options).
-TIP: See the possible options by running: `camel kubernetes export --help` for more details.
+=== Health probes
-=== Kubernetes Container Health Probes
+The export includes `camel-observability-services` by default, which prefixes health probes with `/observe`:
-The Observability Services component is set by default in the project created by the export command, then the health path probes are prefixed with the `/observe` endpoint, regardless if they are Quarkus or Spring Boot.
-
-These are the HTTP Container probe endpoints.
-
-For Quarkus.
-[source]
-----
-/observe/health/live
-/observe/health/ready
-/observe/health/started
-----
-
-For Spring Boot (there is no startup probe)
-[source]
-----
-/observe/health/liveness
-/observe/health/readiness
-----
-
-Note that these container probes are generated by jkube plugin, when you run the `k8s:resource` to generate the manifests in the `target/kubernetes/kubernetes.yml`.
-
-You can export to a project and manually remove the `camel-observability-services` artifact from the `pom.xml`.
+- Quarkus: `/observe/health/live`, `/observe/health/ready`, `/observe/health/started`
+- Spring Boot: `/observe/health/liveness`, `/observe/health/readiness`
== Kubernetes manifest options
-The Kubernetes manifest (kubernetes.yml) describes all resources to successfully run the application on Kubernetes.
-The manifest usually holds the deployment, a service definition, config maps and much more.
+Customize the Kubernetes manifest using traits (from Camel K). Trait configuration precedence:
-You can use several options on the `export` command to customize this manifest with the traits.
-The trait concept was born out of Camel K, and the Camel K operator uses the traits to configure the Kubernetes resources that are managed by an integration.
-You can use the same options to also customize the Kubernetes manifest that is generated as part of the project export.
+1. `--trait` command options
+2. Annotations with prefix `trait.camel.apache.org/*`
+3. Properties in `application-<profile>.properties` with prefix `camel.jbang.trait.*`
+4. Properties in `application.properties` with prefix `camel.jbang.trait.*`
-The configuration of the traits is used by the given order:
+=== Container trait
-1. Use the `--trait` command options values
-2. Any annotation starting with the prefix `trait.camel.apache.org/*`
-3. Any properties from the specific configuration `application-<profile>.properties` for the profile defined by the command option `--profile` with the prefix `camel.jbang.trait.*`
-4. Any properties from the default configuration `application.properties` with the prefix `camel.jbang.trait.*`
-
-=== Container trait options
-
-The container specification is part of the Kubernetes Deployment resource and describes the application container image, exposed ports and health probes, for example.
-
-The container trait is able to customize the container specification with the following options:
+Customize the container specification (image, ports, resources):
[cols="2m,1m,5a"]
|===
@@ -278,79 +184,22 @@ The container trait is able to customize the container specification with the fo
|===
-The syntax to specify container trait options is as follows:
-
-[source,bash]
-----
-camel kubernetes export Sample.java --trait container.[key]=[value]
-----
-
-You may specify these options with the export command to customize the container specification.
+Example:
[source,bash]
----
-camel kubernetes export Sample.java --trait container.name=my-container --trait container.port=8088 --trait container.imagePullPolicy=IfNotPresent --trait container.request-cpu=0.005 --trait container.request-memory=100Mi
-----
-
-This results in the following container specification in the Deployment resource.
-
-[source,yaml]
-----
-apiVersion: apps/v1
-kind: Deployment
-metadata:
- labels:
- camel.apache.org/integration: sample
- name: sample
-spec:
- selector:
- matchLabels:
- camel.apache.org/integration: sample
- template:
- metadata:
- labels:
- camel.apache.org/integration: sample
- spec:
- containers:
- - image: quay.io/sample:1.0-SNAPSHOT #<1>
- imagePullPolicy: IfNotPresent #<2>
- name: my-container #<3>
- ports:
- - containerPort: 8088 #<4>
- name: http
- protocol: TCP
- resources:
- requests:
- memory: 100Mi
- cpu: '0.005'
+camel kubernetes export Sample.java --trait container.name=my-container --trait container.port=8088 --trait container.request-cpu=0.005 --trait container.request-memory=100Mi
----
-<1> Container image running the application
-<2> Customized image pull policy
-<3> Custom container name
-<4> Custom container port exposed
-
-=== Cronjob
-It's possible to run the workload as a https://kubernetes.io/docs/concepts/workloads/controllers/cron-jobs/[CronJob], it allows to set some parameters as `schedule`, `timezone`, `startingDeadlineSeconds`, `activeDeadlineSeconds`, `backoffLimit`, and `durationMaxIdleSeconds`. When the CronJob trait is used, it doesn't contain the container health probes, since the Cronjob doesn't use them to start or check the pods.
+=== CronJob trait
-To generate the CronJob manifest, these are required trait parameters: `enabled=true` and `schedule`.
-
-.Example
+Generate a https://kubernetes.io/docs/concepts/workloads/controllers/cron-jobs/[CronJob] instead of a Deployment (requires `enabled=true` and `schedule`):
[source,bash]
----
-camel kubernetes export Sample.java \
- --trait=cronjob.enabled=true \
- --trait=cronjob.schedule="* * * * 2" \
- --trait=cronjob.timezone="Europe/Lisbon" \
- --trait=cronjob.startingDeadlineSeconds=3 \
- --trait=cronjob.activeDeadlineSeconds=7 \
- --trait=cronjob.backoffLimit=4 \
- --trait=cronjob.durationMaxIdleSeconds=2
+camel kubernetes export Sample.java --trait=cronjob.enabled=true --trait=cronjob.schedule="* * * * 2"
----
-The CronJob configuration parameters:
-
[cols="2m,1m,5a"]
|===
|Property | Type | Description
@@ -387,128 +236,26 @@ The CronJob configuration parameters:
=== Labels and annotations
-You may need to add labels or annotations to the generated Kubernetes resources.
-By default, the generated resources will have the label `camel.apache.org/integration` set to the exported project name.
-
-When the `--observe` command option is present (it is by default) then the generated resources will also have the label `camel.apache.org/app` set to the exported project name.
-
-You can add labels and annotations with these options on the export command:
-
-[source,bash]
-----
-camel kubernetes export Sample.java --annotation [key]=[value] --label [key]=[value]
-----
-
-.Example
+By default, resources have the label `camel.apache.org/integration` set to the project name.
+Add custom labels and annotations:
[source,bash]
----
-camel kubernetes export Sample.java --annotation project.team=camel-experts
+camel kubernetes export Sample.java --annotation project.team=camel-experts --label env=staging
----
-[source,yaml]
-----
-apiVersion: apps/v1
-kind: Deployment
-metadata:
- annotations:
- project.team: camel-experts #<1>
- labels:
- camel.apache.org/integration: sample
- name: sample
-spec:
- selector:
- matchLabels:
- camel.apache.org/integration: sample
- template:
- metadata:
- labels:
- camel.apache.org/integration: sample
- spec:
- containers:
- - image: quay.io/sample:1.0-SNAPSHOT
- name: sample
-----
-<1> Custom deployment annotation
-
=== Environment variables
-The environment trait is there to set environment variables on the container specification.
-
-The environment trait provides the following configuration options:
-
-[cols="2m,1m,5a"]
-|===
-|Property | Type | Description
-
-| environment.vars
-| []string
-| A list of environment variables to be added to the integration container.
-The syntax is KEY=VALUE separated by a comma, e.g., `'MY_VAR="my value"','MY_OTHER_VAR="my value"'` .
-
-These take precedence over the previously defined environment variables.
-
-|===
-
-The syntax to specify environment trait options is as follows:
+Set environment variables with `--trait environment.vars=KEY=VALUE` or the shortcut `--env KEY=VALUE`:
[source,bash]
----
-camel kubernetes export Sample.java --trait environment.[key]=[value]
-----
-
-There is also a shortcut option `--env` that you can use.
-
-[source,bash]
-----
-camel kubernetes export Sample.java --env [key]=[value]
-----
-
-.Example
-[source,bash]
-----
-camel kubernetes export Sample.java --trait environment.vars=MY_ENV=foo --env FOO_ENV=bar
-----
-
-This results in the following container specification in the Deployment resource.
-
-[source,yaml]
-----
-apiVersion: apps/v1
-kind: Deployment
-metadata:
- labels:
- camel.apache.org/integration: sample
- name: sample
-spec:
- selector:
- matchLabels:
- camel.apache.org/integration: sample
- template:
- metadata:
- labels:
- camel.apache.org/integration: sample
- spec:
- containers:
- - image: quay.io/sample:1.0-SNAPSHOT
- name: sample
- env: #<1>
- - name: MY_ENV
- value: foo
- - name: FOO_ENV
- value: bar
+camel kubernetes export Sample.java --env MY_ENV=foo --env FOO_ENV=bar
----
-<1> Environment variables set in the container specification
-
-=== Service trait options
-
-The Service trait enhances the Kubernetes manifest with a Service resource so that the application can be accessed by other components in the same namespace.
-The service resource exposes the application with a protocol (e.g., TCP/IP) on a given port and uses either `ClusterIP`, `NodePort` or `LoadBalancer` type.
-The Camel CLI plugin automatically inspects the Camel routes for exposed Http services and adds the service resource when applicable.
-This means when one of the Camel routes exposes a Http service (for instance by using the `platform-http` component) the Kubernetes manifest also creates a Kubernetes Service resource besides the arbitrary Deployment.
+=== Service trait
-You can customize the generated Kubernetes service resource with trait options:
+A Service resource is auto-generated when routes expose HTTP endpoints (e.g., `platform-http`). Customize it:
[cols="2m,1m,5a"]
|===
@@ -528,21 +275,13 @@ You can customize the generated Kubernetes service resource with trait options:
|===
-=== Knative service trait options
-
-https://knative.dev/docs/serving/[Knative serving] defines a set of resources on Kubernetes to handle Serverless workloads with automatic scaling and scale-to-zero functionality.
-
-When Knative serving is available on the target Kubernetes cluster, you may want to use the Knative service resource instead of an arbitrary Kubernetes service resource.
-The Knative service trait will create such a resource as part of the Kubernetes manifest.
-
-NOTE: The `knative-service` trait is disabled by default, you need to enable the Knative service trait with `--trait knative-service.enabled=true` option. Otherwise, the Camel CLI export will always create an arbitrary Kubernetes service resource.
+=== Knative service trait
-NOTE: If you enable the knative-service trait and deploys to minikube and uses the docker builder to build the container image in the minikube registry addon, it's likely the container image published won't contain the digest value, and https://knative.dev/docs/serving/configuration/deployment/#skipping-tag-resolution[knative-serving has a verification to check the image digest], so the pod will fail to start with the error message `failed to resolve image to digest`, so for development [...]
+Use https://knative.dev/docs/serving/[Knative serving] for serverless workloads with auto-scaling and scale-to-zero.
-WARN: Currently knative-service doesn't work in OpenShift, work is underway to fix it.
+NOTE: Disabled by default — enable with `--trait knative-service.enabled=true`.
-
-The trait offers following options for customization:
+WARN: Currently does not work on OpenShift.
[cols="2m,1m,5a"]
|===
@@ -611,21 +350,11 @@ Refer to the Knative documentation for more information.
|===
-=== Connecting to Knative
-
-The previous section described how the exported Apache Camel application can leverage the Knative service resource with auto-scaling as part of the deployment to Kubernetes.
-
-Apache Camel also provides a Knative component that makes you easily interact with https://knative.dev/docs/eventing/[Knative eventing] and https://knative.dev/docs/serving/[Knative serving].
+=== Knative component trait
-The Knative component enables you to exchange data with the Knative eventing broker and other Knative services deployed on Kubernetes.
-The Camel CLI Kubernetes plugin provides some autoconfiguration options when connecting with the Knative component.
-The export command assists you in configuring both the Knative component and the Kubernetes manifest for connecting to Knative resources on the Kubernetes cluster.
+Configure the Camel Knative component to interact with https://knative.dev/docs/eventing/[Knative eventing] and https://knative.dev/docs/serving/[Knative serving]. The export auto-configures both the component and the Kubernetes manifest.
-You can configure the Knative component with the Knative trait.
-
-NOTE: The `knative` trait is disabled by default, you need to enable the Knative trait with `--trait knative.enabled=true` option.
-
-The trait offers the following options for customization:
+NOTE: Disabled by default — enable with `--trait knative.enabled=true`.
[cols="2m,1m,5a"]
|===
@@ -682,17 +411,7 @@ Refer to the Knative documentation for more information.
=== Knative trigger
-The concept of a Knative trigger allows you to consume events from the https://knative.dev/docs/eventing/[Knative eventing] broker.
-In case your Camel route uses the Knative component as a consumer you may need to create a trigger in Kubernetes
-to connect your Camel application with the Knative broker.
-
-The Camel CLI Kubernetes plugin is able to automatically create this trigger for you.
-
-NOTE: The `knative` trait is disabled by default, you need to enable the Knative trait with `--trait knative.enabled=true` option.
-
-The following Camel route uses the Knative event component and references a Knative broker by its name.
-The plugin inspects the code and automatically generates the Knative trigger as part of the Kubernetes manifest that is used
-to run the Camel application on Kubernetes.
+When a route consumes from `knative:event`, the plugin automatically generates a Knative Trigger in the manifest:
[source,yaml]
----
@@ -706,239 +425,18 @@ to run the Camel application on Kubernetes.
uri: log:info
----
-The route consumes Knative events of type `camel.evt.type`.
-If you export this route with the Camel CLI Kubernetes plugin, you will see a Knative trigger being generated as part of the Kubernetes manifest (kubernetes.yml).
-
-[source,bash]
-----
-camel kubernetes export knative-route.yaml
-----
-
-The generated export project can be deployed to Kubernetes, and as part of the deployment, the trigger is automatically created so the application can start consuming events.
-
-The generated trigger looks as follows:
-
-[source,yaml]
-----
-apiVersion: eventing.knative.dev/v1
-kind: Trigger
-metadata:
- name: my-broker-knative-route-camel-evt-type
-spec:
- broker: my-broker
- filter:
- attributes:
- type: camel.evt.type
- subscriber:
- ref:
- apiVersion: v1
- kind: Service
- name: knative-route
- uri: /events/camel-evt-type
-----
-
-The trigger uses a default filter on the event type CloudEvents attribute and calls the Camel application via the exposed Kubernetes service resource.
-
-The Camel application is automatically configured to expose an Http service so incoming events are handed over to the Camel route.
-You can review the Knative service resource configuration that makes Camel configure the Knative component.
-The configuration has been automatically created in `src/main/resources/knative.json` in the exported project.
-
-Here is an example of the generated `knative.json` file:
-
-[source,json]
-----
-{
- "resources" : [ {
- "name" : "camel-event",
- "type" : "event",
- "endpointKind" : "source",
- "path" : "/events/camel-event",
- "objectApiVersion" : "eventing.knative.dev/v1",
- "objectKind" : "Broker",
- "objectName" : "my-broker",
- "reply" : false
- } ]
-}
-----
-
-The exported project has everything configured to run the application on Kubernetes.
-Of course, you need Knative eventing installed on your target cluster, and you need to have a Knative broker named `my-broker` available in the target namespace.
-
-Now you can just deploy the application using the Kubernetes manifest and see the Camel route consuming events from the broker.
+Export with `camel kubernetes export knative-route.yaml` — the trigger, service, and `knative.json` configuration are all generated automatically.
=== Knative channel subscription
-Knative channels represent another form of producing and consuming events from the Knative broker.
-Instead of using a trigger, you can create a subscription for a Knative channel to consume events.
-
-NOTE: The `knative` trait is disabled by default, you need to enable the Knative trait with `--trait knative.enabled=true` option.
-
-The Camel route that connects to a Knative channel in order to receive events looks like this:
-
-[source,yaml]
-----
-- route:
- from:
- uri: knative:channel/my-channel
- steps:
- - to:
- uri: log:info
-----
-
-The Knative channel is referenced by its name.
-The Camel CLI Kubernetes plugin will inspect your code to automatically create a channel subscription as part of the Kubernetes manifest.
-You just need to export the Camel route as usual.
-
-[source,bash]
-----
-camel kubernetes export knative-route.yaml
-----
-
-The code inspection recognizes the Knative component that references the Knative channel, and the subscription automatically becomes part of the exported Kubernetes manifest.
-
-Here is an example subscription that has been generated during the export:
-
-[source,yaml]
-----
-apiVersion: messaging.knative.dev/v1
-kind: Subscription
-metadata:
- name: my-channel-knative-route
-spec:
- channel:
- apiVersion: messaging.knative.dev/v1
- kind: Channel
- name: my-channel
- subscriber:
- ref:
- apiVersion: v1
- kind: Service
- name: knative-route
- uri: /channels/my-channel
-----
-
-The subscription connects the Camel application with the channel, so each event on the channel is sent to the Kubernetes service resource that also has been created as part of the Kubernetes manifest.
-
-The Camel Knative component uses a service resource configuration internally to create the proper Http service.
-You can review the Knative service resource configuration that makes Camel configure the Knative component.
-The configuration has been automatically created in `src/main/resources/knative.json` in the exported project.
-
-Here is an example of the generated `knative.json` file:
-
-[source,json]
-----
-{
- "resources" : [ {
- "name" : "my-channel",
- "type" : "channel",
- "endpointKind" : "source",
- "path" : "/channels/my-channel",
- "objectApiVersion" : "messaging.knative.dev/v1",
- "objectKind" : "Channel",
- "objectName" : "my-channel",
- "reply" : false
- } ]
-}
-----
-
-Assuming that you have Knative eventing installed on your cluster and that you have set up the Knative channel `my-channel` you can start consuming events right away.
-The deployment of the exported project uses the Kubernetes manifest to create all required resources, including the Knative subscription.
+Similarly, routes consuming from `knative:channel/my-channel` automatically generate a Knative Subscription in the manifest. The `knative.json` configuration is auto-generated.
=== Knative sink binding
-When connecting to a Knative resource (Broker, Channel, Service) in order to produce events for Knative eventing you probably want to use a `SinkBinding` that resolves the URL to the Knative resource for you.
-The sink binding is a Kubernetes resource that makes Knative eventing automatically inject the resource URL into your Camel application on startup.
-The Knative URL injection uses environment variables (`K_SINK`, `K_CE_OVERRIDES`) on your deployment.
-The Knative eventing operator will automatically resolve the Knative resource (e.g. a Knative broker URL) and inject the value so your application does not need to know the actual URL when deploying.
-
-The Camel CLI Kubernetes plugin leverages the sink binding concept for all routes that use the Knative component as an output.
-
-NOTE: The `knative` trait is disabled by default, you need to enable the Knative trait with `--trait knative.enabled=true` option.
-
-The following route produces events on a Knative broker:
-
-[source, yaml]
-----
-- route:
- from:
- uri: timer:tick
- steps:
- - setBody:
- constant: Hello Camel !!!
- - to:
- uri: knative:event/camel.evt.type
- parameters:
- name: my-broker
-----
-
-The route produces events of type `camel.evt.type` and pushes the events to the broker named `my-broker`.
-At this point, the actual Knative broker URL is unknown.
-The sink binding is going to resolve the URL and inject its value at deployment time using the `K_SINK` environment variable.
-
-The Camel CLI Kubernetes plugin export automatically inspects such a route and automatically creates the sink binding resource for us.
-The sink binding is part of the exported Kubernetes manifest and is created on the cluster as part of the deployment.
-
-A sink binding resource created by the export command looks like follows:
-
-[source,bash]
-----
-camel kubernetes export knative-route.yaml
-----
+Routes that produce to `knative:event`, `knative:channel`, or `knative:endpoint` automatically get a `SinkBinding` resource in the manifest. Knative injects the target URL via the `K_SINK` environment variable at deployment time, so the route doesn't need to know the actual URL.
+=== Mount trait
-[source,yaml]
-----
-apiVersion: sources.knative.dev/v1
-kind: SinkBinding
-metadata:
- finalizers:
- - sinkbindings.sources.knative.dev
- name: knative-route
-spec:
- sink:
- ref:
- apiVersion: eventing.knative.dev/v1
- kind: Broker
- name: my-broker
- subject:
- apiVersion: apps/v1
- kind: Deployment
- name: knative-route
-----
-
-In addition to creating the sink binding, the Camel CLI plugin also takes care of configuring the Knative Camel component.
-The Knative component uses a configuration file that you can find in `src/main/resources/knative.json`.
-As you can see the configuration uses the `K_SINK` injected property placeholder as a broker URL.
-
-[source,json]
-----
-{
- "resources" : [ {
- "name" : "camel-evt-type",
- "type" : "event",
- "endpointKind" : "sink",
- "url" : "{{k.sink}}",
- "objectApiVersion" : "eventing.knative.dev/v1",
- "objectKind" : "Broker",
- "objectName" : "my-broker",
- "reply" : false
- } ]
-}
-----
-
-As soon as the Kubernetes deployment for the exported project has started the sink binding will inject the `K_SINK` environment variable so that the Camel applicaiton is ready to send events to the Knative broker.
-
-The sink binding concept works for Knative Broker, Channel and Service resources.
-You just reference the resource by its name in your Camel route when sending data to the Knative component as an output of the route (`to("knative:event|channel|endpoint/<resource-name>")`).
-
-=== Mount trait options
-
-The mount trait is able to configure volume mounts on the Deployment resource in order to inject data from Kubernetes resources such as config maps or secrets.
-
-There are also shortcut options like `--volume`, `--config` and `--resource` for the mount trait.
-These options are described in more detail in the next section.
-For now let's have a look into the pure mount trait configuration options.
-
-The mount trait provides the following configuration options:
+Configure volume mounts from ConfigMaps, Secrets, and PVCs. Shortcuts: `--volume`, `--config`, `--resource`.
[cols="2m,1m,5a"]
|===
@@ -964,151 +462,18 @@ Syntax: [configmap\|secret]:name[/key][@path], where name represents the resourc
|===
-The syntax to specify mount trait options is as follows:
+Example:
[source,bash]
----
-camel kubernetes export Sample.java --trait mount.[key]=[value]
+camel kubernetes export Sample.java --config secret:my-credentials --resource configmap:my-data --volume my-pvc:/container/path
----
-.Example
-[source,bash]
-----
-camel kubernetes export Sample.java --trait mount.configs=configmap:my-data --trait mount.volumes=my-pvc:/container/path
-----
-
-This results in the following container specification in the Deployment resource.
-
-[source,yaml]
-----
-apiVersion: apps/v1
-kind: Deployment
-metadata:
- labels:
- camel.apache.org/integration: sample
- name: sample
-spec:
- selector:
- matchLabels:
- camel.apache.org/integration: sample
- template:
- metadata:
- labels:
- camel.apache.org/integration: sample
- spec:
- containers:
- - image: quay.io/sample:1.0-SNAPSHOT
- name: sample
- volumeMounts:
- - mountPath: /etc/camel/conf.d/_configmaps/my-data #<1>
- name: my-data
- readOnly: true
- - mountPath: /container/path #<2>
- name: my-pvc
- readOnly: false
- volumes:
- - name: my-data #<3>
- configMap:
- name: my-data
- - name: my-pvc #<4>
- persistentVolumeClaim:
- claimName: my-pvc
-----
-<1> The config map `my-data` mounted into the container with default mount path for configurations
-<2> The volume mounted into the container with given path
-<3> The config map reference as volume spec
-<4> The persistent volume claim `my-pvc`
-
-=== ConfigMaps, volumes and secrets
-
-In the previous section, we have seen how to mount volumes, configs, and resources into the container.
-
-The Kubernetes export command provides some shortcut options for adding configmaps and secrets as volume mounts.
-The syntax is as follows:
-
-[source,bash]
-----
-camel kubernetes export Sample.java --config [key]=[value] --resource [key]=[value] --volume [key]=[value]
-----
-
-The options expect the following syntax:
-
-[cols="2m,5a"]
-|===
-|Option | Syntax
-
-| config
-| Add a runtime configuration from a ConfigMap or a Secret (syntax: [configmap\|secret]:name[/key], where name represents the configmap or secret name and key optionally represents the configmap or secret key to be filtered).
-
-| resource
-| Add a runtime resource from a Configmap or a Secret (syntax: [configmap\|secret]:name[/key][@path], where name represents the configmap or secret name, key optionally represents the configmap or secret key to be filtered and the path represents the destination path).
-
-| volume
-| Mount a volume into the integration container, for instance "--volume pvcname:/container/path".
-
-|===
-
-.Example
-[source,bash]
-----
-camel kubernetes export Sample.java --config secret:my-credentials --resource configmap:my-data --volume my-pvc:/container/path
-----
-
-[source,yaml]
-----
-apiVersion: apps/v1
-kind: Deployment
-metadata:
- labels:
- camel.apache.org/integration: sample
- name: sample
-spec:
- selector:
- matchLabels:
- camel.apache.org/integration: sample
- template:
- metadata:
- labels:
- camel.apache.org/integration: sample
- spec:
- containers:
- - image: quay.io/sample:1.0-SNAPSHOT
- name: sample
- volumeMounts:
- - mountPath: /etc/camel/conf.d/_secrets/my-credentials
- name: my-credentials #<1>
- readOnly: true
- - mountPath: /etc/camel/resources.d/_configmaps/my-data
- name: my-data #<2>
- readOnly: true
- - mountPath: /container/path
- name: my-pvc #<3>
- readOnly: false
- volumes:
- - name: my-credentials #<4>
- secret:
- secretName: my-credentials
- - name: my-data #<5>
- configMap:
- name: my-data
- - name: my-pvc #<6>
- persistentVolumeClaim:
- claimName: my-pvc
-----
-<1> The secret configuration volume mount
-<2> The config map resource volume mount
-<3> The volume mount
-<4> The secret configuration volume
-<5> The config map resource volume
-<6> The persistent volume claim volume
-
-The trait volume mounts follow some best practices in specifying the mount paths in the container. Configurations and resources, secrets, and configmaps do use different paths in the container. The Camel application is automatically configured to read these paths as resource folders, so you can use the mounted data in the Camel routes via classpath reference, for instance.
-
-=== Ingress trait options
+Mount paths follow Camel conventions: configs go to `/etc/camel/conf.d/`, resources to `/etc/camel/resources.d/`, and the application is auto-configured to read these paths.
-The ingress trait enhances the Kubernetes manifest with an Ingress resource to expose the application to the outside world. This requires the presence in the Kubernetes manifest of a Service Resource.
+=== Ingress trait
-The ingress trait provides the following configuration options:
+Add an Ingress resource to expose the application externally (requires a Service resource):
[cols="2m,1m,5a"]
|===
@@ -1148,60 +513,16 @@ The ingress trait provides the following configuration options:
|===
-The syntax to specify container trait options is as follows:
+Example:
[source,bash]
----
-camel kubernetes export Sample.java --trait ingress.[key]=[value]
+camel kubernetes export Sample.java --trait ingress.enabled=true --trait ingress.host=example.com --trait ingress.path=/sample
----
-You may specify these options with the export command to customize the Ingress Resource specification.
-
-[source,bash]
-----
-camel kubernetes export Sample.java --trait ingress.enabled=true --trait ingress.host=example.com --trait ingress.path=/sample(/|$)(.*) --trait ingress.pathType=ImplementationSpecific --trait ingress.annotations=nginx.ingress.kubernetes.io/rewrite-target=/\$2 --trait ingress.annotations=nginx.ingress.kubernetes.io/use-regex=true
-----
-
-
-This results in the following container specification in the Ingress resource.
-
-[source,yaml]
-----
-apiVersion: networking.k8s.io/v1
-kind: Ingress
-metadata:
- annotations: #<1>
- nginx.ingress.kubernetes.io/rewrite-target: /$2
- nginx.ingress.kubernetes.io/use-regex: "true"
- labels:
- app.kubernetes.io/name: sample
- name: sample
-spec:
- ingressClassName: nginx
- rules:
- - host: example.com
- http:
- paths:
- - backend:
- service:
- name: route-service
- port:
- name: http #<2>
- path: /sample(/|$)(.*) #<3>
- pathType: ImplementationSpecific #<4>
-
-
-----
-<1> Custom annotations configuration for ingress behavior
-<2> Service port name
-<3> Custom ingress backend path
-<4> Custom ingress backend path type
-
-=== Route trait options
-
-The Route trait enhances the Kubernetes manifest with a Route resource to expose the application to the outside world. This requires the presence in the Kubernetes manifest of a Service Resource.
+=== Route trait (OpenShift)
-The Route trait provides the following configuration options:
+Add an OpenShift Route resource to expose the application externally:
[cols="2m,1m,5a"]
|===
@@ -1246,56 +567,16 @@ The Route trait provides the following configuration options:
|===
-The syntax to specify container trait options is as follows:
+Example:
[source,bash]
----
-camel kubernetes export Sample.java --trait route.[key]=[value]
+camel kubernetes export Sample.java --cluster-type=openshift --trait route.enabled=true --trait route.host=example.com --trait route.tls-termination=edge
----
-You may specify these options with the export command to customize the Route Resource specification.
+=== Jolokia trait
-[source,bash]
-----
-camel kubernetes export Sample.java --cluster-type=openshift -t route.enabled=true --trait route.host=example.com -t route.tls-termination=edge -t route.tls-certificate=file:/tmp/tls.crt -t route.tls-key=file:/tmp/tls.key
-----
-
-
-This results in the following container specification in the Route resource.
-
-[source,yaml]
-----
-apiVersion: route.openshift.io/v1
-kind: Route
-metadata:
- name: route-service
-spec:
- host: example.com #<1>
- port:
- targetPort: http #<2>
- tls:
- certificate: | #<3>
- ...
- key: | #<4>
- ...
- termination: edge #<5>
- to: #<6>
- kind: Service
- name: route-service
-----
-<1> Custom route host
-<2> Service port name
-<3> Custom route TLS certificate content
-<4> Custom route TLS certificate key content
-<5> Custom route TLS termination
-<6> Service Resource reference
-
-
-=== Jolokia trait options
-
-The Jolokia trait enhances the Kubernetes manifest enabling JMX access to Camel application. This requires jolokia being configured in the Camel Application.
-
-The Jolokia trait provides the following configuration options:
+Enable JMX access via Jolokia (requires Jolokia configured in the application):
[cols="2m,1m,5a"]
|===
@@ -1328,431 +609,141 @@ The Jolokia trait provides the following configuration options:
|===
-The syntax to specify jolokia trait options is as follows:
-
-[source,bash]
-----
-camel kubernetes export Sample.java --trait jolokia.[key]=[value]
-----
-
-You may specify these options with the export command to customize the Container and Service Resource specification for Jolokia.
+Example:
[source,bash]
----
-camel kubernetes export Sample.java --trait jolokia.enabled=true --trait jolokia.container-port=8779 --trait jolokia.container-port-name=jolokia-port --trait jolokia.expose=true --trait jolokia.service-port=8779 --trait jolokia.service-port-name=port-jolokia
-----
-
-This results in the following specifications in the Deployment and Service resources.
-
-[source,yaml]
-----
-apiVersion: apps/v1
-kind: Deployment
-metadata:
- ...
- name: sample
-spec:
- selector:
- ...
- template:
- ...
- spec:
- containers:
- - name: sample
- ports:
- - containerPort: 8080
- name: http
- protocol: TCP
- - containerPort: 8779 #<1>
- name: jolokia-port #<2>
- protocol: TCP
-...
+camel kubernetes export Sample.java --trait jolokia.enabled=true --trait jolokia.expose=true
----
-[source,yaml]
-----
-apiVersion: v1
-kind: Service
-metadata:
-...
- name: sample
-spec:
- ports:
- - name: http
- port: 80
- protocol: TCP
- targetPort: http
- - name: jolokia-port #<3>
- port: 8779 #<4>
- protocol: TCP
- targetPort: jolokia-port #<2>
-...
-----
-
-<1> Custom Jolokia container port
-<2> Custom Jolokia container port name
-<3> Custom Jolokia service port name
-<4> Custom Jolokia service port
-
-
-=== OpenApi specifications
-You can mount OpenAPI specifications to the application container with this trait.
+=== OpenAPI trait
-The openapi trait provides the following configuration options:
-
-[cols="2m,1m,5a"]
-|===
-|Property | Type | Description
-
-| openapi.configmaps
-| []string
-| The configmaps holding the spec of the OpenAPI
-
-|===
-
-The syntax to specify openapi trait options is as follows:
+Mount OpenAPI specs from ConfigMaps:
[source,bash]
----
-camel kubernetes export Sample.java --trait openapi.[key]=[value]
+camel kubernetes export Sample.java --open-api configmap:my-spec
----
-.Example
-[source,bash]
-----
-camel kubernetes export Sample.java --trait openapi.configmaps=configmap:my-spec
-----
+== Deploy to OpenShift
-TIP: There is also a shortcut option `--open-api=configmap:my-configmap`.
+Use `--cluster-type=openshift` to generate OpenShift-specific resources (Route, ImageStream, BuildConfig):
[source,bash]
----
-camel kubernetes export Sample.java --open-api configmap:[name-of-configmap]
+camel kubernetes export Sample.java --cluster-type=openshift
----
-This results in the following container specification in the Deployment resource.
+The default image builder switches to S2I for OpenShift. Override with `--image-builder=jib` to push to an external registry instead.
-[source,yaml]
-----
-apiVersion: apps/v1
-kind: Deployment
-metadata:
- labels:
- camel.apache.org/integration: sample
- name: sample
-spec:
- selector:
- matchLabels:
- camel.apache.org/integration: sample
- template:
- metadata:
- labels:
- camel.apache.org/integration: sample
- spec:
- containers:
- - image: quay.io/sample:1.0-SNAPSHOT
- name: sample
- volumeMounts:
- - mountPath: /etc/camel/resources.d/_configmaps/my-spec
- name: my-spec #<1>
- readOnly: true
- volumes:
- - name: my-spec #<2>
- configMap:
- name: my-spec
-----
-<1> OpenAPI specification volume mount
-<2> Volume referencing the config map holding the OpenAPI specification
-
-== Deploy to OpenShift
-
-By default, the Kubernetes manifest is suited for plain Kubernetes platforms.
-In case you are targeting OpenShift as a platform you may want to leverage special resources such as Route, ImageStream or BuildConfig.
-
-You can set the `cluster-type=openshift` option on the export command to tell the Kubernetes plugin to create a Kubernetes manifest specifically suited for OpenShift.
-
-Also, the default image builder is S2I for OpenShift clusters.
-This means by setting the cluster type, you will automatically switch from default Jib to S2I.
-Of course, you can tell the plugin to use Jib with `--image-builder=jib` option.
-The image may then get pushed to an external registry (docker.io or quay.io) so OpenShift can pull as part of the deployment in the cluster.
-
-TIP: When using S2I, you may need to explicitly set the `--image-group` option to the project/namespace name in the OpenShift cluster.
-This is because S2I will push the container image to an image repository that uses the OpenShift project/namespace name as part of the image coordinates in the registry: `image-registry.openshift-image-registry.svc:5000/<project name>/<name>:<tag>`
-
-When using S2I as an image build option, the Kubernetes manifest also contains an ImageStream and BuildConfig resource.
-Both resources are automatically added/removed when creating/deleting the deployment with the Camel Kubernetes JBang plugin.
+TIP: With S2I, set `--image-group` to your OpenShift project/namespace name, since S2I uses it as part of the image coordinates: `image-registry.openshift-image-registry.svc:5000/<project>/<name>:<tag>`
== Kubernetes run
-The run command combines several steps into one single command.
-The command performs a project export to a temporary folder, builds the project artifacts as well as the container images, pushes the image to an image registry and finally performs the deployment to Kubernetes using the generated Kubernetes manifest (`kubernetes.yml`).
+The `run` command exports, builds, pushes, and deploys in one step:
[source,bash]
----
camel kubernetes run route.yaml --image-registry=kind
----
-When connecting to a local Kubernetes cluster, you may need to specify the image registry where the application container image gets pushed to.
-The run command is able to automatically configure the local registry when using predefined names such as `kind` or `minikube`, there is a detection mechanism to set some properties accordingly to the cluster type, currently it can auto detect Openshift and Minikube. If you want to disable the cluster detection, you have to set the `--disable-auto` cli parameter.
+The command auto-detects local clusters (`kind`, `minikube`, OpenShift) and configures the registry accordingly. Disable with `--disable-auto`.
-NOTE: When running minikube, the easiest way to push the image to the minikube container registry, is to enable the registry addon in minikube and to run `eval $(minikube docker-env)`.
-
-Use the `--image-group` or the `--image` option to customize the container image.
+Customize the image:
[source,bash]
----
camel kubernetes run route.yaml --image-registry=kind --image-group camel-experts
-----
-
-The command above builds and pushes the container image: `localhost:5001/camel-experts/route:1.0-SNAPSHOT`.
-
-[source,bash]
-----
camel kubernetes run route.yaml --image quay.io/camel-experts/demo-app:1.0
----
-The `--image` option forces the container image group, name, version as well as the image registry.
+The `run` command supports the same trait options as `export` for customizing the Kubernetes manifest.
-=== Customize the Kubernetes manifest
+=== Auto reload with `--dev`
-The `run` command provides the same options to customize the Kubernetes manifest as the `export` command.
-You may want to add environment variables, mount secrets and configmaps, adjust the exposed service and many other things with trait options as described in the export command section.
-
-=== Auto reload with `--dev` option
-
-The `--dev` option runs the application on Kubernetes and automatically adds a file watcher to listen for changes on the Camel route source files.
-In case the sources get changed, the process will automatically perform a rebuild and redeployment.
-The command constantly prints the logs to the output, so you may see the changes directly being applied to the Kubernetes deployment.
+Watch for source file changes and automatically rebuild/redeploy:
[source,bash]
----
camel kubernetes run route.yaml --image-registry=kind --dev
----
-You need to terminate the process to stop the dev mode.
-This automatically removes the Kubernetes deployment from the cluster on shutdown.
+Terminate the process to stop dev mode — the deployment is automatically removed on shutdown.
-NOTE: On macOS hosts, the file watch mechanism is known to be much slower and less stable compared to using the `--dev` option on other operating systems like Linux.
-This is due to limited native file operations on macOS for Java processes.
+NOTE: On macOS, the file watch mechanism is slower due to limited native file operations for Java processes.
=== Setting properties and resources at runtime
-There are several ways to set runtime properties:
-
-==== Properties as command parameters
-
-The simplest way is to set the property as `key`=`value`:
+Set properties inline, from files, or from Kubernetes resources:
[source,bash]
----
camel kubernetes run route.yaml --property my-key=my-val
-----
-
-==== Properties from files
-
-You can also reference an existing properties file, which in this case the properties content will be read and set in the `src/main/resources/application.properties` file (in the maven project generated by the internal export command).
-
-[source,bash]
-----
-camel kubernetes run route.yaml --property /some/directory/file.properties
-----
-
-You can also use the `file:` prefix
-
-[source,bash]
-----
camel kubernetes run route.yaml --property file:/some/directory/file.properties
----
-==== Properties from ConfigMap and Secret kubernetes resources
-
-The `--config` supports mapping from `ConfigMap` and `Secret` kubernetes resources and materialize as properties files in the pod. There is a standard directory path materialized in the pod filesystem:
-
-* `--config configmap:` materialized in `/etc/camel/conf.d/_configmaps/<configmap name>/<key name>`
-* `--config secret:` materialized in `/etc/camel/conf.d/_secrets/<secret name>/<key name>`
-
-NOTE: For each `--config` the following properties `camel.component.properties.location=<path>` and `camel.component.properties.ignore-missing-location=true` will be set in the generated application.properties, to allow the mapped properties to be readily available in the camel runtime with property placeholders `{{my key}}`.
-
-So, given the following `ConfigMap`, you can see there is a key named `game.properties` whose content is a set of key named values.
-
-[source,bash]
-----
-kind: ConfigMap
-apiVersion: v1
-metadata:
- name: game-config
-data:
- game.properties: |
- my-key=property from SINGLE game.properties
- enemies.cheat=true
- secret.code.lives=30
-----
+==== Properties from ConfigMaps and Secrets
-Materialize the content of `ConfigMap/game-config` using the `--config` parameter:
+Use `--config` to mount ConfigMap/Secret data as properties files, automatically configured for Camel property placeholders:
[source,bash]
----
camel kubernetes run route.java --config configmap:game-config
-----
-
-It will set the following mount options in the deployment manifest:
-
-[source,yaml]
-----
- volumeMounts:
- - mountPath: /etc/camel/conf.d/_configmaps/game-config
- name: game-config
- readOnly: true
-volumes:
-- configMap:
- name: game-config
- name: game-config
-----
-
-Then it will materialize the following file in the pod filesystem:
-----
-/etc/camel/conf.d/_configmaps/game-config/game.properties
-----
-
-Another example, with a `ConfigMap` with more key properties:
-
-[source,yaml]
-----
-kind: ConfigMap
-apiVersion: v1
-metadata:
- name: multiple-config
-data:
- game.properties: |
- my-key=property from game.properties
- secret.code.lives=30
- ui.properties: |
- how.nice.to.look=fairlyNice
-----
-
-[source,bash]
-----
-camel kubernetes run route.java --config configmap:multiple-config
-----
-
-It will materialize the files:
-----
-/etc/camel/conf.d/_configmaps/multiple-config/game.properties
-/etc/camel/conf.d/_configmaps/multiple-config/ui.properties
-----
-
-Note that each `ConfigMap` key is the file name.
-
-You can also map specific keys from the `data` section by using the `/<key name>`:
-
-----
camel kubernetes run route.java --config configmap:game-config/game.properties
+camel kubernetes run route.java --config secret:my-credentials
----
+Mount paths: `--config configmap:` maps to `/etc/camel/conf.d/_configmaps/<name>/<key>`, `--config secret:` maps to `/etc/camel/conf.d/_secrets/<name>/<key>`. Each ConfigMap key becomes a file.
-==== Mounting generic files from ConfigMap
-
-The `--resource` supports mapping from `ConfigMap` and `Secret` kubernetes resources and materialize as files in the pod. There is a standard directory path materialized in the pod filesystem:
+==== Mounting generic files
-* `--resource configmap:` materialized in `/etc/camel/resources.d/_configmaps/<configmap name>/<key name>`
-* `--resource secret:` materialized in `/etc/camel/resources.d/_secrets/<secret name>/<key name>`
+Use `--resource` to mount files without property placeholder configuration. Syntax: `[configmap|secret]:name[/key][@path]`:
-NOTE: The `--resource` parameter doesn't set the `camel.component.properties.location=<path>` as the `--config`.
-
-The `--resource` syntax is `[configmap|secret]:name[/key][@path]`, the `key` and `@path` are optionals. The `@path` allows you to override the materialized file path in the pod filesystem.
-
-Given the following command:
[source,bash]
----
-camel kubernetes run route.java --resource configmap:multiple-config
+camel kubernetes run route.java --resource configmap:my-data
+camel kubernetes run route.java --resource configmap:my-data/config.xml@/etc/my-config.xml
----
-It will materialize the files, similar to `--config`:
-[source,bash]
-----
-/etc/camel/resources.d/_configmaps/multiple-config/game.properties
-/etc/camel/resources.d/_configmaps/multiple-config/ui.properties
-----
-
-Given the following command:
-
-[source,bash]
-----
-camel kubernetes run route.java --resource configmap:multiple-config/ui.properties@/etc/my-file.txt
-----
-
-It will materialize the `/etc/my-file.txt` in the pod filesystem whose content is the `ui.properties` key of the `configmap:multiple-config`.
-[source,bash]
-----
-cat /etc/my-file.txt
-----
-[source,bash]
-----
-color.good=purple
-color.bad=yellow
-allow.textmode=true
-how.nice.to.look=fairlyNice
-my-key=property from ui.properties
-----
+Mount paths: `/etc/camel/resources.d/_configmaps/<name>/<key>` (or `_secrets`). Use `@path` to override the destination.
== Show logs
-To inspect the log output of a running deployment call:
+Stream log output from a running deployment:
[source,bash]
----
camel kubernetes logs --name=route
----
-The command connects to the running integration Pod on the cluster and streams the log output.
-Just terminate the process to stop printing the logs.
-
-The `--name` option should point to a previously exported project (either via `run` or `export` command).
-
== Delete deployments
-Of course, you may also delete a deployment from the cluster.
+Remove a deployment and all its resources:
[source,bash]
----
camel kubernetes delete --name=route
+camel kubernetes delete --name=route --cluster-type=openshift
----
-Use the `--name` option to select a previously exported project (either via `run` or `export` command).
-The delete operation will remove all resources defined in the Kubernetes manifest.
+NOTE: If you used `--cluster-type` during export/run, you must specify it for delete as well.
+
+== Minikube deployment tips
-If you used the `--cluster-type` option to create your project (either via `run` or `export` command) you will need to use it as well for the delete operation.
+Quick start for local development with Minikube (Camel 4.10+):
[source,bash]
----
-camel kubernetes delete --name=route --cluster-type=openshift
+minikube start --addons registry --driver=docker
+eval $(minikube -p minikube docker-env)
+camel kubernetes run demo.camel.yaml --cluster-type=minikube \
+ --build-property=quarkus.kubernetes.image-pull-policy=Never \
+ --image-registry "$(kubectl -n kube-system get service registry -o jsonpath='{.spec.clusterIP}')" \
+ --image-builder=docker
----
-== Minikube deployment tips and troubleshooting
-
-To run a local Kubernetes cluster with Minikube for development purposes.
-Here are some tips from users that have been using this.
-
-The following steps have been known to be working with Camel 4.8.1+:
-
-1. `minikube start --addons registry --driver=docker`
-2. `eval $(minikube -p minikube docker-env)`
-3. `camel kubernetes run demo.camel.yaml --cluster-type=minikube --build-property=quarkus.kubernetes.image-pull-policy=Never`
-
-Most important `--build-property=quarkus.kubernetes.image-pull-policy=Never` without that it is not working, which is not clear from the current Minikube docs.
-
-The following steps have been known to be working with Camel 4.9+:
-
-1. `minikube start --addons registry --driver=docker`
-2. `eval $(minikube -p minikube docker-env)`
-3. `camel kubernetes run demo.camel.yaml --cluster-type=minikube --build-property=quarkus.kubernetes.image-pull-policy=Never --trait container.image-push=true --image-registry '$(kubectl -n kube-system get service registry -o jsonpath='{.spec.clusterIP}')' --image-builder=docker`
-
-The following steps have been known to be working with Camel 4.10+:
-
-1. `minikube start --addons registry --driver=docker`
-2. `eval $(minikube -p minikube docker-env)`
-3. `camel kubernetes run demo.camel.yaml --cluster-type=minikube --build-property=quarkus.kubernetes.image-pull-policy=Never --image-registry "$(kubectl -n kube-system get service registry -o jsonpath='{.spec.clusterIP}')" --image-builder=docker`
+IMPORTANT: The `--build-property=quarkus.kubernetes.image-pull-policy=Never` flag is required for Minikube deployments.
-Note that Docker multi-platform build is used. It requires to have followed these https://docs.docker.com/build/building/multi-platform/#build-multi-platform-images[Docker requirements].
+NOTE: Docker multi-platform build is used. Follow the https://docs.docker.com/build/building/multi-platform/#build-multi-platform-images[Docker multi-platform requirements].
diff --git a/docs/user-manual/modules/ROOT/pages/camel-jbang-launcher.adoc b/docs/user-manual/modules/ROOT/pages/camel-jbang-launcher.adoc
index d2700d011e4f..05de148c52c0 100644
--- a/docs/user-manual/modules/ROOT/pages/camel-jbang-launcher.adoc
+++ b/docs/user-manual/modules/ROOT/pages/camel-jbang-launcher.adoc
@@ -2,25 +2,12 @@
*Available as of Camel 4.13*
-This module provides a self-contained executable JAR that includes all dependencies required to run Camel CLI without the need for the JBang two-step process.
+A self-contained executable JAR for running Camel CLI without JBang. Uses Spring Boot's nested JAR loader for fast startup and isolated classpath.
-The launcher uses Spring Boot's loader tools to create a self-executing JAR with a nested structure, similar to Spring Boot's executable JARs. This provides better performance and avoids classpath conflicts compared to traditional fat JARs.
-
-== Downloading
-
-You can download the `camel-launcher` JAR from https://repo1.maven.org/maven2/org/apache/camel/camel-launcher/[Maven Central].
+Download from https://repo1.maven.org/maven2/org/apache/camel/camel-launcher/[Maven Central].
== Using the fat-jar directly
-Then you can run the JAR using standard Java as follows:
-
-[source,bash]
-----
-java -jar camel-launcher-<version>.jar [command] [options]
-----
-
-For example:
-
[source,bash]
----
java -jar camel-launcher-<version>.jar version
@@ -49,29 +36,17 @@ And then use the provided scripts:
bin\camel.bat [command] [options]
----
-== Benefits of using Camel Launcher
+== Benefits
-- No need for JBang installation
-- Single executable JAR with all dependencies included
-- Faster startup time (no dependency resolution step, on-demand class loading)
-- Better memory usage (only loads classes that are actually used)
-- Avoids classpath conflicts (dependencies kept as separate JARs)
-- Each self-executing JAR is its own release, avoiding version complexity
-- Can still be used with JBang if preferred
-- Locked to use pinned version of Camel which is the same version as the launcher; to upgrade, then download and use a newer launcher.
+- No JBang installation required
+- Faster startup (no dependency resolution, on-demand class loading)
+- Lower memory usage (only loads classes actually used)
+- No classpath conflicts (dependencies kept as separate nested JARs)
+- Pinned Camel version — upgrade by downloading a newer launcher
== Limitations
-The following features are not supported when running from camel-launcher:
-
-=== --camel-version option
-
-The `--camel-version` option requires JBang to dynamically download and run a different Camel version.
-
-Alternatives:
-
-- Use a different camel-launcher JAR version
-- Install Camel CLI via JBang: `jbang app install camel@apache/camel`
+The `--camel-version` option is not supported — it requires JBang to dynamically download a different version. Use a different launcher JAR version instead, or install via JBang: `jbang app install camel@apache/camel`.
== More Information
diff --git a/docs/user-manual/modules/ROOT/pages/camel-jbang-managing.adoc b/docs/user-manual/modules/ROOT/pages/camel-jbang-managing.adoc
new file mode 100644
index 000000000000..fc2e3201ee40
--- /dev/null
+++ b/docs/user-manual/modules/ROOT/pages/camel-jbang-managing.adoc
@@ -0,0 +1,662 @@
+= Camel CLI - Managing Integrations
+
+Once your Camel integrations are running, the CLI provides comprehensive management and monitoring capabilities — from listing processes and tailing logs to tracing messages and checking health.
+
+TIP: Prefer a visual dashboard over individual commands?
+Just type `camel tui` — the plugin auto-installs on first use.
+It shows routes, messages, health, traces, and more in a single terminal view.
+See xref:camel-jbang-tui.adoc[Camel TUI] for details.
+
+== Controlling local Camel integrations
+
+List running integrations with `ps`:
+
+[source,bash]
+----
+camel ps
+ PID NAME READY STATUS AGE
+ 61818 sample.camel.MyCamelApplica... 1/1 Running 26m38s
+ 62506 dude 1/1 Running 4m34s
+----
+
+Stop by name or PID:
+
+[source,bash]
+----
+camel stop dude
+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]
+----
+camel stop
+Stopping running Camel integration (pid: 61818)
+Stopping running Camel integration (pid: 62506)
+----
+
+=== Watch mode
+
+Most management commands support `--watch` for continuous full-screen output:
+
+[source,bash]
+----
+camel ps --watch
+ PID NAME READY STATUS AGE
+ 61818 sample.camel.MyCamelApplica... 1/1 Running 26m38s
+ 62506 dude 1/1 Running 4m34s
+----
+
+== Controlling Spring Boot and Quarkus integrations
+
+By default, the CLI only manages integrations started with `camel run`.
+To manage Spring Boot or Quarkus applications, add the CLI connector dependency.
+
+Spring Boot:
+
+[source,xml]
+----
+<dependency>
+ <groupId>org.apache.camel.springboot</groupId>
+ <artifactId>camel-cli-connector-starter</artifactId>
+</dependency>
+----
+
+Quarkus:
+
+[source,xml]
+----
+<dependency>
+ <groupId>org.apache.camel.quarkus</groupId>
+ <artifactId>camel-quarkus-cli-connector</artifactId>
+</dependency>
+----
+
+== Running in background
+
+Use `--background` to run an integration as a background process (Camel Main only):
+
+[source,bash]
+----
+$ camel run chuck.yaml --background
+Running Camel integration: chuck in background with PID: 80093
+----
+
+Use `camel ps` to list, `camel log` to tail output, and `camel stop` to shut down.
+
+Since Camel 4.10, the command waits for startup to complete and reports any errors
+before returning. Disable with `--background-wait=false`.
+
+== Getting status
+
+The `camel get` command (equivalent to `camel get context`) shows overall status:
+
+[source,bash]
+----
+camel get
+ PID NAME CAMEL PLATFORM PROFILE READY STATUS RELOAD AGE ROUTE MSG/S TOTAL FAIL INFLIGHT LAST DELTA SINCE-LAST
+ 42240 cheese 4.12.0 JBang v0.126.0 dev 1/1 Running 0 1m8s 2/2 1.01 65 0 0 0 -1 1s/1s/-
+----
+
+The _Since Last_ column shows three time-since values: started/completed/failed.
+For example, `0s/0s/-` means the last started and completed message just happened with no failures yet.
+Use `--remote` to break down TOTAL into remote/total pairs.
+
+TIP: Use `camel get --watch` for continuous updates.
+
+== Route status
+
+See per-route statistics across all running integrations:
+
+[source,bash]
+----
+camel get route
+ PID NAME ID FROM STATUS AGE TOTAL FAILED INFLIGHT MEAN MIN MAX SINCE-LAST
+ 61818 MyCamel hello timer://hello?period=2000 Running 29m2s 870 0 0 0 0 14 0s/0s/-
+ 63051 dude java timer://java?period=1000 Running 46s 46 0 0 0 0 9 0s/0s/-
+----
+
+TIP: Run `camel get --help` to see all available sub-commands.
+
+== Top status
+
+The `camel top` command shows utilization statistics sorted by heap usage:
+
+[source,bash]
+----
+camel top
+ PID NAME JAVA CAMEL PLATFORM STATUS AGE HEAP NON-HEAP GC THREADS CLASSES
+ 22104 chuck 11.0.13 3.20.0 JBang Running 2m10s 131/322/4294 MB 70/73 MB 17ms (6) 7/8 7456/7456
+ 14242 MyCamel 11.0.13 3.20.0 Spring Boot v2.7.3 Running 33m40s 115/332/4294 MB 62/66 MB 37ms (6) 16/16 8428/8428
+ 22116 bar 11.0.13 3.20.0 JBang Running 2m7s 33/268/4294 MB 54/58 MB 20ms (4) 7/8 6104/6104
+----
+
+Columns: HEAP = used/committed/max, NON-HEAP = used/committed, GC = time (runs), CLASSES = loaded/total.
+
+Show routes sorted by slowest mean processing time with `camel top route`:
+
+[source,bash]
+----
+camel top route
+ PID NAME ID FROM STATUS AGE TOTAL FAILED INFLIGHT MEAN MIN MAX SINCE-LAST
+ 22104 chuck chuck-norris-source-1 timer://chuck?period=10000 Started 10s 1 0 0 163 163 163 9s
+ 22116 bar route1 timer://yaml2?period=1000 Started 7s 7 0 0 1 0 11 0s
+ 22104 chuck chuck kamelet://chuck-norris-source Started 10s 1 0 0 0 0 0 9s
+ 22104 chuck log-sink-2 kamelet://source?routeId=log-sink-2 Started 10s 1 0 0 0 0 0 9s
+ 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:
+
+[source,bash]
+----
+camel cmd stop-route chuck
+----
+
+Start them again:
+
+[source,bash]
+----
+camel cmd start-route chuck
+----
+
+Without a name, the command applies to all integrations: `camel cmd stop-route` / `camel cmd start-route`.
+
+Target a specific route with `--id`:
+
+[source,bash]
+----
+camel cmd start-route --id=route1
+----
+
+Scope to a specific integration by adding its name:
+
+[source,bash]
+----
+camel cmd start-route bar --id=route1
+----
+
+TIP: Separate multiple IDs with commas: `--id=route1,hello`.
+
+== Starting and stopping route groups
+
+*Available since Camel 4.14*
+
+View group status (aggregate of all routes in each group):
+
+[source,bash]
+----
+camel get group
+ PID NAME GROUP ROUTES STATUS AGE COVER MSG/S TOTAL FAIL INFLIGHT MEAN MIN MAX LAST DELTA SINCE-LAST
+ 53173 foo first 2 Started 8s 4/4 1.00 15 0 1 504 501 511 502 -3 0s/0s/-
+ 53173 foo second 3 Started 40s 7/7 0.00 8 0 0 2260 2256 2263 2263 +6 5s/2s/-
+----
+
+Stop a group:
+
+[source,bash]
+----
+camel cmd stop-group foo --id=first
+----
+
+Start it again:
+
+[source,bash]
+----
+camel cmd start-group foo --id=first
+----
+
+Group commands work the same way as route commands (see above).
+
+== Enabling and disabling EIPs
+
+*Available since Camel 4.14*
+
+Disable individual processors at runtime without changing source code.
+List processors with `camel get processor`, then disable by id:
+
+[source,bash]
+----
+camel cmd disable-processor --id=log1
+----
+
+Re-enable a specific processor or all at once:
+
+[source,bash]
+----
+camel cmd enable-processor --id=log1
+camel cmd enable-processor
+----
+
+TIP: Separate multiple IDs with commas: `--id=log1,log2,setBody2`.
+
+== Developer Console
+
+Enable the web-based developer console with `--console`:
+
+[source,bash]
+----
+camel run hello.java --console
+----
+
+The console is accessible at http://localhost:8080/q/dev and provides insights into routes,
+performance, and EIP-level metrics. It also supports JSON output for tooling:
+
+[source,bash]
+----
+curl -s -H "Accept: application/json" http://0.0.0.0:8080/q/dev/top/ | jq
+----
+
+== Message history
+
+*Available since Camel 4.17*
+
+The `camel get history` command shows a step-by-step summary of the last completed message
+— what each EIP did, with curated details at each step.
+
+Example route that reads a file, splits by line, filters, calls HTTP, and logs:
+
+[source,java]
+----
+import org.apache.camel.builder.RouteBuilder;
+
+public class foo extends RouteBuilder {
+
+ @Override
+ public void configure() throws Exception {
+ from("file:inbox?noop=true")
+ .log("Incoming file")
+ .split(body().tokenize("\n"))
+ .filter(body().contains("world"))
+ .log("Stop the world")
+ .stop()
+ .end()
+ .to("log:line")
+ .end()
+ .to("https://camel.apache.org/xxx?throwExceptionOnFailure=false")
+ .to("log:after-http")
+ .log("complete");
+ }
+}
+----
+
+With a 4-line input file (`hello`, `world`, `from`, `me`), the history shows:
+
+[source,bash]
+----
+$ camel get history --source
+Message History of last completed (id:32E020F6050C165-0000000000000000 status:success ago:4s pid:91133 name:foo)
+ ID PROCESSOR ELAPSED EXCHANGE
+ *--> foo.java:7 from[file://inbox?noop=true] 0 0000 File: foo.txt (19 bytes)
+ foo.java:8 log[Incoming file] 0 0000
+ foo.java:9 split[tokenize(body, \n)] 8 0000 Split (4)
+ foo.java:10 filter[{body contains world}] 0 0001/0000 Filter: false
+ foo.java:14 to[log:line] 0 0001/0000
+ foo.java:10 filter[{body contains world}] 0 0002/0000 Filter: true
+ foo.java:11 log[Stop the world] 0 0002/0000
+ foo.java:12 stop 0 0002/0000
+ foo.java:10 filter[{body contains world}] 0 0003/0000 Filter: false
+ foo.java:14 to[log:line] 0 0003/0000
+ foo.java:10 filter[{body contains world}] 0 0004/0000 Filter: false
+ foo.java:14 to[log:line] 0 0004/0000
+ foo.java:16 to[https:\/\/camel.apache.org\/xxx?throwExceptionO… 143 0000 404=Not Found Content-Type=text/html; charset=utf-8
+ foo.java:17 to[log:after-http] 1 0000
+ foo.java:18 log[complete] 0 0000
+ *<-- foo.java:7 from[file://inbox?noop=true] 157 0000 Success
+----
+
+Each split message gets its own exchange id linked to the parent. The HTTP call shows the 404 status and content type.
+
+=== Interactive mode
+
+Use `camel get history --it` for an interactive step-through view (similar to `camel debug`),
+showing full message details including headers and body. Press ENTER to advance, P+ENTER to go back.
+
+TIP: Run `camel get history --help` for all options.
+
+== Tailing logs
+
+Tail logs from one, several, or all integrations:
+
+NOTE: The `camel log` command is not supported in Spring Boot or Quarkus runtimes.
+
+[source,bash]
+----
+camel log chuck
+camel log bar,chuck
+camel log
+----
+
+Highlight keywords with `--find` (repeatable) or filter lines with `--grep` (case-insensitive):
+
+[source,bash]
+----
+camel log chuck --find=invoice --find=order
+camel log chuck --grep=error
+----
+
+By default, `log` tails continuously. Use `--follow=false` to output matching lines and exit.
+
+== Configuring logging levels
+
+View and change logging levels at runtime:
+
+[source,bash]
+----
+camel cmd logger
+camel cmd logger --logging-level=DEBUG foo
+----
+
+TIP: Use `--all` to change levels for all running integrations.
+
+=== Per-category logging
+
+*Available since Camel 4.6*
+
+Set category-specific levels from the CLI (repeatable):
+
+[source,bash]
+----
+$ camel run myapp.yaml --logging-category=org.apache.kafka=DEBUG --logging-category=com.foo.something=TRACE
+----
+
+Or in `application.properties` (both Camel/Spring Boot and Quarkus styles are supported):
+
+[source,properties]
+----
+
+# make it easy to configure individual logging levels
+logging.level.org.apache.kafka = DEBUG
+logging.level.com.foo.something = TRACE
+
+# you can also use quarkus style naming
+quarkus.log.category."org.apache.kafka".level = DEBUG
+quarkus.log.category."com.foo.something".level = TRACE
+----
+
+== Tracing messages
+
+The `camel trace` command shows every step a message takes through your routes.
+Exchange ids are colour-grouped for correlation when traces are interleaved.
+
+Check tracing status:
+
+[source,bash]
+----
+camel trace
+----
+
+TIP: Since Camel 4.8, tracing starts in standby mode (dev profile). Enable on startup
+with `camel.trace.enabled=true` in `application.properties`.
+
+Start, dump, and stop tracing:
+
+[source,bash]
+----
+camel trace --action=start
+camel trace --action=dump
+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:
+
+[source,bash]
+----
+camel get health
+ PID NAME AGE ID RL STATE RATE SINCE MESSAGE
+ 61005 mybind 8s camel/context R UP 2/2/- 1s/3s/-
+----
+
+The RATE column shows total/success/failure counts. SINCE shows time-since for each.
+When a check starts failing, e.g., `77/-/3` means 77 total, 0 consecutive successes, 3 consecutive failures.
+
+Use `--level=full` for consumer and route-level checks. Use `--trace` to show exception stack traces:
+
+[source,bash]
+----
+camel get health --trace
+ PID NAME AGE ID RL STATE RATE SINCE MESSAGE
+ 61038 mykafka 6m19s camel/context R UP 187/187/- 1s/6m16s/-
+ 61038 mykafka 6m19s camel/kafka-consumer-kafka-not-secure... R DOWN 187/-/187 1s/-/6m16s KafkaConsumer is not ready - Error: Invalid url in bootstrap.servers: value
+
+
+------------------------------------------------------------------------------------------------------------------------
+ STACK-TRACE
+------------------------------------------------------------------------------------------------------------------------
+ PID: 61038
+ NAME: mykafka
+ AGE: 6m19s
+ CHECK-ID: camel/kafka-consumer-kafka-not-secured-source-1
+ STATE: DOWN
+ RATE: 187
+ SINCE: 6m16s
+ METADATA:
+ bootstrap.servers = value
+ group.id = 7d8117be-41b4-4c81-b4df-cf26b928d38a
+ route.id = kafka-not-secured-source-1
+ topic = value
+ MESSAGE: KafkaConsumer is not ready - Error: Invalid url in bootstrap.servers: value
+ org.apache.kafka.common.KafkaException: Failed to construct kafka consumer
+ at org.apache.kafka.clients.consumer.KafkaConsumer.<init>(KafkaConsumer.java:823)
+ at org.apache.kafka.clients.consumer.KafkaConsumer.<init>(KafkaConsumer.java:664)
+ at org.apache.kafka.clients.consumer.KafkaConsumer.<init>(KafkaConsumer.java:645)
+ at org.apache.kafka.clients.consumer.KafkaConsumer.<init>(KafkaConsumer.java:625)
+ at org.apache.camel.component.kafka.DefaultKafkaClientFactory.getConsumer(DefaultKafkaClientFactory.java:34)
+ at org.apache.camel.component.kafka.KafkaFetchRecords.createConsumer(KafkaFetchRecords.java:241)
+ at org.apache.camel.component.kafka.KafkaFetchRecords.createConsumerTask(KafkaFetchRecords.java:201)
+ at org.apache.camel.support.task.ForegroundTask.run(ForegroundTask.java:123)
+ at org.apache.camel.component.kafka.KafkaFetchRecords.run(KafkaFetchRecords.java:125)
+ at java.base/java.util.concurrent.Executors$RunnableAdapter.call(Executors.java:515)
+ at java.base/java.util.concurrent.FutureTask.run(FutureTask.java:264)
+ at java.base/java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1128)
+ at java.base/java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:628)
+ at java.base/java.lang.Thread.run(Thread.java:829)
+ Caused by: org.apache.kafka.common.config.ConfigException: Invalid url in bootstrap.servers: value
+ at org.apache.kafka.clients.ClientUtils.parseAndValidateAddresses(ClientUtils.java:59)
+ at org.apache.kafka.clients.ClientUtils.parseAndValidateAddresses(ClientUtils.java:48)
+ at org.apache.kafka.clients.consumer.KafkaConsumer.<init>(KafkaConsumer.java:730)
+ ... 13 more
+----
+
+TIP: Run `camel get health --help` for all options.
+
+== Listing services
+
+List hosted services (REST, TCP, etc.) across all running integrations:
+
+[source,bash]
+----
+camel get service
+ PID NAME COMPONENT PROTOCOL SERVICE
+ 1912 netty netty tcp tcp:localhost:4444
+ 2023 greetings platform-http rest http://0.0.0.0:7777/camel/greetings/{name} (GET)
+ 2023 greetings platform-http http http://0.0.0.0:7777/q/dev
+----
+
+NOTE: Components must advertise services via the xref:camel-console.adoc[Developer Console] to appear here.
+
+== Observability with metrics
+
+Enable Micrometer metrics with `--observe` or configure in `application.properties`:
+
+[source,properties]
+----
+# enable HTTP management server with metrics
+camel.management.enabled=true
+camel.management.metricsEnabled=true
+
+# turn on micrometer metrics
+camel.metrics.enabled=true
+# include more camel details
+camel.metrics.enableMessageHistory=true
+# include additional out-of-the-box micrometer metrics for cpu, jvm and used file descriptors
+camel.metrics.binders=processor,jvm-info,file-descriptor
+----
+
+Access metrics at http://localhost:8080/observe/metrics or from the CLI:
+
+[source,bash]
+----
+$ camel get metric
+ PID NAME TYPE METRIC ROUTE VALUE MEAN MAX TOTAL
+ 11562 MyCoolCamel timer camel.exchange.event.notifier 3 12 27 35
+ 11562 MyCoolCamel timer camel.exchange.event.notifier 3 1 2 3
+ 11562 MyCoolCamel gauge camel.routes.added 3
+ 11562 MyCoolCamel gauge camel.routes.running 3
+ 11562 MyCoolCamel gauge jvm.info 1
+ 11562 MyCoolCamel gauge process.cpu.usage 0.0045185067010171795
+ 11562 MyCoolCamel gauge process.files.max 10240
+ 11562 MyCoolCamel gauge process.files.open 288
+ 11562 MyCoolCamel gauge system.cpu.count 8
+ 11562 MyCoolCamel gauge system.cpu.usage 0.15222772277227722
+ 11562 MyCoolCamel gauge system.load.average.1m 3.58935546875
+----
+
+== Circuit breaker status
+
+View the state of xref:components:eips:circuitBreaker-eip.adoc[Circuit Breakers]:
+
+[source,bash]
+----
+camel get circuit-breaker
+ PID NAME COMPONENT ROUTE ID STATE PENDING SUCCESS FAIL REJECT
+ 56033 mycb resilience4j route1 circuitBreaker1 HALF_OPEN 5 2 3 0
+----
+
+TIP: Use `camel get circuit-breaker --watch` for continuous updates.
+
+== Using Jolokia and Hawtio
+
+https://hawt.io/[Hawtio] provides a web console for inspecting Camel integrations via JMX,
+including route visualization with live performance metrics.
+
+Attach the Jolokia JVM agent to a running integration (by PID or name):
+
+[source,bash]
+----
+camel jolokia 62506
+Started Jolokia for PID 62506
+http://127.0.0.1:8778/jolokia/
+----
+
+Then launch Hawtio (automatically downloads and opens in browser):
+
+[source,bash]
+----
+camel hawtio
+----
+
+In Hawtio, click the _Discover_ tab to see all local Jolokia agents,
+then click the green _lightning_ icon to connect.
+
+Or do it in one command — attach Jolokia and launch Hawtio together:
+
+[source,bash]
+----
+camel hawtio dude
+----
+
+Uninstall Jolokia when done:
+
+[source,bash]
+----
+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
+* xref:camel-jbang-test.adoc[Camel Testing Plugin] — write and run automated tests with Citrus
diff --git a/docs/user-manual/modules/ROOT/pages/camel-jbang-mcp.adoc b/docs/user-manual/modules/ROOT/pages/camel-jbang-mcp.adoc
index 48f046cd644f..74a885006a48 100644
--- a/docs/user-manual/modules/ROOT/pages/camel-jbang-mcp.adoc
+++ b/docs/user-manual/modules/ROOT/pages/camel-jbang-mcp.adoc
@@ -1,41 +1,26 @@
= Camel MCP Server
-The Camel MCP Server exposes the Apache Camel Catalog and a set of specialized tools through the
-https://modelcontextprotocol.io/[Model Context Protocol (MCP)], the open standard that allows AI coding assistants
-to call external tools. This enables AI tools such as Claude Code, OpenAI Codex, GitHub Copilot, and JetBrains AI
-to query live Camel catalog data, validate endpoint URIs, analyze routes for security concerns, browse Kamelets, and more.
+The Camel MCP Server exposes the Apache Camel Catalog and runtime introspection tools through the
+https://modelcontextprotocol.io/[Model Context Protocol (MCP)]. AI coding assistants (Claude Code, OpenAI Codex,
+GitHub Copilot, JetBrains AI) can query catalog data, validate endpoints, analyze routes, and inspect running applications.
-The server is built on https://quarkus.io/[Quarkus] using the
-https://docs.quarkiverse.io/quarkus-mcp-server/dev/index.html[quarkus-mcp-server] extension and ships as a single
-uber-JAR that can be launched via https://www.jbang.dev/[JBang].
+Built on https://quarkus.io/[Quarkus] with the https://docs.quarkiverse.io/quarkus-mcp-server/dev/index.html[quarkus-mcp-server] extension, launched via https://www.jbang.dev/[JBang].
NOTE: This module is in *Preview* status as of Camel 4.18.
== Transport
-The server supports two transports:
+* **STDIO** (default) -- communicates over stdin/stdout. Logging goes to stderr.
+* **HTTP/SSE** -- for web-based clients and remote/shared access. Enable with `quarkus.http.host-enabled=true`.
+ Supports two variants: SSE (`/mcp/sse`, protocol `2024-11-05`) and Streamable HTTP (`/mcp`, protocol `2025-03-26`, recommended for new integrations).
-* **STDIO** -- The default transport for CLI-based AI tools. The server communicates over stdin/stdout using the MCP
- protocol. All logging goes to stderr to keep stdout clean for protocol messages.
-* **HTTP/SSE** -- An optional transport for web-based clients and remote access scenarios. Useful when running the
- MCP server as a shared service for a team or in a container. Two protocol variants are supported:
-** *SSE* (protocol version `2024-11-05`) -- The legacy HTTP/SSE transport. The client opens a Server-Sent Events
- stream at `/mcp/sse` and receives a message endpoint URL. All subsequent JSON-RPC requests are POSTed to that
- endpoint, and responses are delivered through the SSE stream.
-** *Streamable HTTP* (protocol version `2025-03-26`) -- The newer single-endpoint transport. All JSON-RPC messages
- are POSTed to `/mcp` and responses are returned inline in the HTTP response body. This is simpler to use and
- is the recommended variant for new integrations.
-
-By default, the HTTP server is disabled. To enable it, set `quarkus.http.host-enabled=true`.
-
-IMPORTANT: The MCP server does **not** expose REST endpoints. You cannot query tools or resources with plain HTTP GET
-requests (e.g., `curl http://localhost:8080/mcp/tools` will return a 404). All communication uses JSON-RPC messages
-over the MCP protocol.
+IMPORTANT: The MCP server does **not** expose REST endpoints — all communication uses JSON-RPC over the MCP protocol.
== Available Tools
-The server exposes 30 catalog tools organized into twelve functional areas, 21 runtime introspection tools for
-inspecting and interacting with live Camel processes, plus 3 prompts that provide structured multi-step workflows.
+The server exposes catalog tools for exploring components, validating routes, and assisting with migration,
+runtime introspection tools for inspecting and interacting with live Camel processes,
+plus prompts that provide structured multi-step workflows.
=== Catalog Exploration
@@ -75,6 +60,10 @@ inspecting and interacting with live Camel processes, plus 3 prompts that provid
| `camel_catalog_eip_doc`
| Get detailed documentation for a specific EIP including all its options.
+
+| `camel_component_properties`
+| List valid configuration property keys for a Camel component in `camel.component.<scheme>.<name>` form,
+ including option name, type, default value, and description.
|===
=== Kamelet Catalog
@@ -193,6 +182,26 @@ inspecting and interacting with live Camel processes, plus 3 prompts that provid
| `camel_transform_route`
| Assists with route DSL format transformation between YAML and XML.
+
+| `camel_configuration_validate`
+| Validate Camel configuration property lines (e.g., from `application.properties`). Detects misspelled option
+ names, invalid values, and returns suggestions.
+
+| `camel_properties_translate`
+| Translate Camel configuration properties between runtimes (`main`, `spring-boot`, `quarkus`). Handles
+ runtime-specific keys like HTTP server and management endpoint configuration.
+|===
+
+=== Route Diagram
+
+[cols="1,3",options="header"]
+|===
+| Tool | Description
+
+| `camel_render_route_diagram`
+| Generate a diagram of Camel routes from a source file (YAML, XML, Java). Supports image themes (dark, light,
+ transparent) written as PNG, and text themes (ascii, unicode) returned directly. Useful for visualizing route
+ structure for review, documentation, or troubleshooting.
|===
=== OpenAPI Contract-First
@@ -305,6 +314,10 @@ process is running).
| `camel_runtime_route_control`
| Control a route: start, stop, suspend, or resume it by route ID.
+
+| `camel_runtime_route_topology`
+| Get the inter-route topology showing how routes connect to each other and to external endpoints.
+ Returns nodes and edges describing the route graph.
|===
==== Observability
@@ -330,6 +343,17 @@ process is running).
| `camel_runtime_memory`
| Show JVM memory usage (heap/non-heap), garbage collection stats, and thread counts.
+
+| `camel_runtime_errors`
+| Get captured routing errors from the running application. Returns error details including exception,
+ exchange context, and route information.
+
+| `camel_runtime_history`
+| Get the message history trace of the last completed exchange. Shows the route path, processors visited,
+ headers, body, and timing.
+
+| `camel_runtime_thread_dump`
+| Get a JVM thread dump showing thread names, states, and stack traces.
|===
==== Configuration and Registry
@@ -368,6 +392,14 @@ process is running).
| `camel_runtime_browse`
| Browse messages in a Camel endpoint (e.g., messages queued in a SEDA endpoint).
+
+| `camel_runtime_receive`
+| Receive (poll) a message from a Camel endpoint in the running application. Consumes one message
+ from the endpoint.
+
+| `camel_runtime_stop`
+| Initiate graceful shutdown of a running Camel application. Finishes processing in-flight exchanges
+ before stopping.
|===
== Available Prompts
@@ -406,15 +438,9 @@ instructions and executes each step by calling the referenced tools.
== Setup
-The MCP server requires https://www.jbang.dev/[JBang] to be installed and available on your PATH.
+The MCP server requires https://www.jbang.dev/[JBang] installed and on your PATH.
-=== Claude Code
-
-==== Install as a plugin (recommended)
-
-Claude Code can install the Camel MCP server from the marketplace defined in the `apache/camel`
-repository, so you do not have to edit any configuration file by hand. JBang must still be installed
-and available on your PATH.
+=== Claude Code (plugin install, recommended)
[source,bash]
----
@@ -422,71 +448,19 @@ claude plugin marketplace add apache/camel
claude plugin install camel-mcp@camel-marketplace
----
-The first command registers the marketplace; the second installs the `camel-mcp` plugin, which ships
-the MCP server configuration. The server is launched on demand over STDIO via JBang.
-
-==== Manual configuration
+=== Manual configuration (all AI tools)
-Alternatively, add the following to your project's `.mcp.json` (or `~/.claude/mcp.json` for global
-configuration):
-
-[source,json]
-----
-{
- "mcpServers": {
- "camel": {
- "command": "jbang",
- "args": [
- "-Dquarkus.log.level=WARN",
- "org.apache.camel:camel-jbang-mcp:LATEST:runner"
- ]
- }
- }
-}
-----
-
-=== OpenAI Codex
-
-Add the server to your MCP configuration:
-
-[source,json]
-----
-{
- "mcpServers": {
- "camel": {
- "command": "jbang",
- "args": [
- "-Dquarkus.log.level=WARN",
- "org.apache.camel:camel-jbang-mcp:LATEST:runner"
- ]
- }
- }
-}
-----
-
-=== VS Code with Copilot
-
-Configure MCP servers in your `.vscode/mcp.json` or in the user settings:
-
-[source,json]
-----
-{
- "servers": {
- "camel": {
- "command": "jbang",
- "args": [
- "-Dquarkus.log.level=WARN",
- "org.apache.camel:camel-jbang-mcp:LATEST:runner"
- ]
- }
- }
-}
-----
+Add the server to your MCP configuration file. The JSON is the same for all tools — only the file location differs:
-=== JetBrains IDEs
+[cols="1,2",options="header"]
+|===
+| Tool | Configuration file
-JetBrains IDEs support MCP servers starting from 2025.1. Configure them in
-Settings > Tools > AI Assistant > MCP Servers, or create an `.junie/mcp.json` file in your project root:
+| Claude Code | `.mcp.json` (project) or `~/.claude/mcp.json` (global)
+| OpenAI Codex | MCP configuration file
+| VS Code / Copilot | `.vscode/mcp.json` (use `"servers"` instead of `"mcpServers"` as the top-level key)
+| JetBrains IDEs (2025.1+) | Settings > Tools > AI Assistant > MCP Servers, or `.junie/mcp.json`
+|===
[source,json]
----
@@ -503,522 +477,111 @@ Settings > Tools > AI Assistant > MCP Servers, or create an `.junie/mcp.json` fi
}
----
-=== Generic STDIO Client
+NOTE: For VS Code, the top-level key is `"servers"` instead of `"mcpServers"`.
-Any MCP client that supports the STDIO transport can launch the server directly:
+=== Generic STDIO or HTTP/SSE
[source,bash]
----
+# STDIO (any MCP client)
jbang org.apache.camel:camel-jbang-mcp:LATEST:runner
-----
-
-=== HTTP/SSE Transport
-
-To start the server with the HTTP/SSE transport enabled:
-[source,bash]
-----
+# HTTP/SSE transport
jbang -Dquarkus.http.host-enabled=true -Dquarkus.http.port=8080 org.apache.camel:camel-jbang-mcp:LATEST:runner
----
-If you have built Camel locally, you can also run the uber-JAR directly:
-
-[source,bash]
-----
-java -Dquarkus.http.host-enabled=true -Dquarkus.http.port=8080 -jar dsl/camel-jbang/camel-jbang-mcp/target/camel-jbang-mcp-4.21.0-SNAPSHOT-runner.jar
-----
-
-The server exposes two HTTP endpoints, corresponding to the two MCP protocol variants:
+HTTP endpoints: `/mcp/sse` (SSE, legacy) and `/mcp` (Streamable HTTP, recommended).
-[cols="1,2,3",options="header"]
-|===
-| Endpoint | Protocol Version | Description
-
-| `/mcp/sse`
-| `2024-11-05` (SSE)
-| Legacy HTTP/SSE transport. The client opens an SSE stream at this URL to receive responses and a message
- endpoint URL. JSON-RPC requests are POSTed to the message endpoint. Most existing MCP clients support this
- variant.
-
-| `/mcp`
-| `2025-03-26` (Streamable HTTP)
-| Newer single-endpoint transport. JSON-RPC requests are POSTed directly to this URL and responses are returned
- inline in the HTTP response body. Simpler to use and recommended for new integrations.
-|===
+=== Inspecting with MCP Inspector
-==== Inspecting the MCP Server
-
-To explore what the Camel MCP server exposes (tools, resources, and prompts), you can use the
-https://github.com/modelcontextprotocol/inspector[MCP Inspector]. This is a web-based UI that connects to any
-MCP server and lets you browse and invoke its capabilities interactively.
-
-Start the Camel MCP server with HTTP enabled as shown above, then run the MCP Inspector:
+Start the server with HTTP enabled, then:
[source,bash]
----
npx @modelcontextprotocol/inspector
----
-Open the Inspector UI at http://localhost:6274/ and configure the connection:
-
-* **Transport Type**: `SSE`
-* **URL**: `http://localhost:8080/mcp/sse`
-* **Connection**: `Via Proxy`
-
-Once connected, you can navigate the available MCP Tools, Resources, and Prompts exposed by the server.
-This is useful for understanding what data the server provides and for testing tool invocations
-before integrating with an AI coding assistant.
+Open http://localhost:6274/, set Transport Type to `SSE`, URL to `http://localhost:8080/mcp/sse`, Connection to `Via Proxy`.
-== Getting Started
+== Examples
-This walkthrough demonstrates the full AI-assisted Camel workflow: use the catalog tools to build a route,
-launch it with `camel run`, then use the runtime tools to inspect and interact with the live application.
-The same MCP server provides both catalog and runtime capabilities.
+Here are example prompts you can give your AI assistant. The assistant automatically selects the right MCP tools.
-=== Prerequisites
+=== Catalog exploration
-* https://www.jbang.dev/[JBang] installed and on your PATH
-* manual/camel-jbang.html[Camel CLI] installed (`jbang app install camel@apache/camel`)
-* An MCP-capable AI tool (Claude Code, VS Code with Copilot, JetBrains AI, etc.) configured as shown in the <<Setup>> section above
+* _"List all Camel components in the messaging category"_ — uses `camel_catalog_components`
+* _"Show me the Kafka component documentation with all options"_ — uses `camel_catalog_component_doc`
+* _"Show me all AWS source kamelets"_ — uses `camel_catalog_kamelets`
+* _"What options does aws-s3-source accept?"_ — uses `camel_catalog_kamelet_doc`
+* _"Show me beginner REST examples"_ — uses `camel_catalog_examples`
-=== Step 1: Ask the AI to build a route
+=== Building routes
-Start by asking your AI assistant to create a Camel route. The assistant uses the catalog tools to discover
-components, look up their documentation, build the route, and validate it:
+Ask the assistant to build a route from requirements:
----
Build me a Camel route that generates a message every 5 seconds with a random number,
logs it, and sends it to a SEDA queue called "numbers".
----
-The assistant uses `camel_catalog_component_doc` to look up the `timer`, `log`, and `seda` component options,
-builds a YAML route, and validates it with `camel_validate_yaml_dsl`. You can also use the
-`camel_build_integration` prompt for a more structured multi-step workflow.
-
-The result is a route file, for example `random-numbers.yaml`:
-
-[source,yaml]
-----
-- route:
- from:
- uri: timer:generate?period=5000
- steps:
- - setBody:
- simple: "${random(1000)}"
- - log: "Generated number: ${body}"
- - to: seda:numbers
-----
-
-=== Step 2: Launch the route
-
-In AI tools that can execute shell commands (such as Claude Code), ask the assistant to launch the route:
-
-----
-Run this route with camel run
-----
-
-The assistant runs `camel run random-numbers.yaml` in the background. Alternatively, open a separate terminal
-and run it yourself:
-
-[source,bash]
-----
-camel run random-numbers.yaml
-----
-
-=== Step 3: Inspect the running application
-
-Once the route is running, use the runtime tools to inspect it:
-
-----
-Show me the running Camel processes and their route statistics
-----
-
-The assistant calls `camel_runtime_processes` to discover the running application, then `camel_runtime_routes`
-to show route state, message counts, and throughput. You can drill deeper:
-
-----
-Are there any health issues? What do the endpoints look like?
-----
-
-The assistant calls `camel_runtime_health` and `camel_runtime_endpoints` to provide a full picture of the
-live application.
-
-=== Step 4: Interact with the running application
-
-Try sending a test message or enabling tracing:
-
-----
-Enable message tracing so I can see the exchange flow, wait a few seconds,
-then show me the traced messages.
-----
-
-The assistant calls `camel_runtime_trace` with `action=enable`, waits, then calls it again with `action=dump`
-to show the message path through the route processors.
-
-----
-Browse the messages queued in the seda:numbers endpoint
-----
-
-The assistant calls `camel_runtime_browse` with `endpoint=seda:numbers` to show pending messages.
-
-=== Step 5: Debug and iterate
-
-If something goes wrong, combine catalog and runtime tools:
-
-----
-The route is showing errors. Diagnose the issue and suggest a fix.
-----
-
-The assistant calls `camel_runtime_health` and checks error details from `camel_runtime_routes`, then uses
-`camel_error_diagnose` (a catalog tool) to analyze the error and suggest fixes — all in one conversation.
-
-== Examples
-
-=== Listing Components
-
-Prompt your AI assistant with:
-
-----
-List all Camel components in the messaging category
-----
-
-The assistant calls `camel_catalog_components` with `label=messaging` and receives structured results with name,
-title, description, label, deprecation status, and support level for each matching component.
-
-=== Getting Component Documentation
-
-----
-Show me the documentation for the Kafka component, including all endpoint options
-----
-
-The assistant calls `camel_catalog_component_doc` with `component=kafka` and receives the full component model
-including the URI syntax, Maven coordinates, and every endpoint option with types, defaults, and descriptions.
-
-=== Browsing Kamelets
-
-----
-Show me all available source kamelets related to AWS
-----
-
-The assistant calls `camel_catalog_kamelets` with `type=source` and `filter=aws` and returns matching Kamelets
-with their name, type, support level, and description.
-
-To drill into a specific Kamelet:
-
-----
-What options does the aws-s3-source kamelet accept?
-----
-
-The assistant calls `camel_catalog_kamelet_doc` with `kamelet=aws-s3-source` and returns the complete property
-list including required fields, types, defaults, and Maven dependencies.
+The assistant discovers components, looks up documentation, builds a YAML route, and validates it with `camel_validate_yaml_dsl`. Use the `camel_build_integration` prompt for a structured multi-step workflow.
-=== Browsing Examples
+=== Validation
-----
-Show me beginner-level Camel examples related to REST
-----
-
-The assistant calls `camel_catalog_examples` with `filter=rest` and `level=beginner` and returns matching examples
-with their name, title, description, difficulty level, tags, and file list.
+* _"Validate this endpoint: `kafka:myTopic?brkers=localhost:9092`"_ — detects the typo and suggests `brokers`
+* _"Validate this YAML route"_ — checks against the YAML DSL JSON schema, reports invalid elements
-To read a specific file from an example:
+=== Understanding, security, and testing
-----
-Show me the route file from the rest-api example
-----
+* _"Explain what this route does"_ — uses `camel_route_context` for catalog-enriched analysis
+* _"Analyze this route for security concerns"_ — uses `camel_route_harden_context` to detect hardcoded credentials, plain-text protocols, etc.
+* _"Generate a JUnit 5 test for this route"_ — uses `camel_route_test_scaffold` to produce test class with mock endpoints and test-infra stubs
-The assistant calls `camel_catalog_example_file` with `example=rest-api` and `file=route.camel.yaml` and returns
-the file content directly for bundled examples, or a GitHub URL for non-bundled ones.
+=== Error diagnosis
-=== Validating an Endpoint URI
+Paste a stack trace:
----
-Validate this Kafka endpoint: kafka:myTopic?brkers=localhost:9092&groupId=myGroup
-----
-
-The assistant calls `camel_validate_route` and detects the typo (`brkers`), reports the URI as invalid, and
-suggests the correct option name (`brokers`).
-
-=== Validating YAML DSL Structure
-
-----
-Validate this YAML route definition for me:
-
-- route:
- from:
- uri: timer:yaml
- steps:
- - setCheese:
- simple: Hello Camel
- - log: ${body}
-----
-
-The assistant calls `camel_validate_yaml_dsl` which validates the route against the Camel YAML DSL JSON schema
-and reports that `setCheese` is not a valid DSL element, returning the instance path and error type so the AI
-can suggest the correct processor name (e.g., `setBody`).
-
-=== Understanding a Route
-
-Paste a route and ask:
-
-----
-Explain what this route does
-----
-
-The assistant calls `camel_route_context` which extracts all components and EIPs used in the route, looks up
-their documentation from the catalog, and returns enriched context so the AI can provide an accurate explanation.
-
-=== Security Hardening
-
-----
-Analyze this route for security concerns and suggest hardening measures
-----
-
-The assistant calls `camel_route_harden_context` which analyzes the route for security-sensitive components,
-detects issues (hardcoded credentials, HTTP instead of HTTPS, plain FTP, etc.), assigns risk levels, and
-returns structured findings with remediation recommendations.
-
-=== Diagnosing an Error
-
-Paste a stack trace or error message and ask:
-
-----
-I'm getting this error when starting my Camel route. What's wrong?
-
org.apache.camel.FailedToCreateRouteException: Failed to create route route1 at: >>> To[kafka:myTopic] <<<
-Caused by: org.apache.camel.ResolveEndpointFailedException: Failed to resolve endpoint: kafka:myTopic
Caused by: org.apache.camel.NoSuchEndpointException: No endpoint could be found for: kafka:myTopic
----
-The assistant calls `camel_error_diagnose` which identifies all three exceptions in the chain, extracts the
-`kafka` component, and returns common causes (missing `camel-kafka` dependency, typo in URI scheme), suggested
-fixes (add the dependency, verify the URI), and links to the relevant Camel documentation.
-
-=== Generating a Test Skeleton
-
-----
-Generate a JUnit 5 test for this route:
-
-- route:
- from:
- uri: kafka:orders
- steps:
- - marshal:
- json: {}
- - to: mongodb:myDb?collection=orders&operation=insert
-----
-
-The assistant calls `camel_route_test_scaffold` with the route content. It detects the `kafka` and `mongodb`
-components, generates a test class extending `CamelTestSupport` with `@RegisterExtension` stubs for both
-`KafkaService` and `MongoDBService`, replaces the `mongodb` producer with a mock endpoint, and returns the
-generated test code along with the required Maven test dependencies (`camel-test-junit5`, `camel-mock`,
-`camel-test-infra-kafka`, `camel-test-infra-mongodb`).
-
-For Spring Boot projects, specify the runtime:
-
-----
-Generate a Spring Boot test for this Kafka-to-MongoDB route
-----
-
-The tool generates a test class annotated with `@CamelSpringBootTest` and `@SpringBootTest`, with
-`CamelContext` and `ProducerTemplate` injected via `@Autowired`.
-
-=== Checking Dependency Hygiene
-
-----
-Here's my pom.xml and my main route. Can you check if I'm missing any dependencies
-or if anything is outdated?
-----
-
-Provide your `pom.xml` and route content, and the assistant calls `camel_dependency_check`. It detects whether
-your Camel version is outdated compared to the latest release, identifies components used in the route that are
-missing from the pom (e.g., `camel-kafka` for `kafka:` endpoints), and flags version conflicts where a
-dependency has an explicit version override while a BOM is present. Each issue comes with a corrected Maven
-snippet you can paste directly into your pom.
-
-=== Checking Camel Versions
-
-----
-What are the latest LTS versions of Camel for Spring Boot?
-----
-
-The assistant calls `camel_version_list` with `runtime=spring-boot` and `lts=true` and returns version
-information including release dates, end-of-life dates, and JDK requirements.
-
-=== Migrating a Camel Project
-
-Start by providing your project's `pom.xml`:
-
-----
-I want to migrate my Camel project to the latest version. Here's my pom.xml.
-----
-
-The assistant calls `camel_migration_analyze` to detect the runtime, current Camel version, Java version, and
-component dependencies. It then calls `camel_migration_compatibility` to check for breaking changes and
-`camel_migration_recipes` to provide the OpenRewrite commands for automated migration.
-
-=== Searching Migration Guides
-
-----
-What changed with the direct-vm component in Camel 4?
-----
-
-The assistant calls `camel_migration_guide_search` with `query=direct-vm` and returns matching snippets from the
-official migration guides with version info and URLs, so you can see exactly what changed and how to adapt.
-
-=== Migrating from WildFly or Karaf
-
-----
-I have a Camel application running on WildFly and I want to migrate it to Quarkus. Here's my pom.xml.
-----
-
-The assistant calls `camel_migration_wildfly_karaf` which returns the Maven archetype command to create a new
-Quarkus-based project, migration steps, and relevant guide URLs. The archetype generates the correct project
-structure so you can then migrate your routes and source files into it.
-
-=== Validating an OpenAPI Spec for Camel
-
-----
-I have this OpenAPI spec for my Pet Store API. Can you validate it for use with Camel's contract-first REST support?
-----
-
-Paste the OpenAPI spec (JSON or YAML) and the assistant calls `camel_openapi_validate`. It reports any compatibility
-issues such as missing `operationId` fields, unsupported security schemes (OAuth2, mutual TLS), OpenAPI 3.1
-limitations, and webhooks usage. A valid spec with no issues returns `valid: true` with an operation count.
-
-=== Scaffolding a Contract-First REST API
-
-----
-Generate a Camel YAML scaffold for this OpenAPI spec. The spec file will be called petstore.yaml
-and I want missing operations to use mock mode.
-----
-
-The assistant calls `camel_openapi_scaffold` with `specFilename=petstore.yaml` and `missingOperation=mock`.
-It returns a ready-to-use YAML file containing:
+The assistant uses `camel_error_diagnose` to identify the exception chain, extract components, and suggest fixes (e.g., missing `camel-kafka` dependency).
-* A `rest:openApi` configuration block referencing the spec file with `missingOperation: mock`
-* A `direct:<operationId>` route stub for each operation with `Content-Type` and response code headers
-
-=== Getting Mock Guidance
-
-----
-I want to use Camel's mock mode for my OpenAPI REST API during development. Show me the directory
-structure and mock files I need to create.
-----
-
-The assistant calls `camel_openapi_mock_guidance` with `mode=mock`. It returns:
-
-* An explanation of how mock mode works
-* The YAML configuration snippet with `missingOperation: mock`
-* The `camel-mock/` directory structure with mock file paths derived from the API paths
-* Example content for mock files based on examples defined in the spec
-
-=== Combined Contract-First Workflow
-
-For a complete prototyping workflow, you can combine all three tools:
-
-----
-I'm building a new REST API with Camel using contract-first. Here's my OpenAPI spec.
-Please validate it for compatibility issues, then generate the Camel YAML scaffold
-with mock mode so I can prototype quickly.
-----
-
-The assistant first calls `camel_openapi_validate` to check for issues, then calls `camel_openapi_scaffold`
-to generate the route scaffold. This gives you a validated spec and a complete starting point where you can
-implement routes one at a time while Camel auto-mocks the rest.
-
-=== Using the Build Integration Prompt
-
-In MCP clients that support prompts, select the `camel_build_integration` prompt and provide your requirements:
-
-----
-Requirements: Read messages from a Kafka topic, filter them by a JSON field, and write matching messages to an AWS S3 bucket.
-Runtime: quarkus
-----
+=== Dependencies and versions
-The prompt guides the assistant through a structured seven-step workflow: discovering the right components
-(`kafka`, `aws2-s3`), selecting EIPs (`filter`), retrieving their documentation, building a YAML route,
-validating it against the YAML DSL schema, and running a security review — all in the correct order.
+* _"Check my pom.xml for missing or outdated dependencies"_ — uses `camel_dependency_check`
+* _"What are the latest LTS versions for Spring Boot?"_ — uses `camel_version_list`
-=== Using the Migrate Project Prompt
-
-Select the `camel_migrate_project` prompt and provide your project's `pom.xml`:
-
-----
-pomContent: <paste your pom.xml here>
-targetVersion: 4.18.0
-----
-
-The prompt orchestrates the full migration workflow: analyzing your project, checking component compatibility,
-retrieving OpenRewrite recipes, searching migration guides for per-component breaking changes, and producing a
-structured migration summary with blockers, manual steps, and the exact commands to run.
-
-=== Using the Security Review Prompt
-
-Select the `camel_security_review` prompt and provide a route:
-
-----
-Route: <paste your route here>
-Format: yaml
-----
-
-The prompt guides the assistant through a security audit: analyzing the route for vulnerabilities and
-security-sensitive components, understanding the data flow, and producing a structured audit checklist with
-critical issues, warnings, positive findings, and actionable recommendations.
-
-=== Runtime Introspection Examples
-
-The runtime tools require a Camel application to be running. Start one with `camel run`:
-
-[source,bash]
-----
-camel run my-route.yaml
-----
-
-Then, from a separate terminal (or through your AI assistant), the MCP server auto-discovers the running process.
-
-==== Listing Running Processes
-
-----
-Show me the running Camel processes
-----
-
-The assistant calls `camel_runtime_processes` and returns the PID, name, and context name for each discovered
-Camel application.
-
-==== Inspecting Context and Routes
-
-----
-Show me the Camel context info and route statistics for the running application
-----
+=== Migration
-The assistant calls `camel_runtime_context` to get context metadata (version, state, uptime) and
-`camel_runtime_routes` to list routes with their state, exchange counts, and throughput.
+* _"Migrate my project to the latest version (here's my pom.xml)"_ — uses `camel_migration_analyze` → `camel_migration_compatibility` → `camel_migration_recipes`
+* _"What changed with direct-vm in Camel 4?"_ — uses `camel_migration_guide_search`
+* _"Migrate from WildFly to Quarkus"_ — uses `camel_migration_wildfly_karaf` for archetype commands and steps
+* Use the `camel_migrate_project` prompt for an orchestrated multi-step workflow
-==== Debugging a Live Route
+=== OpenAPI contract-first
-----
-Enable tracing so I can see messages flowing through my routes, then show me the traced messages
-----
+* _"Validate this OpenAPI spec for Camel compatibility"_ — uses `camel_openapi_validate`
+* _"Generate a Camel YAML scaffold with mock mode"_ — uses `camel_openapi_scaffold`
+* _"Show me the mock directory structure"_ — uses `camel_openapi_mock_guidance`
-The assistant calls `camel_runtime_trace` with `action=enable` to start tracing, waits briefly, then calls
-`camel_runtime_trace` with `action=dump` to retrieve the traced messages showing the path each exchange took
-through the route processors.
+Combine all three for a complete prototyping workflow: validate, scaffold, then implement routes one at a time while Camel mocks the rest.
-==== Sending a Test Message
+=== Runtime introspection
-----
-Send a test message with body "Hello" to the direct:start endpoint
-----
+Start a route with `camel run my-route.yaml`, then ask:
-The assistant calls `camel_runtime_send` with `endpoint=direct:start` and `body=Hello`. The tool returns the
-exchange result and any response.
+* _"Show me running Camel processes and route statistics"_ — uses `camel_runtime_processes` and `camel_runtime_routes`
+* _"Enable tracing and show me the traced messages"_ — uses `camel_runtime_trace`
+* _"Send a test message to direct:start"_ — uses `camel_runtime_send`
+* _"Which processors are the slowest?"_ — uses `camel_runtime_top`
+* _"Browse messages in seda:numbers"_ — uses `camel_runtime_browse`
-==== Finding Performance Bottlenecks
+=== Prompts (structured workflows)
-----
-Which processors in my routes are the slowest?
-----
+MCP clients that support prompts expose these as selectable workflows:
-The assistant calls `camel_runtime_top` to get processor-level statistics sorted by processing time,
-helping identify bottlenecks in the running application.
+* `camel_build_integration` — 7-step guided workflow: discover components → select EIPs → build → validate → security review
+* `camel_migrate_project` — 6-step migration: analyze → compatibility → recipes → guide search → summary
+* `camel_security_review` — 3-step audit: analyze vulnerabilities → understand data flow → produce checklist
diff --git a/docs/user-manual/modules/ROOT/pages/camel-jbang-projects.adoc b/docs/user-manual/modules/ROOT/pages/camel-jbang-projects.adoc
new file mode 100644
index 000000000000..5d416f666882
--- /dev/null
+++ b/docs/user-manual/modules/ROOT/pages/camel-jbang-projects.adoc
@@ -0,0 +1,234 @@
+= Camel CLI - Export to Maven
+
+Export your Camel CLI integrations to production-ready Maven projects, manage dependencies, and upgrade Camel versions.
+
+== Creating Projects
+
+Export your Camel CLI integration to a Maven-based project for Spring Boot, Quarkus, or standalone Camel Main.
+
+[source,bash]
+----
+camel export --runtime=spring-boot --gav=com.foo:acme:1.0-SNAPSHOT
+camel export --runtime=quarkus --gav=com.foo:acme:1.0-SNAPSHOT
+camel export --runtime=camel-main --gav=com.foo:acme:1.0-SNAPSHOT
+----
+
+NOTE: Without `--directory`, files are exported to the current directory. Use `--directory=../myproject` to copy to a separate folder.
+
+TIP: Run `camel export --help` for all options.
+
+Notes:
+
+- The Quarkus platform version is automatically resolved from the registry based on the Camel version.
+- The `--profile` option is not supported when exporting to Quarkus.
+- For Spring Boot, you can override versions with `--camel-spring-boot-version`.
+
+=== Exporting with Java Agent included
+
+NOTE: Only `camel-main` runtime supports Java Agents.
+
+Specify the agent with `agent:` prefix in `application.properties`:
+
+[source,properties]
+----
+camel.jbang.dependencies=camel:opentelemetry,agent:io.opentelemetry.javaagent:opentelemetry-javaagent:1.31.0
+camel.opentelemetry.enabled=true
+----
+
+Export and run:
+
+[source,bash]
+----
+camel export --runtime=camel-main --gav=com.foo:acme:1.0-SNAPSHOT --directory=../myproject
+cd ../myproject
+mvn clean package
+java -javaagent:agent/opentelemetry-javaagent-1.31.0.jar -jar target/acme-1.0-SNAPSHOT.jar
+----
+
+The agent JAR is downloaded from Maven and saved to the `agent/` folder.
+
+=== Exporting with selected files
+
+By default, all files from the current directory are exported. Specify files explicitly to split into multiple projects:
+
+[source,bash]
+----
+camel export Foo.java --runtime=quarkus --gav=com.foo:acme:1.0-SNAPSHOT --directory=../export1
+camel export bar.xml cheese.yaml --runtime=spring-boot --gav=com.foo:cheese:1.0-SNAPSHOT --directory=../export2
+----
+
+NOTE: `application.properties` is included in all exports automatically.
+
+=== Including JMX management or CLI connector
+
+JMX management and CLI connector are not included by default. Add them with `--dep`:
+
+[source,bash]
+----
+camel export --runtime=quarkus --gav=com.foo:acme:1.0-SNAPSHOT --dep=camel:management
+camel export --runtime=quarkus --gav=com.foo:acme:1.0-SNAPSHOT --dep=camel:cli-connector
+----
+
+=== Troubleshooting exporting
+
+Use `--verbose` and `--logging` for more detail, or `--logging-level=DEBUG` for full output.
+Try `--ignore-loading-error` if custom Java code prevents export.
+
+TIP: Export logs are stored in `~/.camel/camel-export.log` by default.
+
+=== Configuring exporting
+
+Export loads configuration from `application.properties`, where you can set runtime, Java version, and other parameters.
+See xref:camel-jbang-configuration.adoc[Configuration] for all `camel.jbang.*` options.
+
+== Gathering list of dependencies
+
+List the Camel components and JARs required to run your integration:
+
+[source,bash]
+----
+camel dependency list
+org.apache.camel:camel-dsl-modeline:3.20.0
+org.apache.camel:camel-health:3.20.0
+org.apache.camel:camel-kamelet:3.20.0
+org.apache.camel:camel-log:3.20.0
+...
+----
+
+Output defaults to GAV format. Use `--output=maven` for Maven XML format.
+Use `--runtime=spring-boot` or `--runtime=quarkus` for runtime-specific dependencies.
+
+== Generating SBOM report
+
+Generate a Software Bill of Materials for your integration:
+
+[source,bash]
+----
+camel sbom
+camel sbom --sbom-format=spdx
+camel sbom --runtime=quarkus
+----
+
+Defaults to CycloneDX format (`sbom.json`) with `camel-main` runtime.
+
+=== Copying dependency JARs
+
+Copy required JARs to a folder (defaults to `lib/`):
+
+[source,bash]
+----
+camel dependency copy
+----
+
+IMPORTANT: Both `camel dependency copy` and `camel dependency list` require Apache Maven (`mvn`) in PATH.
+
+== Manage plugins
+
+Plugins extend the CLI with additional commands. List available plugins (ASF and community):
+
+[source,bash]
+----
+camel plugin get --all
+----
+
+Add, list installed, and remove plugins:
+
+[source,bash]
+----
+camel plugin add generate
+camel plugin add forage --version=1.2.3
+camel plugin get
+camel plugin delete <plugin-name>
+----
+
+=== Building custom plugins
+
+It is possible to build custom Camel CLI plugins. We suggest to take a look at one of the https://github.com/apache/camel/tree/main/dsl/camel-jbang[existing plugins],
+to see how that is done.
+
+IMPORTANT: The name of the plugin Maven **artifactId** must start with `camel-jbang-plugin-`. For example if the plugin is named `cheese`, then
+the maven artifact must be named `camel-jbang-plugin-cheese`.
+
+== Generate JSON schema plugin
+
+Generate JSON Schema definitions from Java objects for use with visual development tools (Kaoto, Karavan):
+
+[source,bash]
+----
+camel generate schema fhir org.hl7.fhir.r4.model.Patient
+Schema saved to: ./org.hl7.fhir.r4.model.Patient-schema.json
+----
+
+== Version management
+
+Show the current Camel CLI version:
+
+[source,bash]
+----
+camel version
+----
+
+=== Running with a different version
+
+Use `--camel-version` to run with a specific Camel version:
+
+[source,bash]
+----
+camel run * --camel-version=3.18.4
+----
+
+Or set a persistent version override:
+
+[source,bash]
+----
+camel version set 3.18.2
+camel version set --reset
+----
+
+IMPORTANT: You cannot combine `camel version set` with `--camel-version`.
+
+For SNAPSHOT versions:
+
+[source,bash]
+----
+jbang --fresh -Dcamel.jbang.version=3.21.0-SNAPSHOT camel@apache/camel [command]
+----
+
+=== Listing available releases
+
+Show available Camel releases from Maven Central:
+
+[source,bash]
+----
+camel version list
+ CAMEL VERSION JDK KIND RELEASED SUPPORTED UNTIL
+ 3.18.0 11,17 LTS July 2022 July 2023
+ 3.20.0 11,17 LTS December 2022 December 2023
+ 4.0.0-M1 17 RC February 2023
+ ...
+----
+
+Use `--runtime=quarkus` or `--runtime=spring-boot` to see runtime-specific versions.
+Use `--from-version=3.0` to show older releases (back to Camel 2.18).
+
+TIP: Run `camel version list --help` for all options.
+
+== Automated updates (OpenRewrite)
+
+Update Camel applications automatically using https://github.com/apache/camel-upgrade-recipes[OpenRewrite recipes].
+Supports Camel Main, Spring Boot, and Quarkus.
+
+List available updates and run:
+
+[source,bash]
+----
+camel update list
+camel update run 4.9.0 --runtime=spring-boot --dry-run
+----
+
+NOTE: Run from the project directory containing `pom.xml`.
+
+Options: `--runtime` (camel-main, spring-boot, quarkus), `--repos` (extra Maven repos),
+`--dry-run` (preview only), `--extraActiveRecipes`, `--extraRecipeArtifactCoordinates`.
+
+TIP: Run `camel update run --help` for all options.
diff --git a/docs/user-manual/modules/ROOT/pages/camel-jbang-running.adoc b/docs/user-manual/modules/ROOT/pages/camel-jbang-running.adoc
new file mode 100644
index 000000000000..b30d7824b5ab
--- /dev/null
+++ b/docs/user-manual/modules/ROOT/pages/camel-jbang-running.adoc
@@ -0,0 +1,271 @@
+= Camel CLI - Running Camel
+
+This page covers the essential options for running Camel integrations — dev mode,
+properties, profiles, HTTP endpoints, dependencies, and runtimes.
+
+For advanced techniques like running from GitHub, clipboard, or stub components,
+see xref:camel-jbang-tips.adoc[Tips and Recipes].
+
+== Dev mode with live reload
+
+Run with `--dev` to get automatic reload when you edit and save your source files:
+
+[source,bash]
+----
+camel run foo.yaml --dev
+----
+
+This works for all DSLs (YAML, Java, XML).
+
+NOTE: Live reload is for development purposes. If you encounter JVM class loading issues,
+restart the integration. Java files are not live-reloadable in Spring Boot runtime.
+
+=== Source directory
+
+Use `--source-dir` for more flexibility — Camel watches the entire directory (including subfolders)
+and automatically detects new, modified, and deleted files:
+
+[source,bash]
+----
+camel run --source-dir=mycode --dev
+----
+
+Without `--source-dir`, Camel only watches the specific files you listed on the command line.
+
+NOTE: You cannot combine files and source dir: `camel run abc.java --source-dir=mycode` is not allowed.
+
+=== Live reload of resource files
+
+In dev mode, Camel disables `contentCache` on resource-based components (such as `xslt`)
+so that edits to resource files are picked up on the next message without restarting.
+
+User properties (e.g. `camel.component.xslt.contentCache=true`) and explicit endpoint settings
+are always respected.
+
+=== Loading new routes into existing Camel
+
+*Available as of Camel 4.17*
+
+The `camel cmd load` command loads new routes into a running Camel application:
+
+[source,bash]
+----
+camel cmd load --source=bar.java
+----
+
+IMPORTANT: Assign _ids_ to your routes so the `load` command detects previously loaded routes
+and avoids duplicates.
+
+TIP: Use `--restart` to restart all routes after the new route is loaded.
+
+== Using properties
+
+Set properties with `--property` or load them from a file with `--properties`:
+
+[source,bash]
+----
+camel run foo.yaml --property=my-key=my-value
+camel run foo.yaml --properties=/var/my-app/config.properties
+----
+
+NOTE: Use the `=` sign directly after `--property` (no space).
+
+If both are used, the properties are merged into a single `application.properties` file.
+
+[#_using_profiles]
+== Using profiles
+
+*Available from Camel 4.5*
+
+Camel CLI has three profiles:
+
+- `dev` — development (default), enables tracing, extra metrics, and developer-focused features
+- `test` — testing (currently same as production)
+- `prod` — production
+
+Run with a specific profile:
+
+[source,bash]
+----
+camel run hello.java --profile=prod
+----
+
+Use profile-specific configuration files:
+
+- `application.properties` — common configuration (always loaded)
+- `application-dev.properties` — dev profile overrides
+- `application-prod.properties` — production profile overrides
+
+NOTE: Since Camel 4.21, `camel run` and `camel export` auto-detect `application.properties`
+(and profile-specific variants) in the current directory.
+
+== Using the platform-http component
+
+When a route uses `platform-http`, Camel CLI automatically starts a VertX HTTP server on port 8080:
+
+[source,yaml]
+----
+- route:
+ from:
+ uri: platform-http:/hello
+ steps:
+ - set-body:
+ constant: "Hello World"
+----
+
+[source,bash]
+----
+camel run server.yaml
+----
+
+[source,bash]
+----
+$ curl http://localhost:8080/hello
+Hello World%
+----
+
+NOTE: Camel CLI only supports `platform-http` for HTTP serving and REST DSL.
+It does not support `camel-servlet` or `camel-jetty`.
+
+== Adding custom JARs
+
+Camel CLI automatically detects and downloads dependencies for Camel components.
+For 3rd-party JARs, use `--dep` with Maven GAV syntax:
+
+[source,bash]
+----
+camel run foo.java --dep=com.foo:acme:1.0
+----
+
+For Camel dependencies, use the shorthand syntax:
+
+[source,bash]
+----
+camel run foo.java --dep=camel-saxon
+----
+
+Multiple dependencies can be separated by comma:
+
+[source,bash]
+----
+camel run foo.java --dep=camel-saxon,com.foo:acme:1.0
+----
+
+== Using 3rd-party Maven repositories
+
+By default, Camel CLI downloads from the local Maven repository and Maven Central.
+To add other repositories:
+
+[source,bash]
+----
+camel run foo.java --repos=https://packages.atlassian.com/maven-external
+----
+
+TIP: Separate multiple repositories with commas.
+
+You can also configure repositories in `application.properties`:
+
+[source,properties]
+----
+camel.jbang.repos=https://packages.atlassian.com/maven-external
+----
+
+Or set a global default via environment variable:
+
+[source,bash]
+----
+export JAVA_TOOL_OPTIONS="-Dcamel.extra.repos=repo1=https://repo1.example.com/maven2,repo2=https://repo2.example.com/releases"
+----
+
+== Downloading JARs over the internet
+
+Camel CLI automatically resolves and downloads dependencies in this order:
+
+1. Local Maven repository (`~/.m2/repository`)
+2. Maven Central
+3. Custom 3rd-party repositories
+4. Repositories from `~/.m2/settings.xml`
+
+To disable automatic downloading:
+
+[source,bash]
+----
+camel run foo.java --download=false
+----
+
+== Running with Spring Boot or Quarkus
+
+Camel CLI can run integrations using Spring Boot or Quarkus runtimes:
+
+[source,bash]
+----
+camel run foo.camel.yaml --runtime=spring-boot
+camel run foo.camel.yaml --runtime=quarkus
+----
+
+This does an export to a temporary folder and runs using Maven.
+Source changes are reloaded via Spring Boot dev-tools or Quarkus dev mode.
+
+Limitations:
+
+- Spring Boot and Quarkus cannot auto-detect new components (stop and run again to update dependencies)
+- Quarkus versions are locked to a specific Camel version (`camel version list --runtime=quarkus`)
+- Spring Boot is more flexible — you can choose different versions:
+
+[source,bash]
+----
+camel run foo.camel.yaml --runtime=spring-boot --spring-boot-version=3.2.3 --camel-version=4.4.1
+camel run foo.camel.yaml --runtime=quarkus --quarkus-version=3.9.4
+----
+
+== Running local Kamelets
+
+Run local Kamelets without publishing them:
+
+[source,bash]
+----
+camel run --local-kamelet-dir=/path/to/local/kamelets earthquake.yaml
+----
+
+TIP: Local Kamelets support live reload in dev mode.
+
+You can also point to a GitHub folder:
+
+[source,bash]
+----
+camel run --local-kamelet-dir=https://github.com/apache/camel-kamelets-examples/tree/main/custom-kamelets user.java
+----
+
+NOTE: Kamelets loaded from GitHub cannot be live reloaded.
+
+== Creating a new Kamelet
+
+Create a new Kamelet using naming conventions — the suffix determines the type:
+
+[source,bash]
+----
+camel init cheese-source.kamelet.yaml # creates a source kamelet
+camel init wine-sink.kamelet.yaml # creates a sink kamelet
+----
+
+Use the new Kamelet in a route:
+
+[source,yaml]
+----
+- route:
+ from:
+ uri: kamelet:cheese-source
+ parameters:
+ period: "2000"
+ message: "Hello World"
+ steps:
+ - to:
+ uri: kamelet:wine-sink
+----
+
+To base a new Kamelet on an existing one:
+
+[source,bash]
+----
+camel init orderdb-sink.kamelet.yaml --from-kamelet=mysql-sink
+----
diff --git a/docs/user-manual/modules/ROOT/pages/camel-jbang-test.adoc b/docs/user-manual/modules/ROOT/pages/camel-jbang-test.adoc
index 5bb21d641338..e0a474f48f2c 100644
--- a/docs/user-manual/modules/ROOT/pages/camel-jbang-test.adoc
+++ b/docs/user-manual/modules/ROOT/pages/camel-jbang-test.adoc
@@ -1,185 +1,84 @@
= Camel Testing plugin
-This plugin helps you to write automated tests with Camel CLI.
-Please make sure to meet these prerequisites for running tests with Camel CLI:
+Write and run automated tests for Camel integrations using the https://citrusframework.org/[Citrus] test framework.
-* Activate the Camel CLI test plugin
-
-The Camel CLI Test functionality is provided as a command plugin.
-This means you need to enable the `test` plugin first to use the subcommands in Camel CLI.
+Enable the plugin:
[source,bash]
----
camel plugin add test
----
-You should see the `test` plugin listed as an installed plugin.
-
-[source,bash]
-----
-camel plugin get
-----
-
-[source,bash]
-----
- NAME COMMAND DEPENDENCY DESCRIPTION
- test test org.apache.camel:camel-jbang-plugin-test Manage tests for Camel applications
-----
-
-Now Camel CLI is able to run the subcommands offered by the plugin.
-You can inspect the help page to see the list of available plugin subcommands.
-
-[source,bash]
-----
-camel test --help
-----
-
-You will see the list of available subcommands for this plugin.
+TIP: Run `camel test --help` to see all available subcommands.
== Initialize tests
-The plugin helps you to create automated tests for your Camel integration.
-
-The `init` command creates an empty test file that you can use as a starting point.
+Create an empty test file as a starting point:
[source,bash]
----
camel test init route-test.yaml
----
-The command creates an empty test that uses the given test specification language derived from the file name extension.
-In the example above the test uses YAML as a domain specific language.
-
-The plugin supports the following languages to write automated tests:
-
-* YAML
-* Groovy
-* Java
-* XML
-* Cucumber (.feature file extension)
+The file extension determines the test language: YAML, Java, XML, or Cucumber (`.feature`).
-Whatever language you choose, the result will be a new file that represents the test.
-
-NOTE: The plugin automatically uses a `test` subfolder to create and run tests. This is because it is a good design to separate test-scoped and runtime source files.
-
-TIP: You do not need to navigate to the `test` subfolder when running the test. The plugin will automatically set the proper working directory for you so you do not have to switch folders all the time.
-
-You can directly run the test and start implementing the test logic.
+NOTE: Tests are created in a `test` subfolder to separate them from runtime sources. You don't need to navigate there — the plugin handles the working directory automatically.
== Run tests
-The test plugin helps you to run the tests with JBang.
-As usual, there is no need to create a project or set-up dependencies for that.
-Camel CLI just runs the test locally.
+Run tests locally with JUnit Jupiter — no project setup needed:
[source,bash]
----
camel test run route-test.yaml
----
-You will see the test running and producing some output to the console.
-At the end you should see a passed test in the test summary.
-By default, the tests are run with the JUnit Jupiter engine.
-Please refer to the help page of the `run` command for options and details.
-
-TIP: The Camel CLI plugin automatically creates a subfolder `test` and adds the test source files into this folder.
-This is a way to separate test scoped resources from Camel integration sources.
-
== Project export
-Once you are happy with the Camel integration and the automated test you may want to export these files into a project for further usage after the prototyping phase.
-
-The test plugin is able to participate in the project export in order to also add test scoped resources.
-When the plugin is active in your local JBang environment it will try to locate the automated tests and its resources (in the `test` subfolder) to add them to the exported project.
-
-Just keep using the normal project export command provided in Camel CLI.
-The test plugin will automatically add the test resources for you.
+When you export a project, the test plugin automatically includes test resources as test-scoped Maven dependencies in `src/test/java` and `src/test/resources`:
[source,bash]
----
camel export route.yaml --dir my-export --runtime quarkus
-----
-
-The resulting project export holds the test resources and the required dependencies to run the test.
-In Maven this will be test-scoped dependencies added to the Maven `pom.xml` and test resources in `src/test/java` and `src/test/resources`.
-
-The tests are now part of the Maven build lifecycle so you can build the project and see the tests being automatically run.
-Navigate to the project export folder and run the Maven verify lifecycle that includes running integration tests.
-
-[source,bash]
-----
+cd my-export
./mvnw verify
----
-You should see some tests being executed during the Maven build and of course in case a test is failing you will see the Maven build failing, too.
-Now the automated tests from the prototyping phase with Camel CLI are part of the project for further usage in a CI/CD pipeline for instance.
-
-TIP: The project export has created a Java unit test (in `src/test/java`) that runs the test. You can also run the test from your Java IDE with this class. By default, the export uses JUnit Jupiter as a test engine.
+TIP: The export creates a JUnit Jupiter test class in `src/test/java` that you can also run from your IDE.
== Dependency management
-The test plugin is based on the Java test framework https://citrusframework.org/[Citrus].
-It uses commands and modules provided by Citrus to run the tests.
-In fact the Camel test plugin calls Citrus as another JBang command.
-
-The Citrus JBang tooling includes some basic dependencies out of the box, so you are not required to add dependencies prior to running the test.
-In case you need to add a Citrus module that is not included by default (e.g. support for Kafka or Testcontainers) you can add the additional dependencies to a file called `jbang.properties`.
-
-TIP: The property file should be located right next to the test source file, so JBang can find it automatically when running the test.
+Basic Citrus dependencies are included out of the box. For additional modules (Kafka, Testcontainers, etc.), add them in a `jbang.properties` file next to the test source:
.jbang.properties
[source,properties]
----
-# Declare required additional dependencies
run.deps=org.citrusframework:citrus-camel:4.7.0,\
org.citrusframework:citrus-kafka:4.7.0,\
org.citrusframework:citrus-testcontainers:4.7.0,\
org.apache.camel:camel-endpointdsl:4.13.0,\
org.apache.camel:camel-aws2-s3:4.13.0
-# Enable dump of Camel CLI integration output
run.D=citrus.camel.jbang.dump.integration.output=true
----
-You can add dependencies in the form of Maven GAV style coordinates in the `run.deps` property.
-JBang will automatically resolve the artifacts and add it to the runtime.
-
-The `jbang.properties` is a good place to add System properties for the Citrus runtime.
-For instance, the setting `citrus.camel.jbang.dump.integration.output=true` controls the output of the Camel integration and that it should be stored into a file for later analysis.
-
-TIP: During the project export the dependencies listed in `jbang.properties` will be added to the Maven POM as test-scoped dependencies.
+TIP: These dependencies are automatically added as test-scoped dependencies during project export.
-== Explore test capabilities
+== Writing tests with Citrus
-The test plugin uses https://citrusframework.org/[Citrus] as an underlying test framework.
-Citrus is an Open Source Java test framework that integrates very well with Apache Camel as it provides special test actions to use Camel CLI for instance.
+The test plugin uses https://citrusframework.org/[Citrus] as the underlying test framework. A typical test:
-You can also install the https://citrusframework.org/[Citrus test framework] JBang application to explore the full capabilities.
+1. Starts infrastructure (Kafka, database, etc.)
+2. Launches the Camel integration with test configuration
+3. Sends messages to trigger route logic
+4. Verifies the outcome
-[source,bash]
-----
-jbang trust add https://github.com/citrusframework/citrus/
-jbang app install citrus@citrusframework/citrus
-----
-
-Usually an automated test of a Camel integration needs to perform these high level steps:
-
-* Create and prepare required test infrastructure (e.g. start a Kafka message broker, prepare a database)
-* Start the Camel integration and configure the routes to connect with the infrastructure
-* Invoke exposed services of the Camel integration that triggers the route logic
-* Verify the Camel integration outcome (e.g. receive and validate created events on Kafka, verify the entries in a database)
-
-The following sections explore these tasks when writing a test in Citrus.
-For further details on test capabilities please also read the https://citrusframework.org/citrus/reference/html/[Citrus documentation].
+For full details, see the https://citrusframework.org/citrus/reference/html/[Citrus documentation].
-=== Using Camel Infrastructure Services
+=== Using infrastructure services
-The Camel CLI `infra` command enables you to start infrastructure services in your test environment.
-See the list of available services with `camel infra`.
+Start Camel infra services or Testcontainers as part of the test:
-The Citrus test is able to run these infrastructure services as part of the test.
-
-.Start Camel infra service
[source,yaml]
----
actions:
@@ -187,59 +86,24 @@ actions:
infra:
run:
service: postgres
-----
-
-Once the infrastructure service is started Citrus exposes connection settings as test variables.
-You can use the exposed connection settings to create proper clients that connect to the services.
-
-The exposed connection settings follow a naming pattern that looks like this:
-
-* CITRUS_CAMEL_INFRA_SERVICE_<SERVICE_NAME>_<PROPERTY_NAME>
-* CITRUS_CAMEL_INFRA_SERVICE_<SERVICE_NAME>_<IMPLEMENTATION>_<PROPERTY_NAME>
-
-You can then use these test variables in the Camel configuration (e.g. in `application.properties`).
-
-.application.properties
-[source,properties]
-----
-camel.database.url=${CITRUS_CAMEL_INFRA_POSTGRES_SERVICE_ADDRESS}
-----
-
-Read more about the https://citrusframework.org/citrus/reference/html/#camel-infra[Camel infra support in Citrus].
-
-=== Using Testcontainers
-
-In a similar way to starting Camel infrastructure services you can also use Testcontainers as a form of infrastructure for your test.
-You may want to start a Testcontainers instance as part of the test.
-
-[source,yaml]
-----
-actions:
- testcontainers:
start:
kafka: {}
----
-Once the Testcontainers instance is started the Citrus test exposes connection settings in the form of test variables.
-The variable names follow this naming pattern:
+Connection settings are exposed as test variables (`CITRUS_CAMEL_INFRA_SERVICE_<NAME>_<PROP>` or `CITRUS_TESTCONTAINERS_<NAME>_<PROP>`) for use in `application.properties`:
-* CITRUS_TESTCONTAINERS_<SERVICE_NAME>_<PROPERTY_NAME>
-
-You can reference the test variables in the configuration for the Camel routes (e.g. in `application.properties`).
-
-.application.properties
[source,properties]
----
+camel.database.url=${CITRUS_CAMEL_INFRA_POSTGRES_SERVICE_ADDRESS}
camel.kafka.bootstrapServers=${CITRUS_TESTCONTAINERS_KAFKA_BOOTSTRAP_SERVERS}
----
-Read more about the https://citrusframework.org/citrus/reference/html/#testcontainers[Testcontainers support in Citrus].
+See https://citrusframework.org/citrus/reference/html/#camel-infra[Camel infra] and https://citrusframework.org/citrus/reference/html/#testcontainers[Testcontainers] in the Citrus docs.
-=== Run the Camel integration
+=== Running the Camel integration
-Citrus provides special test actions to run Camel integrations with Camel CLI.
-The test starts the integration as a separate Camel CLI process.
-You are able to apply specific configuration to the Camel CLI process such as `application.properties`, system properties and environment variables.
+Launch a Camel integration as a separate process with test-specific configuration:
[source,yaml]
----
@@ -253,25 +117,15 @@ actions:
file: "application.test.properties"
----
-The test action above runs the Camel integration in the file `route.yaml` and applies some test configuration as application properties.
-
-TIP: Note that the file path to the `route.yaml` Camel integration uses a relative path that navigates to the parent folder.
-This is because usually the tests are located in a subdirectory (e.g. `test`) in order to separate test-scoped resources from runtime resources.
-
-This will start the Camel integration as a Camel CLI process.
-The test waits for the integration to report a running status.
-Then the test proceeds with further actions (e.g. invoking the exposed service of the Camel integration).
-
-Read more about the https://citrusframework.org/citrus/reference/html/#apache-camel[Camel CLI support in Citrus].
+TIP: The path uses `../` because tests are in the `test` subfolder.
-=== Send/receive messages
+See https://citrusframework.org/citrus/reference/html/#apache-camel[Camel CLI support in Citrus].
-Once the Camel integration is up and running the test may trigger the route logic by invoking an exposed service.
-Citrus is able to send and receive messages with various messaging transports (Kafka, Http, SOAP WebServices, FTP, JMS and many more).
+=== Sending and receiving messages
-You can send a message to a Kafka topic for instance:
+Citrus supports Kafka, HTTP, SOAP, FTP, JMS, and many more transports:
-.Send message to Kafka topic
+.Send to Kafka
[source,yaml]
----
actions:
@@ -286,28 +140,7 @@ actions:
value: "bookings.csv_0"
----
-The message sent may trigger the Camel integration that listens for events on the Kafka topic `bookings`.
-
-In the same way Citrus would be able to invoke an Http service that the Camel integration exposes as a Http platform service.
-
-.Invoke Http service
-[source,yaml]
-----
-actions:
- - send:
- endpoint: "http://localhost:8080/bookings"
- message:
- body:
- data: |
- { "client": "camel-batch", "product": "Orange", "amount": 200, "price": 1.0, "status": "APPROVAL_REQUIRED" }
- headers:
- - name: "Content-Type"
- value: "application/json"
-----
-
-When receiving messages in the test you can define an expected message content (body and headers).
-
-.Validate Kafka event
+.Verify received message
[source,yaml]
----
actions:
@@ -319,36 +152,7 @@ actions:
{ "bookings": { "completed": 1, "errors": 0 } }
----
-The test will validate the message according to the expected message content and of course the test will fail in case some elements
-are not as expected. Citrus as a test framework provides very powerful message validation capabilities for different message formats such as XML, Json, YAML, plaintext and more.
-
-Read more about https://citrusframework.org/citrus/reference/html/#endpoints[message endpoints] and how to invoke services with https://citrusframework.org/citrus/reference/html/#actions-send[send and receive test actions] in Citrus.
-
-=== Invoke Camel endpoint URIs
-
-Citrus is able to invoke any Camel endpoint URI as part of the test.
-This way users are able to use any of the Apache Camel components for sending and receiving messages during the test.
-
-.Send message to AWS S3 service
-[source,yaml]
-----
-actions:
- - send:
- endpoint: |
- camel:aws2-s3:my-bucket?amazonS3Client=#s3Client
- message:
- body:
- data: |
- Apple,200,1.0
- Orange,100,1.0
- Pineapple,100,2.99
- headers:
- - name: "CamelAwsS3Key"
- value: "bookings.csv"
-----
-
-This uses the `aws2-s3` Apache Camel component to create a new file on a S3 bucket.
-
-TIP: You can reference beans in the Camel endpoint URI. As an example the URI above uses a bean reference `#s3Client` as a client that connects to the AWS S3 test infrastructure service. The beans can be added to both the Camel context or the Citrus registry.
+You can also use any Camel endpoint URI directly (e.g., `camel:aws2-s3:my-bucket?amazonS3Client=#s3Client`).
+Bean references (`#beanName`) and Citrus test variables work in endpoint URIs.
-TIP: You can also use Citrus test variables in the Camel endpoint URIs in order to reference dynamic values such as connection settings exposed by test infrastructure.
+See https://citrusframework.org/citrus/reference/html/#actions-send[send/receive actions] and https://citrusframework.org/citrus/reference/html/#endpoints[message endpoints] in the Citrus docs.
diff --git a/docs/user-manual/modules/ROOT/pages/camel-jbang-tips.adoc b/docs/user-manual/modules/ROOT/pages/camel-jbang-tips.adoc
new file mode 100644
index 000000000000..4dac9fde047f
--- /dev/null
+++ b/docs/user-manual/modules/ROOT/pages/camel-jbang-tips.adoc
@@ -0,0 +1,222 @@
+= Camel CLI - Tips and Recipes
+
+A collection of productivity shortcuts and advanced techniques for working with the Camel CLI.
+
+== Run from clipboard
+
+Run a route directly from the OS clipboard — copy some code, then run it:
+
+[source,bash]
+----
+camel run clipboard.yaml
+----
+
+The extension tells the CLI which DSL the clipboard content uses (`yaml`, `java`, `xml`).
+
+You can also run from clipboard in dev mode for live reload:
+
+[source,bash]
+----
+camel run clipboard.yaml --dev
+----
+
+Edit your code, copy it again, and Camel reloads automatically.
+
+== Run with inline code
+
+For quick one-liners, pass the route directly on the command line:
+
+[source,bash]
+----
+camel run --code='from("kamelet:beer-source").to("log:beer")'
+----
+
+Limitations:
+
+- Java DSL only
+- Wrap code in single quotes so you can use double quotes inside
+- All routes must fit in a single `--code` parameter
+
+From Camel 4.7, `--code` can also reference a `.java` file that contains bare route definitions
+(no `public class` wrapper):
+
+[source,java]
+----
+from("timer:java?period=1000")
+ .setBody()
+ .simple("Hello from ${routeId}")
+ .log("${body}");
+----
+
+[source,bash]
+----
+camel run --code=quick.java
+----
+
+== Interactive prompt for placeholder values
+
+Run with `--prompt` to have Camel ask for missing values at startup:
+
+[source,bash]
+----
+camel run foo.java --prompt
+----
+
+Camel will prompt for each unresolved pass:c[`{{placeholder}}`] in the terminal.
+Placeholders with default values (e.g. pass:c[`{{time:1000}}`]) can be accepted by pressing Enter.
+
+This is useful for prototypes where you want users to enter custom values quickly.
+Values can also be pre-configured in `application.properties`.
+
+== Stub components
+
+When troubleshooting a route that uses components you cannot connect to (JMS brokers, databases, etc.),
+stub them out:
+
+[source,bash]
+----
+camel run myroute.java --stub=jms
+----
+
+Camel replaces the stubbed component with an in-memory substitute, keeping the original endpoint URIs.
+You can then send test messages with:
+
+[source,bash]
+----
+camel cmd send --body='Something here'
+----
+
+Other stub options:
+
+[source,bash]
+----
+camel run myroute.java --stub=jms:inbox # stub a specific endpoint
+camel run myroute.java --stub=jms,sql # stub multiple components
+camel run myroute.java --stub=remote # stub all remote components
+camel run myroute.java --stub=all # stub everything
+----
+
+The `remote` flag uses the Camel catalog to determine which components connect to external systems.
+
+Use `camel cmd stub` to list stubbed endpoints, and `camel cmd stub --browse` to browse their messages.
+
+== Run from GitHub
+
+Run a route directly from a GitHub repository:
+
+[source,bash]
+----
+camel run github:apache:camel-kamelets-examples:jbang/hello-java/Hey.java
+----
+
+Or use the full HTTPS URL — copy it from your browser:
+
+[source,bash]
+----
+camel run https://github.com/apache/camel-kamelets-examples/tree/main/jbang/hello-java
+----
+
+Wildcards work too:
+
+[source,bash]
+----
+camel run https://github.com/apache/camel-kamelets-examples/tree/main/jbang/languages/rou*
+----
+
+=== Run from GitHub gists
+
+Gists are a quick way to share small Camel routes:
+
+[source,bash]
+----
+camel run https://gist.github.com/davsclaus/477ddff5cdeb1ae03619aa544ce47e92
+----
+
+A gist can contain multiple files (routes, properties, Java beans) — the CLI gathers them all.
+
+== Download from GitHub
+
+Download examples from GitHub to local disk for editing:
+
+[source,bash]
+----
+camel init https://github.com/apache/camel-kamelets-examples/tree/main/jbang/dependency-injection
+camel run *
+----
+
+Use `--directory` to download into a specific folder:
+
+[source,bash]
+----
+camel init https://github.com/apache/camel-kamelets-examples/tree/main/jbang/dependency-injection --directory=myproject
+----
+
+Single files and gists work the same way:
+
+[source,bash]
+----
+camel init https://github.com/apache/camel-kamelets-examples/blob/main/jbang/hello-yaml/hello.camel.yaml
+camel init https://gist.github.com/davsclaus/477ddff5cdeb1ae03619aa544ce47e92
+----
+
+== Upload files via HTTP
+
+When running with `--source-dir`, `--console`, and `--dev`, you can upload, modify, or delete
+source files over HTTP:
+
+[source,bash]
+----
+camel run --source-dir=mycode --console --dev
+----
+
+Upload or update a file:
+
+[source,bash]
+----
+curl -T bar.java http://0.0.0.0:8080/q/upload/bar.java
+----
+
+Delete files (wildcards supported):
+
+[source,bash]
+----
+curl -X DELETE http://0.0.0.0:8080/q/upload/bar.java
+curl -X DELETE http://0.0.0.0:8080/q/upload/*.java
+curl -X DELETE http://0.0.0.0:8080/q/upload/*
+----
+
+== Maven configuration
+
+By default, Camel CLI loads `~/.m2/settings.xml` for Maven mirrors, credentials, and repositories.
+
+You can override the settings file location:
+
+[source,bash]
+----
+camel run foo.java --maven-settings=/path/to/settings.xml --maven-settings-security=/path/to/settings-security.xml
+----
+
+Or disable Maven settings entirely:
+
+[source,bash]
+----
+camel run foo.java --maven-settings=false
+----
+
+For encrypted passwords in Maven settings, configure a master password with `mvn -emp`,
+store it in `~/.m2/settings-security.xml`, then encrypt repository passwords with `mvn -ep`.
+See the https://maven.apache.org/guides/mini/guide-encryption.html[Maven encryption guide] for details.
+
+== Running a Maven based project
+
+Camel CLI can do a _best effort_ run of an existing Maven-based project for migration purposes:
+
+[source,bash]
+----
+camel run pom.xml
+----
+
+Camel CLI scans `src/main/java` and `src/main/resources` for files to include.
+
+NOTE: This is not a fully compatible way to run Maven projects. It cannot start Spring Boot or Quarkus
+applications — use the proper plugins for those. This command is mainly useful for migrating from old projects.
diff --git a/docs/user-manual/modules/ROOT/pages/camel-jbang-transforming.adoc b/docs/user-manual/modules/ROOT/pages/camel-jbang-transforming.adoc
new file mode 100644
index 000000000000..fc46c1663b84
--- /dev/null
+++ b/docs/user-manual/modules/ROOT/pages/camel-jbang-transforming.adoc
@@ -0,0 +1,497 @@
+= Camel CLI - Data Transformation
+
+The Camel CLI includes tools for transforming messages and converting between route DSL formats — with live reload for interactive development. For the full overview, see xref:camel-jbang.adoc[Camel CLI].
+
+== Transforming messages (data mapping)
+
+The `camel transform message` command takes an input message and a template, and shows the
+transformed output in real time — with live reload as you edit the template.
+
+For example, given this JSON document (`random.json`):
+
+[source,json]
+----
+{
+ "id": 9914,
+ "uid": "eb5fa603-1db6-45f9-912a-431a6ed59b18",
+ "password": "ei7gvYKdnN",
+ "first_name": "Khalilah",
+ "last_name": "Monahan",
+ "username": "khalilah.monahan",
+ "email": "khalilah.monahan@email.com",
+ "avatar": "https://robohash.org/utnumquamexcepturi.png?size=300x300&set=set1",
+ "gender": "Agender",
+ "phone_number": "+54 (421) 591-5640 x333",
+ "social_insurance_number": "268418308",
+ "date_of_birth": "1975-03-11",
+ "employment": {
+ "title": "Product Design Director",
+ "key_skill": "Work under pressure"
+ },
+ "address": {
+ "city": "New Fritzchester",
+ "street_name": "Patrick Common",
+ "street_address": "4538 Reggie Inlet",
+ "zip_code": "16282-7045",
+ "state": "New York",
+ "country": "United States",
+ "coordinates": {
+ "lat": -1.9868753435474673,
+ "lng": 39.09763956726292
+ }
+ },
+ "credit_card": {
+ "cc_number": "4493983042212"
+ },
+ "subscription": {
+ "plan": "Student",
+ "status": "Active",
+ "payment_method": "Debit card",
+ "term": "Monthly"
+ }
+}
+----
+
+Create a `transform.json` template with the desired output structure:
+
+[source,json]
+----
+{
+ "sid": 123,
+ "name": "TODO",
+ "country": "TODO",
+ "phone": "TODO",
+ "student": false
+}
+----
+
+Run with `--watch` to see output update live as you edit the template:
+
+[source,bash]
+----
+$ camel transform message --body=file:random.json --language=simple --template=file:transform.json --pretty --watch
+----
+
+Initial output:
+
+[source,bash]
+----
+ Exchange (DefaultExchange) InOut 23F5DD4CE6C260B-0000000000000002
+ Message (DefaultMessage)
+ Body (String) (bytes: 118)
+ {
+ "sid": 123,
+ "name": "TODO",
+ "country": "TODO",
+ "phone": "TODO",
+ "student": false
+ }
+----
+
+Now edit `transform.json` to add JQ expressions and save — the output updates instantly:
+
+[source,json]
+----
+{
+ "sid": ${jq(.id)},
+ "name": "${jq(.first_name)} ${jq(.last_name)}",
+ "country": "TODO",
+ "phone": "TODO",
+ "student": false
+}
+----
+
+Output:
+
+[source,bash]
+----
+ Exchange (DefaultExchange) InOut 23F5DD4CE6C260B-0000000000000018
+ Message (DefaultMessage)
+ Body (String) (bytes: 158)
+ {
+ "sid": 9914,
+ "name": "Khalilah Monahan",
+ "country": "TODO",
+ "phone": "TODO",
+ "student": false
+ }
+----
+
+Continue editing the template until you have the desired result. Errors are shown in red with a stack trace.
+
+=== Transforming directly from a Camel route
+
+Instead of an external template, you can transform directly inside a Camel route using `--source`.
+
+NOTE: Java DSL does not support `--watch` mode (live reload on change).
+
+For example, given this beer JSON (`sample.json`):
+
+[source,json]
+----
+ {
+ "id": 2104,
+ "uid": "cefb36e1-e42f-4083-8f97-fc4ff85e56fb",
+ "brand": "Pabst Blue Ribbon",
+ "name": "St. Bernardus Abt 12",
+ "style": "Belgian Strong Ale",
+ "hop": "Amarillo",
+ "yeast": "1388 - Belgian Strong Ale",
+ "malts": "Caramel",
+ "ibu": "43 IBU",
+ "alcohol": "3.8%",
+ "blg": "16.0°Blg"
+ }
+----
+
+And a route with a `setBody` expression (starting with TODO):
+
+[source,yaml]
+----
+- route:
+ nodePrefixId: route-c38
+ id: route-66b0
+ from:
+ uri: kamelet:beer-source
+ id: from-3996
+ steps:
+ - setBody:
+ expression:
+ simple:
+ expression: >-
+ TODO
+ id: simple-b320
+ id: setBody-fa01
+ - log:
+ message: ${body}
+ id: log-0c79
+----
+
+Run the transform command against the route:
+
+[source,bash]
+----
+camel transform message --body=file:sample.json --source=beer-jq.yaml --watch --pretty
+----
+
+Initial output:
+
+[source,text]
+----
+ Exchange (DefaultExchange) InOut D9F909701338607-0000000000000004
+ Message (DefaultMessage)
+ Body (String) (bytes: 4)
+ TODO
+----
+
+Edit the expression in the route to use JQ and save — the output updates live:
+
+[source,yaml]
+----
+ expression: >-
+ {
+ "kind": "${jq(.brand)}",
+ "beer": "${jq(.name)}"
+ }
+ id: simple-b320
+----
+
+Output:
+
+[source,text]
+----
+ Exchange (DefaultExchange) InOut D9F909701338607-000000000000003E
+ Message (DefaultMessage)
+ Body (String) (bytes: 78)
+ {
+ "kind": "Pabst Blue Ribbon",
+ "beer": "St. Bernardus Abt 12"
+ }
+----
+
+Press Ctrl+C to stop.
+
+By default, `--source` picks the last expression in the route. With multiple expressions,
+specify which one by line number or EIP id:
+
+[source,bash]
+----
+camel transform message --body=file:sample.json --source=beer-jq.yaml:11 --watch --pretty
+----
+
+The line number does not need to be exact — any number within the EIP's range works. By id:
+
+[source,bash]
+----
+camel transform message --body=file:sample.json --source=beer-jq.yaml:setBody-fa01 --watch --pretty
+----
+
+You can also transform to XML or any other structure:
+
+[source,yaml]
+----
+- setBody:
+ expression:
+ simple:
+ expression: >-
+ <beer id="${jq(.id)}">
+ <name>${jq(.name)}</name>
+ <kind>${jq(.brand)}</kind>
+ </beer>
+ id: simple-b320
+ id: setBody-fa01
+----
+
+Configure language options with `--option` (repeatable):
+
+[source,bash]
+----
+$ camel transform message --body=file:sample.json --language=jsonpath --template="beer.unknown" --option=suppressExceptions=true
+----
+
+Here JSONPath would normally throw for a missing path — `suppressExceptions=true` returns null instead:
+
+[source,text]
+----
+2023-12-04 13:02:50.923 66291 --- Message transformed (success) (239ms)
+ Exchange (DefaultExchange) InOut 6118686CA3995FF-0000000000000000
+ Message (DefaultMessage)
+ Body (null) (bytes: 14)
+ [Body is null]
+----
+
+=== Transforming with Groovy
+
+Groovy is a powerful option for data transformation — its concise syntax and built-in JSON/XML
+support make it ideal for reshaping messages.
+
+Use Groovy as the expression language to transform JSON:
+
+[source,bash]
+----
+camel transform message --body=file:random.json --language=groovy --template=file:transform.groovy --pretty --watch
+----
+
+Where `transform.groovy` uses Groovy's `JsonSlurper` and `JsonBuilder`:
+
+[source,groovy]
+----
+import groovy.json.*
+
+def input = new JsonSlurper().parseText(request.body)
+def output = new JsonBuilder()
+output {
+ name "${input.first_name} ${input.last_name}"
+ country input.address.country
+ phone input.phone_number
+ student input.subscription.plan == 'Student'
+}
+output.toPrettyString()
+----
+
+Camel also provides two Groovy-based data formats for quick marshal/unmarshal without writing scripts:
+
+* `groovyJson` — transform between JSON and `Map`/`List` objects using Groovy's built-in JSON slurper and builder
+* `groovyXml` — transform between XML and Groovy `Node` objects
+
+[source,bash]
+----
+camel transform message --body=file:data.json --dataformat=groovyJson
+camel transform message --body=file:data.xml --dataformat=groovyXml
+----
+
+These data formats have minimal configuration and are convenient for quick inspection
+or when combined with Groovy expressions in a route for further manipulation.
+
+=== Using components
+
+Components like XSLT, Velocity, FreeMarker, and Thymeleaf can also be used for transformation.
+
+TIP: Run `camel catalog component --filter=transform` to list transformation-capable components.
+
+Given this XML (`sample.xml`):
+
+[source,xml]
+----
+<hash>
+ <id type="integer">1369</id>
+ <uid>8c946e1a-fdc5-40d3-9098-44271bdfad65</uid>
+ <account-number>8673088731</account-number>
+ <iban>GB38EFUA27474531363797</iban>
+ <bank-name>ABN AMRO MEZZANINE (UK) LIMITED</bank-name>
+ <routing-number>053228004</routing-number>
+ <swift-bic>AACCGB21</swift-bic>
+</hash>
+----
+
+Transform it with an XSLT stylesheet (`mystyle.xsl`):
+
+[source,xml]
+----
+<?xml version = "1.0"?>
+<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
+
+ <xsl:template match="/">
+ <bank>
+ <name><xsl:value-of select="/hash/bank-name/text()"/></name>
+ <bic><xsl:value-of select="/hash/swift-bic/text()"/></bic>
+ </bank>
+ </xsl:template>
+
+</xsl:stylesheet>
+----
+
+Run with live reload:
+
+[source,bash]
+----
+$ camel transform message --body=file:sample.xml --component=xslt --template=file:mystyle.xsl --pretty --watch
+----
+
+Configure component options with `--option` (repeatable):
+
+[source,bash]
+----
+$ camel transform message --body=file:sample.xml --component=xslt --template=file:mystyle.xsl --option=output=bytes --pretty --watch
+----
+
+NOTE: Some components require complex options that cannot be set from the command line.
+
+=== Using data formats
+
+Data formats (Base64, CSV, FlatPack, etc.) can unmarshal input into Java objects for inspection.
+
+TIP: Run `camel catalog dataformat --filter=transform` to list available data formats.
+
+Given this CSV file (`daltons.csv`):
+
+[source,text]
+----
+Jack Dalton, 115, mad at Averell
+Joe Dalton, 105, calming Joe
+William Dalton, 105, keeping Joe from killing Averell
+Averell Dalton, 80, playing with Rantanplan
+Lucky Luke, 120, capturing the Daltons
+----
+
+Unmarshal with the CSV data format:
+
+[source,bash]
+----
+$ camel transform message --body=file:daltons.csv --dataformat=csv
+----
+
+Output:
+
+[source,text]
+----
+2023-12-04 10:53:45.578 55793 --- Message transformed (success) (176ms)
+ Exchange (DefaultExchange) InOut 6673987D34F3B54-0000000000000000
+ Message (DefaultMessage)
+ Body (ArrayList) (size: 5 bytes: 224)
+ [[Jack Dalton, 115, mad at Averell], [Joe Dalton, 105, calming Joe], [William Dalton, 105, keeping Joe from killing Averell], [Averell Dalton, 80,
+ playing with Rantanplan], [Lucky Luke, 120, capturing the Daltons]]
+----
+
+The CSV data format produces an `ArrayList` — one list per row, each containing the column values.
+
+Configure data format options with `--option` (repeatable):
+
+[source,bash]
+----
+$ camel transform message --body=file:daltons.csv --dataformat=csv --option=captureHeaderRecord=true
+----
+
+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 —
+useful when working with graphical editors or code generators that target a specific DSL.
+
+For example, given this YAML route (`route.yaml`):
+
+[source, yaml]
+----
+- route:
+ id: route-b785
+ nodePrefixId: route-14b
+ from:
+ id: from-959e
+ uri: direct
+ parameters:
+ name: start
+ steps:
+ - choice:
+ id: choice-52fe
+ when:
+ - id: when-b126
+ expression:
+ simple:
+ id: simple-576d
+ expression: ${header.foo} == 'bar'
+ steps:
+ - to:
+ id: to-65f9
+ uri: jms
+ parameters:
+ destinationName: queue
+ otherwise:
+ id: otherwise-c07f
+ steps:
+ - to:
+ id: to-dc76
+ uri: log
+ parameters:
+ loggerName: default
+----
+
+Convert to XML:
+
+[source, bash]
+----
+camel transform route --format=xml /path/to/route.yaml
+----
+
+Output:
+
+[source, xml]
+----
+<camel>
+ <route id="route-b785" nodePrefixId="route-14b">
+ <from id="from-959e" uri="direct:start"/>
+ <choice id="choice-52fe">
+ <when id="when-b126">
+ <simple>${header.foo} == 'bar'</simple>
+ <to id="to-65f9" uri="jms:queue"/>
+ </when>
+ <otherwise id="otherwise-c07f">
+ <to id="to-dc76" uri="log:default"/>
+ </otherwise>
+ </choice>
+ </route>
+</camel>
+----
+
+TIP: When all input files share the same extension (e.g., `.yaml`), the target format defaults to the other DSL (XML) and vice versa.
diff --git a/docs/user-manual/modules/ROOT/pages/camel-jbang-tui.adoc b/docs/user-manual/modules/ROOT/pages/camel-jbang-tui.adoc
index 251a3650f2b8..bc77fe6ebddc 100644
--- a/docs/user-manual/modules/ROOT/pages/camel-jbang-tui.adoc
+++ b/docs/user-manual/modules/ROOT/pages/camel-jbang-tui.adoc
@@ -79,7 +79,7 @@ to any tab, or use *Tab* / *Shift+Tab* to cycle.
| 7 | Health | Health check status.
| 8 | Inspect | Message history and tracing -- step through exchanges processor by processor.
| 9 | Errors | Failures with stack traces and exchange context.
-| 0 | More | Additional tabs: Beans, Browse, Circuit Breaker, Classpath, Configuration, Consumers, Inflight, Memory, Metrics, Startup, Threads.
+| 0 | More | Additional tabs: Beans, Browse, Circuit Breaker, Classpath, Configuration, Consumers, Inflight, Memory, Metrics, Process, Spans, Startup, Threads.
|===
Tab badges show live counts -- the Errors tab shows a red badge when errors exist,
@@ -225,6 +225,39 @@ For deeper troubleshooting, switch to the Inspect tab (Tab 8) and use the diagra
This combination of error details + visual diagram replay gives you a complete picture of
what went wrong and why -- without leaving the terminal.
+== OpenTelemetry Spans
+
+The Spans tab (under More, shortcut *o*) visualizes OpenTelemetry traces collected from your
+running integration. It shows every span with trace ID, span name, kind, status, duration,
+and Camel-specific context (route ID, processor ID).
+
+Run your integration with OpenTelemetry enabled:
+
+[source,bash]
+----
+camel run my-route.yaml --dep=camel:opentelemetry
+----
+
+Features:
+
+* *Waterfall view* -- spans displayed as a timeline showing parent-child relationships
+ and duration bars, color-coded from green (fast) to red (slow)
+* *Trace grouping* -- spans grouped by trace ID so you can follow a complete request
+ across multiple routes and components
+* *Camel-only filter* -- toggle to show only Camel-originated spans, hiding framework
+ and library spans
+* *Sort and search* -- sort by trace ID, route, status, duration, or span count;
+ filter with text search
+* *Error highlighting* -- failed spans (status ERROR) are highlighted in red
+
+This is especially useful for understanding latency in multi-route integrations and for
+correlating Camel processing with external service calls (HTTP, database, messaging).
+
+== Process Information
+
+The Process tab (under More, shortcut *p*) shows JVM process details for the selected
+integration: Java version, PID, uptime, command-line arguments, and system properties.
+
== Actions Menu (F2)
Press *F2* to open the actions menu with quick access to common operations:
diff --git a/docs/user-manual/modules/ROOT/pages/camel-jbang.adoc b/docs/user-manual/modules/ROOT/pages/camel-jbang.adoc
index 328d569dba8d..6bf7f66f5988 100644
--- a/docs/user-manual/modules/ROOT/pages/camel-jbang.adoc
+++ b/docs/user-manual/modules/ROOT/pages/camel-jbang.adoc
@@ -1,4762 +1,157 @@
= Camel CLI
-The Camel CLI is used for easily running Camel routes and managing Camel projects.
-Camel CLI is powered by https://www.jbang.dev/[JBang].
+The Camel CLI is the command-line interface for Apache Camel.
+It gives you a complete, terminal-native development environment for building integrations
+-- from a first prototype to a production-ready project -- without requiring an IDE, a Maven project,
+or boilerplate code.
-== Installation
+Write a route in YAML, Java, or XML. Run it. Debug it. Trace messages flowing through it.
+Spin up the infrastructure it needs. Export it to Spring Boot or Quarkus when you are ready.
+All from the terminal.
-First, you must install https://www.jbang.dev/[JBang], which is used for launching Camel.
-See instructions on https://www.jbang.dev/download/[JBang] how to download and install.
+== Why Camel CLI
-After JBang is installed, you can verify JBang is working by executing the following command from a command shell:
+*Zero-to-running in seconds.*
+Create and run an integration in three commands -- no project skeleton, no POM file, no IDE.
+The CLI auto-detects the Camel components your route needs and downloads them on the fly.
-[source,bash]
-----
-jbang version
-----
-
-Which should output the version of JBang.
-
-To make it easier to use Camel CLI, then install the following:
-
-[source,bash]
-----
-jbang app install camel@apache/camel
-----
-
-This will install Apache Camel as the `camel` command within JBang, meaning that you can run Camel from the command line
-by just executing `camel` (see more next).
-
-Note: It requires access to the internet, in case of using a proxy, please ensure that the proxy is configured for your system.
-If Camel CLI is not working with your current configuration,
-please look to https://www.jbang.dev/documentation/jbang/latest/configuration.html#proxy-configuration[Proxy configuration in JBang documentation].
-
-=== Installing without JBang
-
-It is also possible to install and run Camel CLI without _JBang_ using the xref:camel-jbang-launcher.adoc[Camel CLI Launcher] which essentially is
-a standard Java _fat-jar_ with launch scripts.
-
-=== Installing a specific Camel CLI version
-
-By default, Camel CLI installs the latest release, which may not be the desired version.
-
-To use a specific version then you need to provide these when installing from jbang such as 4.14.1:
-
-[source,bash]
-----
-jbang app install --force --fresh -Dcamel.jbang.version=4.14.1 -Dcamel-kamelets.version=4.14.1 camel@apache/camel
-----
-
-TIP: You can use `--force` and `--fresh` to tell JBang to force installing the version and refresh downloading,
-so no previous downloaded cache etc. may cause a problem.
-
-IMPORTANT: From Camel 4.17 onwards then Kamelets are optional, and only downloaded on demand. You define the version
-of kamelets via `--kamelets-version` parameter to `camel run` or can pre-configure the version via `camel config set kamelets-version=4.17.0`.
-
-=== Installing Offline-Safe or Version-Pinned Camel CLI
-
-When installing Camel CLI using `jbang app install`, JBang will occasionally check
-upstream sources and update the installed application automatically. This may be undesirable if you
-want to ensure your Camel CLI installation remains on a specific Camel release.
-
-The following options allow you to install Camel CLI in a way that prevents unexpected upgrades.
-
-==== Option 1: Pin by Installing from a Local `CamelJBang.java`
-
-This approach pins the Camel version directly in the source file used to install the application.
-
-1. Download the `CamelJBang.java` file to your local machine:
-+
-[source]
-----
-https://github.com/apache/camel/blob/main/dsl/camel-jbang/camel-jbang-main/dist/CamelJBang.java
-----
-
-2. Edit the `CamelJBang.java` file and set the Camel version you want to use.
-
-3. Install Camel CLI locally:
-+
-[source,bash]
-----
-jbang app install CamelJBang.java
-----
-
-4. After installation, the `CamelJBang.java` file can be deleted.
-
-==== Option 2: Install from a Version-Pinned Catalog
-
-Another option is to install Camel CLI from a catalog tied to a specific Camel release tag.
-
-Example:
-[source,bash]
-----
-CAMEL_VERSION="4.18.0"
-CAMEL_TAG="camel-${CAMEL_VERSION}"
-CAMEL_JBANG_CATALOG_URL="https://raw.githubusercontent.com/apache/camel/${CAMEL_TAG}/jbang-catalog.json"
-
-jbang app install --force --fresh \
- -Dcamel.jbang.version="${CAMEL_VERSION}" \
- -Dcamel-kamelets.version="${CAMEL_VERSION}" \
- camel@"${CAMEL_JBANG_CATALOG_URL}"
-----
-
-In this example:
-
-* The catalog URL points to a specific Camel release tag.
-* `-Dcamel.jbang.version` ensures the installed application uses that same Camel version.
-
-[NOTE]
-====
-Option 1 provides the most deterministic installation and is best suited for fully offline-safe environments.
-
-Option 2 offers a simpler installation while still ensuring the version is pinned to a specific Camel release.
-====
-
-==== Option 3: Use Camel Launcher
-
-See xref:camel-jbang-launcher.adoc[Camel CLI Launcher]
-
-
-== Container Image
-
-There is also a container image available in https://hub.docker.com/r/apache/camel-jbang/[Dockerhub]
-
-[source,bash]
-----
-docker pull apache/camel-jbang:4.4.0
-----
-
-or
-
-[source,bash]
-----
-podman pull apache/camel-jbang:4.4.0
-----
-
-Once you have the image in your local registry, you can run all the commands listed below by simple doing:
-
-[source,bash]
-----
-docker run apache/camel-jbang:4.4.0 version
-----
-
-or
-
-[source,bash]
-----
-podman run apache/camel-jbang:4.4.0 version
-----
-
-This will print the following result:
-
-[source,bash]
-----
-Camel CLI version: 4.4.0
-----
-
-So running a simple route will be as easy as doing the following:
-
-[source,bash]
-----
-docker run -v .:/integrations apache/camel-jbang:4.4.0 run /integrations/example.yaml
-----
-
-or
-
-[source,bash]
-----
-podman run -v .:/integrations apache/camel-jbang:4.4.0 run /integrations/example.yaml
-----
-
-== Using Camel CLI
-
-The Camel CLI supports multiple commands. Running the command below will print all of them:
-
-[source,bash]
-----
-camel --help
-----
-
-TIP: The first time you run this command, it may cause dependencies to be cached, therefore taking a few extra seconds to run. If you are already using JBang and you get first time to run errors such as `Exception in thread "main" java.lang.NoClassDefFoundError: "org/apache/camel/dsl/jbang/core/commands/CamelJBangMain"` you may try clearing the JBang cache and re-install again.
-
-All the commands support the `--help` and will display the appropriate help if that flag is provided.
-
-TIP: For a complete reference of all commands and their options, see the xref:jbang-commands/camel-jbang-commands.adoc[Camel CLI Command Reference].
-
-=== Enable shell completion
-
-Camel CLI provides shell completion for bash and zsh out of the box. To enable shell completion for Camel CLI, run:
-
-[source,bash]
-----
-source <(camel completion)
-----
-
-To make it permanent, run:
-
-[source,bash]
-----
-echo 'source <(camel completion)' >> ~/.bashrc
-----
-
-== REPL loop
-
-A simple read-eval-print loop is available, you can launch it with:
-
-[source, bash]
-----
-camel shell
-----
-
-== Creating and running Camel routes
-
-You can create a new basic routes with the `init` command.
-
-For example, to create an XML route, you can run:
-
-[source,bash]
-----
-camel init cheese.xml
-----
-
-Which creates the file `cheese.xml` (in the current directory) with a sample route.
-
-To run the file, you do:
-
-[source,bash]
-----
-camel run cheese.xml
-----
-
-NOTE: You can create and run any of the supported xref:dsl.adoc[DSLs] in Camel such as YAML, XML, Java, Groovy.
-
-To create a new .java route, you simply do:
-
-[source,bash]
-----
-camel init foo.java
-----
-
-When using the init command, then Camel will by default create the file in the current directory.
-However, you can use
-the `--directory` option to create the file in the specified directory.
-For example, to create in a folder
-named `_foobar_` you can do:
-
-[source,bash]
-----
-camel init foo.java --directory=foobar
-----
-
-=== Running Routes from multiple files
-
-You can run more than one file, for example, to run two YAML files you can do:
-
-[source,bash]
-----
-camel run one.yaml two.yaml
-----
-
-You can also mix different xref:dsl.adoc[DSLs] such as YAML and Java:
-
-[source,bash]
-----
-camel run one.yaml hello.java
-----
-
-You can also use wildcards (i.e. `*`) to match multiple files, such as running all the YAML files:
-
-[source,bash]
-----
-camel run *.yaml
-----
-
-Or you can run all files starting with foo*
-
-[source,bash]
-----
-camel run foo*
-----
-
-And to run everything
-
-[source,bash]
-----
-camel run *
-----
-
-TIP: The run goal can also detect files that are `properties`, such as `application.properties`.
-
-=== Running a Maven based project
-
-Camel CLI is intended for flat-file-based projects, where you run small integrations.
-However, Camel CLI may be used as a tool for migrating existing Maven based projects.
-To make the migration easier, then JBang can do _best effort_ to run, export, or transform these projects.
-
-For example, if you have a Maven-based project, you can execute
-
-[source,bash]
-----
-camel run pom.xml
-----
-
-Camel CLI will then scan in `src/main/java` and `src/main/resources` for files to include (recursive).
-
-NOTE: Using `camel run pom.xml` is not intended as a fully compatible way of running an existing Maven-based project. It cannot start Quarkus or Spring Boot applications; instead, use the proper plugins/commands. The command is mainly used to migrate from old projects.
-
-=== Running Route with user interactive prompt for placeholder values
-
-You can create Camel integrations that makes it possible for the user to quickly enter placeholder values from command prompt.
-
-For example, given the following route:
-
-[source,java]
-----
-import org.apache.camel.builder.RouteBuilder;
-
-public class foo extends RouteBuilder {
-
- @Override
- public void configure() throws Exception {
- from("timer:java?period={{time:1000}}")
- .setBody()
- .simple("Hello Camel from {{you}}")
- .log("${body}");
- }
-}
-----
-
-Then if you run this with:
-
-[source,bash]
-----
-camel run foo.java
-----
-
-You will have an exception on startup about the missing value
-[source,text]
-----
-Caused by: java.lang.IllegalArgumentException: Property with key [you] not found in properties from text: Hello Camel from {{you}}`
-----
-
-However, you can then run in prompt mode as follows:
-
-[source,bash]
-----
-camel run foo.java --prompt
-----
-
-And Camel will now prompt in the terminal for you to enter values for the placeholders:
-
-[source,bash]
-----
-2023-12-15 21:46:44.218 INFO 15033 --- [ main] org.apache.camel.main.MainSupport : Apache Camel (JBang) 4.7.0 is starting
-2023-12-15 21:46:44.331 INFO 15033 --- [ main] org.apache.camel.main.MainSupport : Using Java 17.0.5 with PID 15033. Started by davsclaus in /Users/davsclaus/workspace/deleteme/prompt
-2023-12-15 21:46:45.360 INFO 15033 --- [ main] mel.cli.connector.LocalCliConnector : Management from Camel CLI enabled
-Enter optional value for time (1000):
-Enter required value for you: Jack
-2023-12-15 21:46:55.239 INFO 15033 --- [ main] el.impl.engine.AbstractCamelContext : Apache Camel 4.7.0 (foo) is starting
-2023-12-15 21:46:55.323 INFO 15033 --- [ main] g.apache.camel.main.BaseMainSupport : Property-placeholders summary
-2023-12-15 21:46:55.323 INFO 15033 --- [ main] g.apache.camel.main.BaseMainSupport : [prompt] you=Jack
-2023-12-15 21:46:55.341 INFO 15033 --- [ main] el.impl.engine.AbstractCamelContext : Routes startup (started:1)
-----
-
-From the snippet above, Camel CLI had two prompts. First for the `time` which has a default value of `1000` so you can just press ENTER to accept the default value.
-And for `you` a value must be entered, and we entered `Jack` in this example.
-
-You may want to use this for Camel prototypes where you want the user to be able to enter custom values quickly.
-Those values can of course be pre-configured in `application.properties` as well.
-
-=== Running Route from input parameter
-
-For very small Java routes then it is possible to provide the route as CLI argument, as shown below:
-
-[source,bash]
-----
-camel run --code='from("kamelet:beer-source").to("log:beer")'
-----
-
-This is very limited as the CLI argument is a bit cumbersome to use than files.
-
-- Java DSL code is only supported
-- Code wrapped in single quote, so you can use double quote in Java DSL
-- Code limited to what literal values possible to provide from the terminal and JBang.
-- All route(s) must be defined in a single `--code` parameter.
-
-NOTE: Using `--code` is only usable for very quick and small prototypes.
-
-From *Camel 4.7* onwards the `--code` parameter can also refer to a `.java` source file,
-that are not wrapped in a `public class` which makes it possible to quickly try a prototype
-with some Camel java based routes such as the following stored in a file named `quick.java`:
-
-[source,java]
-----
-from("timer:java?period=1000")
- .setBody()
- .simple("Hello Quick Camel from ${routeId}")
- .log("${body}");
-----
-
-Then you can run this route via:
-
-[source,bash]
-----
-camel run --code=quick.java
-----
-
-NOTE: You cannot use `--dev` to hot-reload this on code changes.
-
-=== Running Routes from source directory
-
-You can also run dev mode when running Camel with `--source-dir`, such as:
-
-[source,bash]
-----
-camel run --source-dir=mycode
-----
-
-This starts Camel where it will load the files from the _source dir_ (also subfolders).
-
-=== Stub components that should not be active
-
-Sometimes you need to troubleshoot an existing integration and is given some Camel code (routes).
-These routes may use different components, and those components may be tricky to run as they are configured
-in a custom way, or need connection to servers you may not have access to.
-
-You can run Camel CLI by stubbing those components (or all of them).
-
-For example, suppose you need access to a JMS broker in the given route below.
-
-[source,java]
-----
-from("jms:inbox")
- .log("Incoming order")
- .to("bean:transform")
- .log("After transformation")
- .to("jms:process");
-----
-
-Then you can run this by stub the `jms` component by:
-
-[source,bash]
-----
-camel run syncToDatabase.java --stub=jms
-----
-
-Then Camel will not start up the JMS component but replace it with the `stub` component, but keep the actual endpoint URIs.
-
-You can then simulate sending messages to Camel with the `cmd send` command:
-
-[source,bash]
-----
-camel cmd send --body='Something here'
-----
-
-Which then will send the message to the incoming endpoint in the route, i.e. `jms:inbox` which has been stubbed.
-
-You can also stub a specific endpoint by providing the full uri, such as:
-
-[source,bash]
-----
-camel run syncToDatabase.java --stub=jms:inbox
-----
-
-Then only the `jms:inbox` endpoint is stubbed.
-
-TIP: You can stub multiple components separated by comma, such as `--stub=jms,sql`
-
-You can also use `--stub=all` to stub all components, or `--stub=remote` to stub only
-remote components (components that connect to external systems such as messaging brokers, databases, cloud services, etc.).
-The `remote` flag uses the Camel catalog to determine which components are remote, so it automatically
-handles new components without needing a hardcoded list.
-
-[source,bash]
-----
-camel run syncToDatabase.java --stub=remote
-----
-
-Camel CLI comes with the `camel cmd stub` command that allows to list all endpoints that
-has been stubbed, and also browse any messages that are currently present in their internal queues.
-A stub endpoint is based on the `seda` component.
-
-[source,bash]
-----
-camel cmd stub
-----
-
-And to browse the messages:
-
-[source,bash]
-----
-camel cmd stub --browse
-----
-
-=== Dev mode with live reload
-
-You can enable dev mode that comes with live reload of the route(s) when the source file is updated (saved),
-using the `--dev` options as shown:
-
-[source,bash]
-----
-camel run foo.yaml --dev
-----
-
-Then, while the Camel integration is running, you can update the YAML route and update when saving.
-
-This works for all DSLs, even java, so you can do:
-
-[source,bash]
-----
-camel run hello.java --dev
-----
-
-NOTE: The live reload is meant for development purposes, and if you encounter problems with reloading
-such as JVM class loading issues, then you may need to restart the integration. Java files cannot
-be supported in Spring Boot runtime since they have to be recompiled to trigger a restart.
-
-You can also run dev mode when running Camel with `--source-dir`, such as:
-
-[source,bash]
-----
-camel run --source-dir=mycode --dev
-----
-
-This starts Camel where it will load the files from the _source dir_ (also subfolders).
-And in _dev mode_ then you can add new files, update existing files, and delete files, and Camel
-will automatically hot-reload on the fly.
-
-Using _source dir_ is more flexible than having to specify the files in the CLI as shown below:
-
-[source,bash]
-----
-camel run mycode/foo.java mycode/bar.java --dev
-----
-
-In this situation, then Camel will only watch and reload these two files (foo.java and bar.java).
-So, for example, if you add a new file cheese.xml, then this file is not reloaded. On the other hand,
-if you use `--source-dir` then any files in this directory (and subfolders) are automatic detected
-and reloaded. You can also delete files to remove routes.
-
-NOTE: You cannot use both files and source dir together.
-The following is not allowed: `camel run abc.java --source-dir=mycode`.
-
-==== Live reload of resource files
-
-When `--dev` is used, Camel also disables `contentCache` on resource-based components (such as
-`xslt`) whose default is `true`, so that edits to resource files are picked up on the next message
-without having to restart the route.
-
-This is driven by `camel.main.routesReloadEnabled` (set automatically by `--dev`). User properties
-(e.g. `camel.component.xslt.contentCache=true`) and explicit endpoint/URI settings are always
-respected: set `contentCache=true` to keep caching even in dev mode.
-
-==== Loading new routes into existing Camel
-
-*Available as of Camel 4.17*
-
-The `camel cmd load` command can be used to load new route(s) into an existing running Camel CLI application.
-For example during development to inject a new route for experimentation. This can also be used as part
-of testing scenarios using Citrus with the xref:camel-jbang-test.adoc[Camel CLI Test] plugin.
-
-For example to load `bar.java` route into a Camel application:
-
-[source,bash]
-----
-camel cmd load --source=bar.java
-----
-
-You can load any of the DSLs such as Java, XML, or YAML.
-
-IMPORTANT: Assign _ids_ to your routes so the `load` command would detect a previous loaded route (when you update),
-to avoid adding the same route as a duplicate.
-
-TIP: There is a `--restart` option to tell Camel to restart all routes after the new route is loaded.
-
-==== Uploading files to source directory via HTTP
-
-When running Camel CLI with `--source-dir`, `--console` and `--dev` (reloading) then you can
-change the source files on-the-fly by copying, modifying or deleting the files in the source directory.
-
-This can also be done via HTTP using the `q/upload/:filename` HTTP endpoint using PUT and DELETE verbs.
-
-Suppose that you run Camel CLI with:
-
-[source,bash]
-----
-camel run --source-dir=mycode --console --dev
-----
-
-Then you can upload or modify a source file named `bar.java` you can send a PUT request via curl:
-
-[source,bash]
-----
-curl -X PUT http://0.0.0.0:8080/q/upload/bar.java --data-binary "@bar.java"
-----
-
-Or via:
-
-[source,bash]
-----
-curl -T bar.java http://0.0.0.0:8080/q/upload/bar.java
-----
-
-To send the data via PUT, then the file body can be included when using `Content-Type: application/x-www-form-urlencoded`:
-
-For example, from a CURL `--trace-ascii log.txt`:
-
-[source,text]
-----
-0000: PUT /q/upload/bar.java HTTP/1.1
-0021: Host: 0.0.0.0:8080
-0035: User-Agent: curl/7.87.0
-004e: Accept: */*
-005b: Content-Length: 385
-0070: Content-Type: application/x-www-form-urlencoded
-00a1:
-=> Send data, 385 bytes (0x181)
-0000: // camel-k: language=java..import org.apache.camel.builder.Route
-0040: Builder;..public class bar extends RouteBuilder {.. @Override
-0080: . public void configure() throws Exception {.. // Writ
-00c0: e your routes here, for example:. from("timer:java?period
-0100: ={{time:1000}}"). .setBody(). .simple(
-0140: "XXXCamel from ${routeId}"). .log("${body}");. }.}
-0180: .
-== Info: Mark bundle as not supporting multiuse
-<= Recv header, 17 bytes (0x11)
-0000: HTTP/1.1 200 OK
-<= Recv header, 19 bytes (0x13)
-0000: content-length: 0
-<= Recv header, 2 bytes (0x2)
-0000:
-== Info: Connection #0 to host 0.0.0.0 left intact
-----
-
-To delete one or more files, you use the DELETE verb, such as:
-
-[source,bash]
-----
-curl -X DELETE http://0.0.0.0:8080/q/upload/bar.java
-----
-
-You can also use wildcards ('*') to delete all .java files:
-
-[source,bash]
-----
-curl -X DELETE http://0.0.0.0:8080/q/upload/*.java
-----
-
-Or to delete everything
-
-[source,bash]
-----
-curl -X DELETE http://0.0.0.0:8080/q/upload/*
-----
-
-=== Developer Console
-
-You can enable the developer console, which presents a variety of information to the developer.
-
-[source,bash]
-----
-camel run hello.java --console
-----
-
-The console is then accessible from a web browser at: http://localhost:8080/q/dev (by default).
-The link is also shown in the log when Camel is starting up.
-
-The console can give you insights into your running Camel integration, such as reporting the top
-routes that takes the longest time to process messages. You can then drill down to pinpoint exactly
-which individual EIPs in these routes are the slowest.
-
-The developer console can also output the data in JSON format, which, for example, can be used by 3rd-party tooling
-to scrape the information.
-
-For example, to output the top routes via curl, you can execute:
-
-[source,bash]
-----
-curl -s -H "Accept: application/json" http://0.0.0.0:8080/q/dev/top/
-----
-
-And if you have `jq` installed which can format and output the JSON data in color, then do:
-
-[source,bash]
-----
-curl -s -H "Accept: application/json" http://0.0.0.0:8080/q/dev/top/ | jq
-----
-
-=== Using properties
-
-To set properties when running a route, you can use the `--property` or `--properties` parameter from `camel run` command:
-
-* `--property`: sets individual parameters, example: `--property=my-key=my-value`, you have to add more `--property` in case you need more parameters.
-* `--properties`: loads a properties file from the local filesystem, example: `--properties=/var/my-app/config.properties`.
-
-NOTE: You have to use the `=` sign right after the `--property`, as in the examples above.
-
-If both parameters are used, the properties will be merged in a single `application.properties` file.
-
-=== History of last completed message
-
-*Available from Camel 4.17*
-
-When developers are coding Camel using the high level DSL with EIPs and components then it can appear as a mystery box what happened when Camel processed an incoming message. There are of course many ways to find out with logging, tracing, debugging, and good old System.out.println.
-
-In Camel 4.17 there is the `camel get history` command that show a summary of the last completed message of every step of the message; with a column that shows curanted important information. This is a high level summary to quickly allow users to see what happened.
-
-For example the following `foo.java` source file contains a Camel route that consumes a file, split the file line by line, and filter if the line contains world. After the split then calls a non-existing page on the Camel website, and then logs at the end.
-
-[source,java]
-----
-import org.apache.camel.builder.RouteBuilder;
-
-public class foo extends RouteBuilder {
-
- @Override
- public void configure() throws Exception {
- from("file:inbox?noop=true")
- .log("Incoming file")
- .split(body().tokenize("\n"))
- .filter(body().contains("world"))
- .log("Stop the world")
- .stop()
- .end()
- .to("log:line")
- .end()
- .to("https://camel.apache.org/xxx?throwExceptionOnFailure=false")
- .to("log:after-http")
- .log("complete");
- }
-}
-----
-
-And the file contains 4 lines:
-
-[source,text]
-----
-hello
-world
-from
-me
-----
-
-And when you execute the `camel get history` you would see:
-
-[source,bash]
-----
-$ camel get history --source
-Message History of last completed (id:32E020F6050C165-0000000000000000 status:success ago:4s pid:91133 name:foo)
- ID PROCESSOR ELAPSED EXCHANGE
- *--> foo.java:7 from[file://inbox?noop=true] 0 0000 File: foo.txt (19 bytes)
- foo.java:8 log[Incoming file] 0 0000
- foo.java:9 split[tokenize(body, \n)] 8 0000 Split (4)
- foo.java:10 filter[{body contains world}] 0 0001/0000 Filter: false
- foo.java:14 to[log:line] 0 0001/0000
- foo.java:10 filter[{body contains world}] 0 0002/0000 Filter: true
- foo.java:11 log[Stop the world] 0 0002/0000
- foo.java:12 stop 0 0002/0000
- foo.java:10 filter[{body contains world}] 0 0003/0000 Filter: false
- foo.java:14 to[log:line] 0 0003/0000
- foo.java:10 filter[{body contains world}] 0 0004/0000 Filter: false
- foo.java:14 to[log:line] 0 0004/0000
- foo.java:16 to[https:\/\/camel.apache.org\/xxx?throwExceptionO… 143 0000 404=Not Found Content-Type=text/html; charset=utf-8
- foo.java:17 to[log:after-http] 1 0000
- foo.java:18 log[complete] 0 0000
- *<-- foo.java:7 from[file://inbox?noop=true] 157 0000 Success
-----
-
-The history command shows what happened and as you can see we are able to show that the there are 4 entries in the Split, and also how each splitted message has its own unique exchange id, that links to the parent exchange id. Also notice how the HTTP call we can see the 404 error code, and the response body is in text/plain.
-
-==== Interactive mode with full message history details
-
-The `camel get history` command can be used in _interactive mode_ via `camel get history --it` which shows
-more detailed information for each step. (similar screen like `camel debug`). This allows you to see the content
-of the message including message headers, body, etc.
-
-You can then go forward (press ENTER), or go back (press P + ENTER).
-
-TIP: Use `camel get history --help` to see all available options.
-
-
-[#_using_profiles]
-=== Using profiles
-
-*Available from Camel 4.5*
-
-Camel CLI comes with three sets of profiles
-
-- `dev`:for development (default)
-- `test`:for testing (currently same as production)
-- `prod`:for production
-
-The developer profile will pre-configure Camel CLI with a number of developer assisted features when
-running Camel. For example, tracing messages during routing, additional metrics collected, and more.
-This is useful during development and also enhanced the Camel CLI CLI tool.
-
-However, you may want to run Camel CLI in a production-like scenario, which you can do with:
-
-[source,bash]
-----
-camel run hello.java --profile=prod
-----
-
-You can have profile-specific configuration in configuration files using the naming style `application-<profile>.properties`,
-such as in the following:
-
-- `application.properties`: common configuration that is always in use (default).
-- `application-dev.properties`: developer specific configuration for the `dev` profile.
-- `application-prod.properties`: developer specific configuration for the `prod` profile.
-
-The profile-specific configuration will override values in the common configuration.
-
-NOTE: Since Camel 4.21, the `camel run` and `camel export` commands auto-detect `application.properties`
-(and profile-specific variants such as `application-prod.properties`) in the current directory.
-You no longer need to list them explicitly on the command line.
-
-
-=== Downloading JARs over the internet
-
-By default, Camel CLI will automatically resolve dependencies needed to run Camel, which is done
-by JBang and Camel respectively. Camel itself detects at runtime if a component has a need for JARs that
-are not currently available on the classpath, and can then automatically download the JARs (incl transitive).
-
-Camel will download these JARs in the following order:
-
-1. from local disk in `~/.m2/repository`
-2. from the internet in Maven Central
-3. from the internet from custom third-party Maven repositories
-4. from all the repositories found in active profiles of `~/.m2/settings.xml` or a settings file specified using
-`--maven-settings` option.
-
-If you do not want Camel CLI to download over the internet, you can turn this off with `--download`, as shown below:
-
-[source,bash]
-----
-camel run foo.java --download=false
-----
-
-If you do not want Camel CLI to use your existing Maven settings file, you can use:
-
-[source,bash]
-----
-camel run foo.java --maven-settings=false
-----
-
-[#_adding_custom_jars]
-=== Adding custom JARs
-
-Camel CLI will automatically detect dependencies for Camel components, languages, data formats, etc. that
-from its own release. This means you often do not have to specify which JARs to use.
-
-However, if you need to add 3rd-party custom JARs, then you can specify these with `--dep` as CLI argument in Maven
-GAV syntax (`groupId:artifactId:version`), such as:
-
-[source,bash]
-----
-camel run foo.java --dep=com.foo:acme:1.0
-----
-
-In case you need to explicit add a Camel dependency you can use a shorthand syntax (starting with `camel:` or `camel-`)
-such as:
-
-[source,bash]
-----
-camel run foo.java --dep=camel-saxon
-----
-
-You can specify multiple dependencies separated by comma:
-
-[source,bash]
-----
-camel run foo.java --dep=camel-saxon,com.foo:acme:1.0
-----
-
-=== Using 3rd-party Maven repositories
-
-Camel CLI will download from local repository first, and then online from Maven Central.
-To be able to download from 3rd-party Maven repositories then you need to specify this as CLI argument,
-]or in `application.properties`
-
-[source,bash]
-----
-camel run foo.java --repos=https://packages.atlassian.com/maven-external
-----
-
-TIP: Multiple repositories can be separated by comma
-
-The configuration for the 3rd-party Maven repositories can also be configured in `application.properties`
-with the key `camel.jbang.repos` as shown:
-
-[source,properties]
-----
-camel.jbang.repos=https://packages.atlassian.com/maven-external
-----
-
-Alternatively, you can configure default Maven repositories globally via a system property.
-This is useful for custom Camel distributions that require additional repositories without manual configuration on each command:
-
-[source,bash]
-----
-export JAVA_TOOL_OPTIONS="-Dcamel.extra.repos=repo1=https://repo1.example.com/maven2,repo2=https://repo2.example.com/releases"
-----
-
-When running Camel, `application.properties` in the current directory is auto-detected and included.
-You can also pass it explicitly if needed:
-
-[source,bash]
-----
-camel run foo.java application.properties
-----
-
-=== Configuration of Maven usage
-
-By default, existing `~/.m2/settings.xml` file is loaded, so it is possible to alter the behaviour of Maven resolution
-process. Maven settings file can provide information about Maven mirrors, credential configuration (potentially
-encrypted) or active profiles, and additional repositories.
-
-Maven repositories can use authentication and the Maven-way to configure credentials is through `<server>` elements,
-like this:
-
-[source,xml]
-----
-<server>
- <id>external-repository</id>
- <username>camel</username>
- <password>{SSVqy/PexxQHvubrWhdguYuG7HnTvHlaNr6g3dJn7nk=}</password>
-</server>
-----
-
-While the password may be specified using plain text, it's better to configure maven master password first and then
-use it to configure repository password:
-
-[source,bash]
-----
-$ mvn -emp
-Master password: camel
-{hqXUuec2RowH8dA8vdqkF6jn4NU9ybOsDjuTmWvYj4U=}
-----
-
-The above password should be added to `~/.m2/settings-security.xml` file like this:
-
-[source,xml]
-----
-<settingsSecurity>
- <master>{hqXUuec2RowH8dA8vdqkF6jn4NU9ybOsDjuTmWvYj4U=}</master>
-</settingsSecurity>
-----
-
-Then a normal password can be configured like this:
-
-[source,bash]
-----
-$ mvn -ep
-Password: camel
-{SSVqy/PexxQHvubrWhdguYuG7HnTvHlaNr6g3dJn7nk=}
-----
-
-Finally, such passwords can be used in `<server>/<password>` configuration.
-
-By default, Maven reads the master password from `~/.m2/settings-security.xml` file, but we can override it.
-The location of the `settings.xml` file itself can be specified as well:
-
-[source,bash]
-----
-camel run foo.java --maven-settings=/path/to/settings.xml --maven-settings-security=/path/to/settings-security.xml
-----
-
-If you want to run Camel application without assuming any location (even `~/.m2/settings.xml`), use this option:
-
-[source,bash]
-----
-camel run foo.java --maven-settings=false
-----
-
-
-=== Running routes hosted on GitHub
-
-You can run a route hosted on GitHub using Camels xref:components:others:resourceresolver-github.adoc[GitHub] resource loader.
-
-For example, to run one of the Camel Kamelets examples, you can do:
-
-[source,bash]
-----
-camel run github:apache:camel-kamelets-examples:jbang/hello-java/Hey.java
-----
-
-You can also use the `https` URL for GitHub. For example, you can browse the examples from a web-browser and
-then copy the URL from the browser window and run the example with Camel CLI:
-
-[source,bash]
-----
-camel run https://github.com/apache/camel-kamelets-examples/tree/main/jbang/hello-java
-----
-
-You can also use wildcards (i.e. `*`) to match multiple files, such as running all the groovy files:
-
-[source,bash]
-----
-camel run https://github.com/apache/camel-kamelets-examples/tree/main/jbang/languages/*.groovy
-----
-
-Or you can run all files starting with rou*
-
-[source,bash]
-----
-camel run https://github.com/apache/camel-kamelets-examples/tree/main/jbang/languages/rou*
-----
-
-==== Running routes from GitHub gists
-
-Using gists from GitHub is a quick way to share small Camel routes that you can easily run.
-
-For example, to run a gist, you can execute:
-
-[source,bash]
-----
-camel run https://gist.github.com/davsclaus/477ddff5cdeb1ae03619aa544ce47e92
-----
-
-A gist can contain one or more files, and Camel CLI will gather all relevant files, so a gist
-can contain multiple routes, properties files, Java beans, etc.
-
-=== Downloading routes hosted on GitHub
-
-We have made it easy for Camel CLI to download existing examples from GitHub to local disk,
-which allows for modifying the example and to run locally.
-
-All you need to do is to copy the https link from the web browser.
-For example, you can download the _dependency injection_ example by:
-
-[source,bash]
-----
-camel init https://github.com/apache/camel-kamelets-examples/tree/main/jbang/dependency-injection
-----
-
-Then the files (not subfolders) are downloaded to the current directory.
-The example can then be run locally with:
-
-[source,bash]
-----
-camel run *
-----
-
-You can also download to a new folder using the `--directory` option, for example, to download to a folder named _myproject_,
-you would do:
-
-[source,bash]
-----
-camel init https://github.com/apache/camel-kamelets-examples/tree/main/jbang/dependency-injection --directory=myproject
-----
-
-You can also run in dev mode, to hot-deploy on source code changes.
-
-[source,bash]
-----
-camel run * --dev
-----
-
-You can also download a single file, such as one of the Camel Kamelets examples:
-
-[source,bash]
-----
-camel init https://github.com/apache/camel-kamelets-examples/blob/main/jbang/hello-yaml/hello.camel.yaml
-----
-
-This is a groovy route, which you can run with (or use `*`):
-
-[source,bash]
-----
-camel run simple.groovy
-----
-
-==== Downloading routes form GitHub gists
-
-You can also download files from gists easily as shown:
-
-[source,bash]
-----
-camel init https://gist.github.com/davsclaus/477ddff5cdeb1ae03619aa544ce47e92
-----
-
-This will then download the files to local disk, which you can run afterward:
-
-[source,bash]
-----
-camel run *
-----
-
-You can also download to a new folder using the `--directory` option, for example, to download to a folder named _foobar_,
-you would do:
-
-[source,bash]
-----
-camel init https://gist.github.com/davsclaus/477ddff5cdeb1ae03619aa544ce47e92 --directory=foobar
-----
-
-=== Using a specific Camel version
-
-You can specify which Camel version to run as shown:
-
-[source,bash]
-----
-jbang -Dcamel.jbang.version=3.18.4 camel@apache/camel [command]
-----
-
-NOTE: Older versions of Camel may not work as well with Camel CLI as the newest versions.
-Starting from Camel 3.20 onwards are the versions that are recommended to be used onwards.
-
-TIP: In Camel *3.20.3* onwards there is a `version` command, see the following section for more details.
-
-In *Camel 3.20.2* onwards the `run` command has built-in support, using `--camel-version`,
-for specifying the Camel version to use for the running Camel integration.
-
-[source,bash]
-----
-camel run * --camel-version=3.18.4
-----
-
-TIP: This makes it easy to try different Camel versions, for example, when you need to reproduce an issue,
-and find out how it works in a different Camel version.
-
-You can also try bleeding-edge development by using SNAPSHOT such as:
-
-[source,bash]
-----
-jbang --fresh -Dcamel.jbang.version=3.21.0-SNAPSHOT camel@apache/camel [command]
-----
-
-=== Using the version command
-
-In *Camel 3.20.3* onwards the `version` command makes it possible to configure a specific version
-of Camel to use when running or exporting. This makes it possible to use the latest Camel CLI CLI
-and run integrations using an older Camel version.
-
-[source,bash]
-----
-camel version
-Camel CLI version: 3.20.3
-----
-
-Here Camel CLI is using version 3.20.3. Now suppose we want to run Camel integrations with version 3.18.2.
-
-[source,bash]
-----
-camel version set 3.18.2
-----
-
-And you can see what Camel version has been set by:
-
-[source,bash]
-----
-camel version
-Camel CLI version: 3.20.3
-User configuration:
- camel-version = 3.18.2
-----
-
-And when running an integration, then Camel CLI will show you the _overridden version_ when starting.
-
-[source,bash]
-----
-camel run foo.java
-Running integration with the following configuration:
- --camel-version=3.18.2
-2023-03-17 13:35:13.876 INFO 28451 --- [ main] org.apache.camel.main.MainSupport : Apache Camel (JBang) 3.18.2 is starting
-...
-----
-
-IMPORTANT: You cannot use both a set version via `camel version set` and also a version specified via `--camel-version` option,
-i.e., the following is not possible:
-
-[source,bash]
-----
-camel version set 4.0.1
-camel run * --camel-version=4.3.0
-----
-
-If you want to unset the version, you can use the `--reset` option:
-
-[source,bash]
-----
-camel version set --reset
-----
-
-Then the Camel version in use will be the same version as Camel CLI.
-
-==== Listing available Camel releases
-
-The `version` command can also show available Camel releases by checking the Maven central repository.
-
-[source,bash]
-----
-camel version list
- CAMEL VERSION JDK KIND RELEASED SUPPORTED UNTIL
- 3.14.0 8,11 LTS December 2021 December 2023
- 3.14.1 8,11 LTS January 2022 December 2023
- 3.14.2 8,11 LTS March 2022 December 2023
- 3.14.3 8,11 LTS May 2022 December 2023
- 3.14.4 8,11 LTS June 2022 December 2023
- 3.14.5 8,11 LTS August 2022 December 2023
- 3.14.6 8,11 LTS November 2022 December 2023
- 3.14.7 8,11 LTS December 2022 December 2023
- 3.15.0 11 February 2022
- 3.16.0 11 March 2022
- 3.17.0 11,17 May 2022
- 3.18.0 11,17 LTS July 2022 July 2023
- 3.18.1 11,17 LTS August 2022 July 2023
- 3.18.2 11,17 LTS September 2022 July 2023
- 3.18.3 11,17 LTS October 2022 July 2023
- 3.18.4 11,17 LTS December 2022 July 2023
- 3.18.5 11,17 LTS January 2023 July 2023
- 3.19.0 11,17 October 2022
- 3.20.0 11,17 LTS December 2022 December 2023
- 3.20.1 11,17 LTS January 2023 December 2023
- 3.20.2 11,17 LTS February 2023 December 2023
- 4.0.0-M1 17 RC February 2023
- 4.0.0-M2 17 RC March 2023
-----
-
-NOTE: The `version list` shows the latest releases going back a few versions, at this time of writing the minimum version
-is Camel 3.14. To show all Camel 3.x releases, you can specify `--from-version=3.0` and the list is longer.
-The list can only go back to Camel 2.18, as we do not have all release meta-data for older releases.
-
-You can also show Camel releases for either Spring Boot or Quarkus using the `--runtime` option, such as:
-
-[source,bash]
-----
-camel version list --runtime=quarkus
- CAMEL VERSION QUARKUS JDK KIND RELEASED SUPPORTED UNTIL
- 3.14.0 2.6.0 11 December 2021
- 3.14.1 2.7.0 11 LTS February 2022 August 2022
- 3.14.2 2.7.1 11 LTS April 2022 August 2022
- 3.14.4 2.7.2 11 LTS July 2022 August 2022
- 3.15.0 2.8.0-M1 11 March 2022
- 3.16.0 2.8.0 11 April 2022
- 3.16.0 2.9.0 11 May 2022
- 3.17.0 2.10.0 11 June 2022
- 3.18.0 2.11.0 11 July 2022
- 3.18.1 2.12.0 11 September 2022
- 3.18.2 2.13.0 11 LTS September 2022 March 2023
- 3.18.3 2.13.1 11 LTS November 2022 March 2023
- 3.18.3 2.13.2 11 LTS December 2022 March 2023
- 3.19.0 2.14.0 11 November 2022
- 3.19.0 2.15.0 11 December 2022
- 3.20.1 2.16.0 11 January 2023
-----
-
-TIP: See more options with `camel version list --help`.
-
-=== Manage plugins
-
-Camel CLI uses a plugin concept for some of the subcommands so users can add functionality on demand.
-Each provided plugin adds a list of commands to the Camel CLI command line tool.
-
-You can list the supported plugins with
-
-[source,bash]
-----
-camel plugin get --all
-----
-
-[source,text]
-----
-Supported plugins:
-
- NAME COMMAND VENDOR DEPENDENCY DESCRIPTION
- kubernetes kubernetes ASF org.apache.camel:camel-jbang-plugin-kubernetes Run Camel applications on Kubernetes
- generate generate ASF org.apache.camel:camel-jbang-plugin-generate Generate code such as DTOs
- ...
-
-Known 3rd party plugins:
-
- NAME COMMAND VENDOR DEPENDENCY DESCRIPTION
- forage forage Community io.kaoto.forage:camel-jbang-plugin-forage Production ready Apache Camel components configurations via properties
- camel-kit kit Community io.github.luigidemasi:camel-kit-jbang-plugin Design Apache Camel Integrations with AI
-----
-
-The `VENDOR` column indicates whether the plugin is from `ASF` (Apache Software Foundation) or `Community` (3rd party).
-
-In case you want to enable a plugin and its functionality, you can add it as follows:
-
-[source,bash]
-----
-camel plugin add <plugin-name>
-----
-
-For example to install `generate` you execute:
-
-[source,bash]
-----
-camel plugin add generate
-----
-
-This adds the plugin, and all subcommands are now available for execution.
-
-Known 3rd party plugins can be installed by name as well. For example:
-
-[source,bash]
-----
-camel plugin add forage
-----
-
-To install a specific version of a 3rd party plugin, use the `--version` option:
-
-[source,bash]
-----
-camel plugin add forage --version=1.2.3
-----
-
-You can list the currently installed plugins with:
-
-[source,bash]
-----
-camel plugin get
-----
-
-To remove a plugin from the current Camel CLI command line tooling, you can use the `plugin delete` command.
-
-[source,bash]
-----
-camel plugin delete <plugin-name>
-----
-
-==== Building custom plugins
-
-It is possible to build custom Camel CLI plugins. We suggest to take a look at one of the https://github.com/apache/camel/tree/main/dsl/camel-jbang[existing plugins],
-to see how that is done.
-
-IMPORTANT: The name of the plugin Maven **artifactId** must start with `camel-jbang-plugin-`. For example if the plugin is named `cheese`, then
-the maven artifact must be named `camel-jbang-plugin-cheese`.
-
-=== Running Pipes
-
-Camel also supports running pipes, which represent Kubernetes custom resources following a specific CRD format (Kubernetes Custom Resource Definitions).
-
-For example, a pipe file named `joke.yaml`:
-
-[source,yaml]
-----
-#!/usr/bin/env jbang camel@apache/camel run
-apiVersion: camel.apache.org/v1
-kind: Pipe
-metadata:
- name: joke
-spec:
- source:
- ref:
- kind: Kamelet
- apiVersion: camel.apache.org/v1
- name: chuck-norris-source
- properties:
- period: 2000
- sink:
- ref:
- kind: Kamelet
- apiVersion: camel.apache.org/v1
- name: log-sink
- properties:
- show-headers: false
-----
-
-Can be run with camel:
-
-[source,bash]
-----
-camel run joke.yaml
-----
-
-==== Binding Kamelets in a pipe
-
-WARNING: The bind command is deprecated from Camel 4.19 onwards
-
-Camel CLI is able to create the Pipe custom resource for you.
-You can use the `bind` command to specify a source and a sink that should be set in the pipe.
-As a result, Camel CLI will create a proper Pipe custom resource for you.
-
-The command expects a file name as command argument and provides several options to define the source and the sink that should be used in the pipe.
-
-[source,bash]
-----
-camel bind joke.yaml --source chuck-norris-source --sink log-sink
-----
-
-This creates the `joke.yaml` file that represents the Pipe resource.
-
-[source,yaml]
-----
-apiVersion: camel.apache.org/v1
-kind: Pipe
-metadata:
- name: joke
-spec:
- source:
- ref:
- kind: Kamelet
- apiVersion: camel.apache.org/v1
- name: chuck-norris-source
- properties:
- period: 5000
- sink:
- ref:
- kind: Kamelet
- apiVersion: camel.apache.org/v1
- name: log-sink
-----
-
-NOTE: The bind command is able to inspect the Kamelets being used as a source and sink in order to automatically set all required properties.
-In case the Kamelet defines a required property, and the user has not specified such, the command will automatically set this property with an example value.
-Once the pipe resource file is generated, you can review and set the properties as you wish.
-
-The bind command supports the following options:
-
-[width="100%",cols="1m,3",options="header",]
-|=======================================================================
-|Option |Description
-
-|--source
-|Source (from) such as a Kamelet or Camel endpoint uri that provides data.
-
-|--sink
-|Sink (to) such as a Kamelet or Camel endpoint uri where data should be sent to.
-
-|--step
-|Add optional 1-n steps to the pipe processing. Each step represents a reference to a Kamelet of type action.
-
-|--property
-|Add a pipe property in the form of `[source,sink,error-handler,step-<n>].<key>=<value>` where `<n>` is the step number starting from 1.
-
-|--error-handler
-|Add error handler (none,log,sink:<endpoint>). Sink endpoints are expected in the format [[apigroup/]version:]kind:[namespace/]name, plain Camel URIs or Kamelet name.
-
-|--output
-|Output format generated by this command (supports: file, YAML or JSON). Default is "file".
-|=======================================================================
-
-==== Binding explicit Camel URIs
-
-Usually, the source and sink reference a Kamelet by its name as shown in the previous section.
-As an alternative, you can also just use an arbitrary Camel endpoint URI that acts as a source or sink in the pipe.
-
-[source,bash]
-----
-camel bind joke.yaml --source chuck-norris-source --sink https://mycompany.com/the-service
-----
-
-As a result, the Pipe resource uses the Camel endpoints as source and sink.
-
-[source,yaml]
-----
-apiVersion: camel.apache.org/v1
-kind: Pipe
-metadata:
- name: my-pipe
-spec:
- source:
-# ...
- sink:
- uri: https://mycompany.com/the-service # <1>
-----
-<1> Pipe with explicit Camel endpoint URI as sink where the data gets pushed to
-
-=== Creating a new Kamelet
-
-You can create a new kamelet with the `init` command by using kamelet naming convention.
-
-For example, to create a new kamelet source, you can do:
-
-[source,bash]
-----
-camel init cheese-source.kamelet.yaml
-----
-
-This will create a basic kamelet (based on the timer source).
-
-And to use the kamelet, you could create the following route:
-
-[source,yaml]
-----
-- route:
- from:
- uri: kamelet:cheese-source
- parameters:
- period: "2000"
- message: "Hello World"
- steps:
- - log:
- message: "${body}"
-----
-
-If you want to create a sink kamelet, then you just name it with sink as follows (based on log sink):
-
-[source,bash]
-----
-camel init wine-sink.kamelet.yaml
-----
-
-You can then change the route to use the wine kamelet as follows:
-
-[source,yaml]
-----
-- route:
- from:
- uri: kamelet:cheese-source
- parameters:
- period: "2000"
- message: "Hello World"
- steps:
- - to:
- uri: kamelet:wine-sink
-----
-
-If you want to create a new Kamelet based on an existing Kamelet, for example, to create a new sink based on the existing MySQL:
-
-[source,bash]
-----
-camel init orderdb-sink.kamelet.yaml --from-kamelet=mysql-sink
-----
-
-=== Run from clipboard
-
-You can also run Camel routes directly from the OS clipboard. This allows copying some code,
-and then quickly run this.
-
-The syntax is
-
-[source,bash]
-----
-camel run clipboard.<extension>
-----
-
-Where `<extension>` is what kind of file the content of the clipboard is, such as `java`, `xml`, or `yaml` etc.
-
-For example, you can copy this to your clipboard and then run it afterward:
-
-[source,xml]
-----
-<route>
- <from uri="timer:foo"/>
- <log message="Hello World"/>
-</route>
-----
-
-[source,bash]
-----
-camel run clipboard.xml
-----
-
-==== Run and reload from clipboard
-
-*Available since Camel 4.2*
-
-It is also possible to run from clipboard in _reload_ mode as shown:
-
-[source,bash]
-----
-camel run clipboard.xml --dev
-----
-
-Then you can quickly make changes and copy to clipboard, and Camel CLI will update while running.
-
-=== Sending messages via Camel
-
-*Available since Camel 4*
-
-When building integrations with Camel CLI, you may find yourself in need of being able
-to send messages into Camel, to test your Camel routes. This can be challenging when the
-Camel routes are connected to external systems using different protocols.
-
-The best approach is to send messages into these external systems using standard tools provided
-by these systems, which often can be done using CLI tools. However, in some situations, where you
-may not be familiar with these tools, you can try to let Camel send the message. Note that this
-can only be possible in some scenarios, and should only be used as a _quick way_.
-
-Suppose you have a Camel route that consumes messages from an external MQTT broker:
-
-[source,yaml]
-----
-- route:
- from:
- uri: kamelet:mqtt5-source
- parameters:
- topic: temperature
- brokerUrl: tcp://mybroker:1883
- steps:
- - transform:
- expression:
- jq:
- expression: .value
- - log:
- message: The temperature is ${body}
-----
-
-In the example above the MQTT broker is running on hostname `mybroker` port 1883.
-
-The idea with the `camel cmd send` command is to _tap into_ an existing running Camel integration (by name or PID),
-and reuse an existing endpoint (if possible). In this example, we want to use the existing configuration
-to avoid having to configure this again.
-
-By executing the following from a shell, we send the message to the existing running Camel integration named mqtt:
-
-[source,bash]
-----
-$ camel cmd send mqtt --body=file:payload.json mqtt
-----
-
-We can send a message where the payload is loaded from a file (`_payload.json_`). You can also specify the payload in the CLI
-argument, but it's cumbersome to specify JSON structure so often it's better to refer to a local file.
-
-[source,json]
-----
-{
- "value": 21
-}
-----
-
-The `mqtt` argument is the name of the existing running Camel integration. You can also specify the PID instead.
-So what happens is that Camel will let the existing integration send the message.
-
-Because the existing integration only has one route, then the `send` command will automatically pick
-the `_from_` endpoint, i.e. `kamelet:mqtt5-source` with all its configuration. If there are multiple routes,
-then you can filter which route/endpoint by the `--endpoint` option:
-
-For example, to pick the first route by _route id_:
-
-[source,bash]
-----
-$ camel cmd send mqtt --body=file:payload.json --endpoint=route1
-----
-
-Or to pick the first route that uses mqtt component:
-
-[source,bash]
-----
-$ camel cmd send mqtt --body=file:payload.json --endpoint=mqtt
-----
-
-We are fortunate in this situation as the endpoint can be used as both a _consumer_ and _producer_ in Camel,
-and therefore we are able to send the message to the MQTT broker via `tcp://mybroker:1883` on topic _temperate_.
-
-TIP: See more options with `camel cmd send --help`.
-
-The source for this example is provided on GitHub at https://github.com/apache/camel-jbang-examples/tree/main/mqtt[https://github.com/apache/camel-kamelets-examples/tree/main/jbang/mqtt])[camel-jbang MQTT example].
-
-==== Sending messages without any running Camel
-
-*Available since Camel 4.12*
-
-In Camel 4.12 you can use `camel cmd send` without any existing running Camel integration, which then
-will automatic startup a internal Camel and use that for sending the message. This allows to send a message
-using all the Camel components or Kamelets. However, this requires that all the necessary configuration can
-be provided from the CLI (which can be cumbersome for some components).
-
-This is done by **NOT** specifying any integration name or PID in the command such as:
-
-[source,bash]
-----
-$ camel cmd send --body=file:payload.json --uri='paho-mqtt5:temperature?brokerUrl=tcp://mybroker:1883'
-----
-
-As you can see this is more cumbersome as we need to provide all the configurations, which can be more complex
-for components like Kafka or AWS. So for these you may want to use a kamelet instead:
-
-[source,bash]
-----
-$ camel cmd send --body=file:payload.json --uri='kamelet:mqtt-sink?brokerUrl=tcp://mybroker:1883&topic=temperature'
-----
-
-==== Sending messages to infrastructure services
-
-*Available since Camel 4.18*
-
-You can use `camel cmd send` to send messages directly to infrastructure services that are started with `camel infra run`.
-This eliminates the need to manually specify server connection details, as the command automatically reads connection information from JSON files created by infrastructure services.
-
-This is done by using the `--infra` option to specify which infrastructure service to send to:
-
-[source,bash]
-----
-$ camel infra run nats
-$ camel cmd send --body=file:payload.json --infra=nats
-----
-
-The command automatically discovers the running infrastructure service, reads its connection details from the JSON file (stored in `~/.camel/`), and constructs the appropriate endpoint URI with the server information using the Camel Catalog.
-
-===== Specifying a custom endpoint
-
-If you don't specify an `--endpoint`, the command automatically creates a default endpoint based on the infrastructure service type (e.g., `kafka:default`, `nats:default`).
-
-You can also combine the `--infra` option with a specific endpoint to customize the destination:
-
-[source,bash]
-----
-$ camel cmd send --endpoint='kafka:myTopic' --body=file:payload.json --infra=kafka
-$ camel cmd send --endpoint='nats:mySubject' --body=file:payload.json --infra=nats
-----
-
-NOTE: If your endpoint already contains query parameters (e.g., `kafka:myTopic?groupId=myGroup`), the connection details from the infrastructure service will not override them.
-
-===== Automatic credential handling
-
-For services that support authentication (such as artemis, ftp, sftp), the command automatically appends credentials from the connection details to the endpoint URI if the Camel component supports them:
-
-[source,bash]
-----
-$ camel infra run artemis
-$ camel cmd send --endpoint='jms:myQueue' --body='Hello' --infra=artemis
-----
-
-The resulting endpoint will automatically include authentication parameters like `username` and `password=RAW(...)`.
-
-===== Multiple service detection
-
-If multiple instances of the same infrastructure service are running, the command will display an error and ask you to be more specific:
-
-[source,bash]
-----
-Multiple running infrastructure services found for: kafka. Found 2 services.
-----
-
-In this case, stop the unwanted service or specify the exact PID.
-
-==== Poll messages via Camel
-
-*Available since Camel 4.8*
-
-The `camel cmd send` command has been improved to also _poll_ messages from Camel. This is needed
-if you want to poll the latest messages from a Kafka topic, JMS queue, or download a file from FTP etc.
-
-The poll uses Camel consumer to poll the message (timeout if no message received) instead of producer.
-
-For example to poll a message from a ActiveMQ queue named cheese you can do:
-
-[source,bash]
-----
-$ camel cmd send --poll --endpoint='activemq:cheese'
-----
-
-When you poll then you do not send any payload (body or headers).
-
-=== Receiving messages via Camel
-
-*Available since Camel 4.9*
-
-When building a prototype integration with Camel CLI, you may route messages to external systems.
-To know whether messages are being routed correctly, you may use system consoles to look inside these systems
-which messages have arrived, such as SQL prompts, web consoles, CLI tools etc.
-
-The Camel CLI now comes with a new command to receive messages from remote endpoints.
-This can be used to quickly look or tail in terminal the messages that an external systems has received.
-Camel does this by consuming the messages (if the component has support for consumer) and then let Camel CLI dump the messages from the CLI.
-
-For example to start dumping all messages from ActiveMQ in one command, you can do:
-
-[source,bash]
-----
-$ camel cmd receive --endpoint='activemq:cheese'
-----
-
-You can also use pattern syntax for the endpoint, so suppose you have the following route:
-
-[source,java]
-----
-from("ftp:myserver:1234/foo")
- .to("log:order")
- .to("activemq:orders");
-----
-
-Then you can tell Camel to automatic start receiving messages with:
-
-[source,bash]
-----
-$ camel cmd receive --action=start
-----
-
-TIP: You can enable and disable this mode with `--action=start` and `--action-stop`.
-
-Then Camel will automatically discover from the running integration, all the _producers_ and
-find the first _producer_ that is remote and also has consumer support. In the example above,
-that is the `activemq` component, and thus Camel will start receive from `activemq:orders`.
-
-You can see the status via:
-
-[source,bash]
-----
-$ camel cmd receive
- PID NAME AGE STATUS TOTAL SINCE ENDPOINT
- 4364 foo 1m33s Enabled 18 2s activemq://orders
-----
-
-You can then dump all the received messages with:
-
-[source,bash]
-----
-$ camel cmd receive --action=dump
-----
-
-This will dump all the messages, and continue to dump new incoming messages. Use (ctrl + c) to break and exit.
-You can turn follow off with `--follow=false`.
-
-TIP: Use `camel cmd receive --help` to see all the various options for this command.
-
-
-=== Controlling local Camel integrations
-
-To list the currently running Camel integrations, you use the `ps` command:
-
-[source,bash]
-----
-camel ps
- PID NAME READY STATUS AGE
- 61818 sample.camel.MyCamelApplica... 1/1 Running 26m38s
- 62506 dude 1/1 Running 4m34s
-----
-
-This lists the PID, the name and age of the integration.
-
-You can use the `stop` command to stop any of these running Camel integrations.
-For example, to stop dude, you can do
-
-[source,bash]
-----
-camel stop dude
-Stopping running Camel integration (pid: 62506)
-----
-
-You can also stop by the PID:
-
-[source,bash]
-----
-camel stop 62506
-Stopping running Camel integration (pid: 62506)
-----
-
-NOTE: You do not have to type the full name, as the stop command will match using integrations
-that start with the input, for example, you can do `camel stop d` to stop all integrations
-starting with d. If you have multiple integrations running with similar name such as `dude`, `dude2`, then
-if you type `camel stop dude` then Camel will stop both integrations. However, if you want to only
-stop a single integration then either stop via PID or use `camel stop dude!` with the `!` at the end.
-
-To stop all integrations, then execute without any pid:
-
-[source,bash]
-----
-camel stop
-Stopping running Camel integration (pid: 61818)
-Stopping running Camel integration (pid: 62506)
-----
-
-==== Watching local Camel integrations
-
-Most of the management commands can run in _watch_ mode, which repetitively output the status in full-screen mode.
-This is done using the `--watch` parameter as follows:
-
-[source,bash]
-----
-camel ps --watch
- PID NAME READY STATUS AGE
- 61818 sample.camel.MyCamelApplica... 1/1 Running 26m38s
- 62506 dude 1/1 Running 4m34s
-----
-
-==== Controlling Spring Boot and Quarkus integrations
-
-The Camel CLI CLI will by default only control Camel integrations that are running using the CLI, eg `camel run foo.java`.
-
-For the CLI to be able to control and manage Spring Boot or Quarkus applications, then you need to add a dependency
-to these projects to integrate with Camel CLI.
-
-In Spring Boot, you add the following dependency:
-
-[source,xml]
-----
-<dependency>
- <groupId>org.apache.camel.springboot</groupId>
- <artifactId>camel-cli-connector-starter</artifactId>
-</dependency>
-----
-
-In Quarkus, you need to add the following dependency:
-
-[source,xml]
-----
-<dependency>
- <groupId>org.apache.camel.quarkus</groupId>
- <artifactId>camel-quarkus-cli-connector</artifactId>
-</dependency>
-----
-
-==== Getting status of Camel integrations
-
-The `get` command in Camel CLI is used for getting Camel specific status for one
-or all of the running Camel integrations.
-
-To display the status of the running Camel integrations:
-
-[source,bash]
-----
-camel get
- PID NAME CAMEL PLATFORM READY STATUS AGE TOTAL FAILED INFLIGHT SINCE-LAST
- 61818 MyCamel 3.20.0 Spring Boot v2.7.3 1/1 Running 28m34s 854 0 0 0s/0s/-
- 63051 dude 3.20.0 JBang 1/1 Running 18s 14 0 0 0s/0s/-
- 63068 mygroovy 3.20.0 JBang 1/1 Running 5s 2 0 0 0s/0s/-
-----
-
-The `camel get` command will default display Camel application (context), which is equivalent to
-typing `camel get context`.
-
-This displays overall information for every Camel integration, where you can see
-the total number of messages processed. The column _Since Last_
-shows how long time ago the last processed message for 3 stages (started/completed/failed).
-
-The value of `0s/0s/-` means that the last started and completed message just happened (0 seconds ago),
-and that there has not been any failed message yet. And this example `9s/9s/1h3m` means that last started and
-completed message is 9 seconds ago, and last failed were 1 hour and 3 minutes ago.
-
-TIP: You can run in _watch_ mode using: `camel get --watch`
-
-===== Total in Camel 4.7 and 4.8
-
-From *Camel 4.7* onwards, two numbers will be displayed for _TOTAL_, _FAILED_, and _INFLIGHT_ columns.
-The first number is messages received from external systems (databases, cloud systems), and the second
-number is the total number (as in earlier versions).
-
-[source,bash]
-----
-camel get
- PID NAME CAMEL PLATFORM PROFILE READY STATUS RELOAD AGE ROUTE MSG/S TOTAL FAIL INFLIGHT LAST DELTA SINCE-LAST
- 42240 cheese 4.7.0 JBang v0.116.0 dev 1/1 Running 0 1m8s 2/2 1.01 1/65 0/0 0/0 0 -1 1s/1s/-
-----
-
-The _TOTAL_ column above shows `1/65` which mean that 1 message was from an external source, and 65 in total; which means that
-64 are from internal sources (such as timer, seda).
-
-===== Total in Camel 4.9 onwards
-
-The TOTAL column is total number of messages processed. This is all messages both started internally (such as from a timer)
-and received from external systems (databases, cloud systems). In *Camel 4.9* we made the TOTAL column a single digit again
-to not confuse, and we added a new `REMOTE` column to show total for remote systems only. So the example above would be:
-
-[source,bash]
-----
-camel get
- PID NAME CAMEL PLATFORM PROFILE READY STATUS RELOAD AGE ROUTE MSG/S TOTAL REMOTE FAIL INFLIGHT LAST DELTA SINCE-LAST
- 42240 cheese 4.9.0 JBang v0.118.0 dev 1/1 Running 0 1m8s 2/2 1.01 65 1 0/0 0/0 0 -1 1s/1s/-
-----
-
-===== Total in Camel 4.12 onwards
-
-And yet again it was changed in *Camel 4.12* to be a single number by default.
-You can use `--remote` to break down the numbers into remote/total pair.
-
-[source,bash]
-----
-camel get
- PID NAME CAMEL PLATFORM PROFILE READY STATUS RELOAD AGE ROUTE MSG/S TOTAL FAIL INFLIGHT LAST DELTA SINCE-LAST
- 42240 cheese 4.12.0 JBang v0.126.0 dev 1/1 Running 0 1m8s 2/2 1.01 65 0 0 0 -1 1s/1s/-
-----
-
-==== Route status
-
-You can also see the status of every route, from all the local Camel integrations with `camel get route`:
-
-[source,bash]
-----
-camel get route
- PID NAME ID FROM STATUS AGE TOTAL FAILED INFLIGHT MEAN MIN MAX SINCE-LAST
- 61818 MyCamel hello timer://hello?period=2000 Running 29m2s 870 0 0 0 0 14 0s/0s/-
- 63051 dude java timer://java?period=1000 Running 46s 46 0 0 0 0 9 0s/0s/-
- 63068 mygroovy groovy timer://groovy?period=1000 Running 34s 34 0 0 0 0 5 0s/0s/-
-----
-
-TIP: Use `camel get --help` to display all the available commands as additional will be added in upcoming releases.
-
-==== Top status of Camel integrations
-
-The `camel top` command is intended for getting top utilization statistics (highest to lowest heap used memory)
-of the running Camel integrations.
-
-[source,bash]
-----
-camel top
- PID NAME JAVA CAMEL PLATFORM STATUS AGE HEAP NON-HEAP GC THREADS CLASSES
- 22104 chuck 11.0.13 3.20.0 JBang Running 2m10s 131/322/4294 MB 70/73 MB 17ms (6) 7/8 7456/7456
- 14242 MyCamel 11.0.13 3.20.0 Spring Boot v2.7.3 Running 33m40s 115/332/4294 MB 62/66 MB 37ms (6) 16/16 8428/8428
- 22116 bar 11.0.13 3.20.0 JBang Running 2m7s 33/268/4294 MB 54/58 MB 20ms (4) 7/8 6104/6104
-----
-
-The _HEAP_ column shows the heap memory (used/committed/max) and the non-heap (used/committed).
-The _GC_ column shows garbage collection information (time and total runs).
-The _CLASSES_ column shows the number of classes (loaded/total).
-
-You can also see the top performing routes (highest to lowest mean processing time)
-of every route, from all the local Camel integrations with `camel top route`:
-
-[source,bash]
-----
-camel top route
- PID NAME ID FROM STATUS AGE TOTAL FAILED INFLIGHT MEAN MIN MAX SINCE-LAST
- 22104 chuck chuck-norris-source-1 timer://chuck?period=10000 Started 10s 1 0 0 163 163 163 9s
- 22116 bar route1 timer://yaml2?period=1000 Started 7s 7 0 0 1 0 11 0s
- 22104 chuck chuck kamelet://chuck-norris-source Started 10s 1 0 0 0 0 0 9s
- 22104 chuck log-sink-2 kamelet://source?routeId=log-sink-2 Started 10s 1 0 0 0 0 0 9s
- 14242 MyCamel hello timer://hello?period=2000 Started 31m41s 948 0 0 0 0 4 0s
-----
-
-TIP: Use `camel top --help` to display all the available commands as additional will be added in upcoming releases.
-
-==== Tailing logs
-
-When you run Camel integrations, then they will by default run in the foreground and output logs.
-
-NOTE: The `camel log` command is **not** supported when running in Spring Boot or Quarkus runtimes.
-
-You can from another terminal access the logs from any Camel integration with the `log` command, as follows:
-
-[source,bash]
-----
-camel log chuck
-chuck | 2023-01-04 17:59:19.288 INFO 44619 --- [ main] org.apache.camel.main.MainSupport : Apache Camel (JBang) 3.21.0 is starting
-chuck | 2023-01-04 17:59:19.395 INFO 44619 --- [ main] org.apache.camel.main.MainSupport : Using Java 17.0.5 with PID 44619. Started by davsclaus in /Users/davsclaus/workspace/
-...
-----
-
-You can also watch logs for all Camel integrations by `camel log`, or you can specify by name/pids (separate by comma) `camel log bar,chuck`.
-
-It is also possible to find and highlight keywords from the log using `--find`, such as:
-
-[source,bash]
-----
-camel log chuck --find=invoice
-----
-
-You can find multiple items by repeating the option, i.e.:
-
-[source,bash]
-----
-camel log chuck --find=invoice --find=order
-----
-
-There is also a _grep_ option that will filter the logs to only show lines that matches text (ignore case).
-
-[source,bash]
-----
-camel log chuck --grep=error
-----
-
-The log command will by default tail the logs for new lines. If you want to exit the command immediately, you
-can turn off the following as shown:
-
-[source,bash]
-----
-camel log chuck --grep=error --follow=false
-----
-
-This will grep the logs for log lines with matches text `error` and output only these logs, and exit.
-
-==== Tracing messages
-
-The `trace` command is used for showing how messages are routed in Camel. The command has similar output as the `log`
-command but only display message tracing information. This allows you to see every _step_ a message is routed in Camel.
-
-The `trace` command has many options and can be used to _filter_, _grep_ or output on different detail _levels`.
-The _exchange id_ is logged (and grouped by colour), so you can use that to correlate the events when traces are interleaved.
-
-The trace command will by default list the status of whether tracing is enabled or not in the integrations:
-
-[source,bash]
-----
-camel trace
- PID NAME AGE STATUS TOTAL QUEUE FILTER PATTERN
- 6911 chuck 5s Standby 0 0
-----
-
-Here we can see that the tracer is in standby mode, and you need to start the tracer before Camel will capture messages:
-
-TIP: Camel 4.8 onwards has tracing in standby mode (when using dev profile). You can enable tracing on startup by setting the configuration `camel.trace.enabled=true` in `application.properties`.
-
-[source,bash]
-----
-camel trace --action=start
-----
-
-And if you run `camel trace` again you can see the tracer is started:
-
-[source,bash]
-----
-camel trace
-PID NAME AGE STATUS TOTAL QUEUE FILTER PATTERN
-6911 chuck 1m5s Started 16 4
-----
-
-And to show the traces you need to use the `dump` action as follows:
-
-[source,bash]
-----
-camel trace chuck --action=dump
-----
-
-You can also dump traces from all running integrations:
-
-[source,bash]
-----
-camel trace --action=dump
-----
-
-To stop tracing use `--action=stop`.
-
-And you can also clear the already traced messages with `--action=clear`.
-
-==== Running Camel integrations in background
-
-The `run` command allows running Camel in the background with the `--background` option.
-Therefore, to see and understand what happens then the management commands
-cane be used, such as `camel ps`, `camel get`, and `camel log`.
-
-NOTE: Only Camel Main is supported to run in background
-
-[source,bash]
-----
-$ camel run chuck.yaml --background --runtime=main
-Running Camel integration: chuck in background with PID: 80093
-
-$ camel ps
- PID NAME READY STATUS AGE
- 80093 chuck 1/1 Running 33s
-----
-
-To see the log use `camel log`
-[source,bash]
-----
-$ camel log
-chuck | 2023-01-04 17:59:19.288 INFO 44619 --- [ main] org.apache.camel.main.MainSupport : Apache Camel (JBang) 3.21.0 is starting
-chuck | 2023-01-04 17:59:19.395 INFO 44619 --- [ main] org.apache.camel.main.MainSupport : Using Java 17.0.5 with PID 44619. Started by davsclaus in /Users/davsclaus/workspace/
-...
-----
-
-To stop the integration you can use `camel stop`
-
-[source,bash]
-----
-$ camel stop chuck
-Shutting down Camel integration (pid: 80093)
-----
-
-When running in background, then Camel CLI (**4.10 onwards**) will now automatic wait for the integration
-to startup before returning from the CLI command. This ensures that if there are any startup
-errors such as compilation errors or DSL errors etc. then these are captured and printed in the shell.
-You can use the option `--background-wait=false` to turn this off.
-
-==== Starting and Stopping routes
-
-The `camel cmd` is intended for executing miscellaneous commands in the running Camel integrations.
-For example, there are commands to start and stop routes.
-
-To stop all the routes in the chuck integration, you execute:
-
-[source,bash]
-----
-camel cmd stop-route chuck
-----
-
-And the status will then report the status as _Stopped_ for the chuck integration:
-
-[source,bash]
-----
-camel get route
- PID NAME ID FROM STATUS AGE TOTAL FAILED INFLIGHT MEAN MIN MAX SINCE-LAST
- 81663 chuck chuck kamelet://chuck-norris-source Stopped 600 0 0 0 0 1 4s
- 81663 chuck chuck-norris-source-1 timer://chuck?period=10000 Stopped 600 0 0 65 52 290 4s
- 81663 chuck log-sink-2 kamelet://source?routeId=log-sink-2 Stopped 600 0 0 0 0 1 4s
- 83415 bar route1 timer://yaml2?period=1000 Started 5m30s 329 0 0 0 0 10 0s
- 83695 MyCamel hello timer://hello?period=2000 Started 3m52s 116 0 0 0 0 9 1s
-----
-
-To start the routes, you can do:
-
-[source,bash]
-----
-camel cmd start-route chuck
-----
-
-To stop _all_ routes in every Camel integration:
-
-[source,bash]
-----
-camel cmd stop-route
-----
-
-And you can start _all_ routes using:
-
-[source,bash]
-----
-camel cmd start-route
-----
-
-To start a specific route, you need to use `--id` parameter such as the following,
-which will start routes named `route1` in all running integrations:
-
-[source,bash]
-----
-camel cmd start-route --id=route1
-----
-
-If you want to do this in a specific integration, you must include the name or pid:
-
-[source,bash]
-----
-camel cmd start-route bar --id=route1
-----
-
-TIP: You can stop one or more route by their ids by separating using
-comma such as `camel cmd start-route --id=route1,hello`.
-Use `camel cmd start-route --help` for more details.
-
-==== Starting and Stopping route groups
-
-*Available as of Camel 4.14*
-
-If you group together routes, then you can also control by groups. For example, you can see status of route groups via:
-
-[source,bash]
-----
-camel get group
- PID NAME GROUP ROUTES STATUS AGE COVER MSG/S TOTAL FAIL INFLIGHT MEAN MIN MAX LAST DELTA SINCE-LAST
- 53173 foo first 2 Started 8s 4/4 1.00 15 0 1 504 501 511 502 -3 0s/0s/-
- 53173 foo second 3 Started 40s 7/7 0.00 8 0 0 2260 2256 2263 2263 +6 5s/2s/-
-----
-
-The data shown above is _aggregate_ of all the routes within each group. There are _2_ routes in first and _3_ routes in seconds.
-
-You can then stop a group such as _first_ via:
-
-[source,bash]
-----
-camel cmd stop-group foo --id=first
-----
-
-And when you see the status it is listed as _Stopped_:
-
-[source,bash]
-----
-camel get group
- PID NAME GROUP ROUTES STATUS AGE COVER MSG/S TOTAL FAIL INFLIGHT MEAN MIN MAX LAST DELTA SINCE-LAST
- 53173 foo first 2 Stopped 0/0 0.00 8 0 0 504 501 511 502 -1 11s/11s/-
- 53173 foo second 3 Started 19s 7/7 1.00 4 0 0 2259 2256 2261 2260 -1 3s/1s/-
-----
-
-And you can of course also start the group again:
-
-[source,bash]
-----
-camel cmd start-group foo --id=first
-----
-
-The route group commands works similar to how you control routes (see above).
-
-==== Enabling and Disabling EIPs
-
-*Available as of Camel 4.14*
-
-When developing prototypes or trouble-shooting, you may want to quickly be able to disable some EIPs that
-should not be active, without having to change source code.
-
-[source,bash]
-----
-camel get processor
-PID NAME ID PROCESSOR STATUS TOTAL FAIL INFLIGHT MEAN MIN MAX LAST DELTA SINCE-LAST
- 5202 foo a direct://a Started 14 0 1 504 501 506 501 -5 1s/-
- delay1 delay Started 14 0 1 503 500 505 500 -5 1s/-
- log1 log Started 14 0 0 0 0 1 0 0 1s/-
-----
-
-The route above have 2 processors, and we can quickly disable one of them such as _log1_ as follows:
-
-[source,bash]
-----
-camel cmd disable-processor --id=log1
-----
-
-[source,bash]
-----
-camel get processor
- PID NAME ID PROCESSOR STATUS TOTAL FAIL INFLIGHT MEAN MIN MAX LAST DELTA SINCE-LAST
- 5202 foo a direct://a Started 116 0 1 503 500 506 503 -1 0s/-
- delay1 delay Started 116 0 1 503 500 505 503 -1 0s/-
- log1 log Disabled 112 0 0 0 0 1 0 0 4s/-
-----
-
-The status is now changed to _Disabled_ and the EIP is not in use, and it's statistics will not be updated as it does not process any messages.
-
-You can enable the EIP again either explicit:
-
-[source,bash]
-----
-camel cmd enable-processor --id=log1
-----
-
-Or to quickly enable all EIPs
-
-[source,bash]
-----
-camel cmd enable-processor
-----
-
-TIP: You can also disable multiple EIPs seperated by comma, such as `--id=log1,log2,setBody2,choice1`
-
-
-==== Running Camel integrations on Kubernetes
-
-After developing the Camel routes locally with JBang, you may want to run these also on the Kubernetes platform at some point.
-
-Camel CLI provides a plugin for managing and easily running Camel applications on Kubernetes.
-The plugin uses the project export functionality to build and deploy the application on Kubernetes with Quarkus or SpringBoot.
-
-Read about it in the xref:camel-jbang-kubernetes.adoc[Camel Kubernetes plugin] documentation.
-
-==== Automated tests for Camel integrations
-
-Testing is essential, from the very first line of code!
-When prototyping a Camel route locally with JBang, you can also start prototyping an automated test from the very beginning.
-
-Camel CLI provides a plugin for writing and executing automated tests.
-The plugin uses the capabilities of the Open Source test framework https://citrusframework.org[Citrus] to develop fully self-contained tests that verify your Camel integrations.
-
-The automated test is able to prepare required infrastructure (e.g. PostgreSQL database, Kafka message broker) using containers and Camel infra services. Also, the test is able to automatically start the Camel integration locally with Camel CLI. Following from that the test is able to invoke exposed services of the Camel integration and verify its outcome.
-
-Once the prototyping phase with Camel CLI is complete you can include the automated tests into the project export.
-Usually, the export creates a Maven project on top of Quarkus or SpringBoot and the automated tests become part of this project, so the tests are run with the project build lifecycle.
-
-Read about the plugin in the xref:camel-jbang-test.adoc[Camel Testing plugin] documentation.
-
-==== Configuring logging levels
-
-You can see the current logging levels of the running Camel integrations by:
-
-[source,bash]
-----
-camel cmd logger
- PID NAME AGE LOGGER LEVEL
- 90857 bar 2m48s root INFO
- 91103 foo 20s root INFO
-----
-
-The logging level can be changed at runtime, for example, to change foo to DEBUG you execute:
-
-[source,bash]
-----
-camel cmd logger --logging-level=DEBUG foo
-----
-
-TIP: You can use `--all` to change logging levels for all running integrations.
-
-===== Configuring individual logging levels
-
-From *Camel 4.6* onwards you can easily configure different logging levels from CLI and `application.properties`.
-
-For example from CLI, you can specify using the `--logging-category` option.
-For example, to enable DEBUG logging if using Kafka:
-
-[source,bash]
-----
-$ camel run myapp.yaml --logging-category=org.apache.kafka=DEBUG
-----
-
-You can specify multiple categories by repeating the CLI option as shown:
-
-[source,bash]
-----
-$ camel run myapp.yaml --logging-category=org.apache.kafka=DEBUG --logging-category=com.foo.something=TRACE
-----
-
-You can also configure logging levels in `application.properties` using two styles
-
-- `logging.level.` it is the default style used by Camel and Spring Boot
-- `quarkus.log.category.` is used by Quarkus
-
-For example, you can declare as follows:
-
-[source,properties]
-----
-
-# make it easy to configure individual logging levels
-logging.level.org.apache.kafka = DEBUG
-logging.level.com.foo.something = TRACE
-
-# you can also use quarkus style naming
-quarkus.log.category."org.apache.kafka".level = DEBUG
-quarkus.log.category."com.foo.something".level = TRACE
-----
-
-==== Listing services
-
-Some Camel integrations may host a service which clients can call, such as REST, or SOAP-WS, or socket-level services using TCP protocols.
-
-You can list the available services as shown in the example below:
-
-[source,bash]
-----
-camel get service
- PID NAME COMPONENT PROTOCOL SERVICE
- 1912 netty netty tcp tcp:localhost:4444
- 2023 greetings platform-http rest http://0.0.0.0:7777/camel/greetings/{name} (GET)
- 2023 greetings platform-http http http://0.0.0.0:7777/q/dev
-----
-
-Here you can see 2 Camel integrations. The netty integration hosts a TCP service that is available on port 4444.
-The other Camel integration hosts a REST service that can be called via GET only.
-And finally the integration comes with embedded web console (started with the `--console` option).
-
-NOTE: For a service to be listed then Camel components must be able to advertise the services using xref:camel-console.adoc[].
-
-==== Observability with metrics
-
-Camel CLI comes with support for using Micrometer for metrics that easily can be made available.
-
-You simply either run with `--observe` option (use `--metrcis` in older Camel versions),
-or enable and have more control of the configuration in the `application.properties` file as shown below:
-
-[source,properties]
-----
-# enable HTTP management server with metrics
-camel.management.enabled=true
-camel.management.metricsEnabled=true
-
-# turn on micrometer metrics
-camel.metrics.enabled=true
-# include more camel details
-camel.metrics.enableMessageHistory=true
-# include additional out-of-the-box micrometer metrics for cpu, jvm and used file descriptors
-camel.metrics.binders=processor,jvm-info,file-descriptor
-----
-
-Then you can access metrics from the web browser at: http://localhost:8080/observe/metrics[http://localhost:8080/observe/metrics]
-
-You can also see metrics from the CLI as shown below:
-
-[source,bash]
-----
-$ camel get metric
- PID NAME TYPE METRIC ROUTE VALUE MEAN MAX TOTAL
- 11562 MyCoolCamel timer camel.exchange.event.notifier 3 12 27 35
- 11562 MyCoolCamel timer camel.exchange.event.notifier 3 1 2 3
- 11562 MyCoolCamel gauge camel.routes.added 3
- 11562 MyCoolCamel gauge camel.routes.running 3
- 11562 MyCoolCamel gauge jvm.info 1
- 11562 MyCoolCamel gauge process.cpu.usage 0.0045185067010171795
- 11562 MyCoolCamel gauge process.files.max 10240
- 11562 MyCoolCamel gauge process.files.open 288
- 11562 MyCoolCamel gauge system.cpu.count 8
- 11562 MyCoolCamel gauge system.cpu.usage 0.15222772277227722
- 11562 MyCoolCamel gauge system.load.average.1m 3.58935546875
-----
-
-==== Listing state of Circuit Breakers
-
-If your Camel integration uses xref:components:eips:circuitBreaker-eip.adoc[Circuit Breaker],
-then you can output the status of the breakers with Camel CLI as follows:
-
-[source,bash]
-----
-camel get circuit-breaker
- PID NAME COMPONENT ROUTE ID STATE PENDING SUCCESS FAIL REJECT
- 56033 mycb resilience4j route1 circuitBreaker1 HALF_OPEN 5 2 3 0
-----
-
-Here we can see the circuit breaker is in _half-open_ state, i.e., a state where the breaker is attempting
-to transition back to closed if the failures start to drop.
-
-TIP: You can run the command with watch to keep showing the latest state `watch camel get circuit-breaker`.
-
-=== Using Jolokia and Hawtio
-
-The https://hawt.io/[Hawtio] web console allows inspecting running Camel integrations, such
-as all the JMX management information, and not but least to visualize the Camel routes
-with live performance metrics. Hawtio is a handy tool for many years, and we have made it
-easy to use Hawtio with Camel CLI.
-
-To let Hawtio able to inspect the Camel integrations, then the Jolokia JVM Agent
-must be installed in the running integration, this can be done, either explicit as follows:
-
-[source,bash]
-----
-camel ps
- PID NAME READY STATUS AGE
- 61818 sample.camel.MyCamelApplica... 1/1 Running 26m38s
- 62506 dude.java 1/1 Running 4m34s
-----
-
-With the PID you can then attach Jolokia:
-
-[source,bash]
-----
-camel jolokia 62506
-Started Jolokia for PID 62506
-http://127.0.0.1:8778/jolokia/
-----
-
-Instead of using PID, you can also attach by name pattern.
-In this example, because the
-two Camel integrations have unique names (foo and dude), then you can also attach Jolokia
-without knowing the PID as follows:
-
-[source,bash]
-----
-camel jolokia du
-Started Jolokia for PID 62506
-http://127.0.0.1:8778/jolokia/
-----
-
-Then you can launch https://hawt.io/[Hawtio] using Camel CLI:
-
-[source,bash]
-----
-camel hawtio
-----
-
-This will automatically download and start Hawtio, and open in web browser.
-
-TIP: See `camel hawtio --help` for options.
-
-And when Hawtio launches in the web browser, click the _Discover_ tab which should
-list all the local available Jolokia Agents (yes you can use `camel jolokia PID` to connect
-to multiple different Camel integrations and from this list select which to load).
-
-Click the green _lightning_ icon to connect to running Camel integration (of choice).
-
-You can uninstall the Jolokia JVM Agent in a running Camel integration when no longer needed:
-
-[source,bash]
-----
-camel jolokia 62506 --stop
-Stopped Jolokia for PID 62506
-----
-
-It is also possible to do this with only one command, as follows:
-
-[source,bash]
-----
-camel hawtio dude
-----
-
-Where _dude_ is the name of the running Camel integration. When you stop Hawtio (using `ctrl` + `c`)
-then Camel will attempt to uninstall the Jolokia JVM Agent. However, this may not be
-able to do this always, because the JVM is being terminated which can prevent camel-jbang
-from doing JVM process communication to the running Camel integration.
-
-=== Scripting from terminal using pipes
-
-You can also execute a Camel CLI file as a script that can be used for terminal scripting with pipes and filters.
-
-NOTE: Every time the script is executed, a JVM is started with Camel.
-This is not very fast or low on memory usage,
-so use Camel CLI terminal scripting where using Camel makes sense.
-For example, to use
-many Camel components or Kamelets, to more easily send or receive data from disparate IT systems.
-
-This requires adding the following line in top of the file, for example, as in the `UpperCase.java` file below:
-
-[source,text]
-----
-///usr/bin/env jbang --quiet camel@apache/camel script "$0" "$@" ; exit $?
-
-import org.apache.camel.builder.RouteBuilder;
-
-//Will upper-case the input
-public class UpperCase extends RouteBuilder {
-
- @Override
- public void configure() throws Exception {
- from("stream:in")
- .setBody()
- .simple("${body.toUpperCase()}")
- .to("stream:out");
- }
-}
-----
-
-To be able to execute this as a script, you need to set execute file permission:
-
-[source,bash]
-----
-chmod +x UpperCase.java
-----
-
-Then you can then execute this as a script:
-
-[source,bash]
-----
-echo "Hello\nWorld" | ./UpperCase.java
-----
-
-Which should output:
-
-[source,text]
-----
-HELLO
-WORLD
-----
-
-Logging can be turned on using `--logging=true` which then logs to `.camel-jbang/camel-pipe.log` file.
-The name of the logging file cannot be configured.
-
-[source,bash]
-----
-echo "Hello\nWorld" | ./UpperCase.java --logging=true
-----
-
-==== Using stream:in with line vs. raw mode
-
-When using `stream:in` to read data from _System in_ then the xref:components::stream-component.adoc[Stream component]
-works in two modes:
-
-- line mode (default): reads input as single lines (separated by line breaks).
- Message body is a `String`.
-- raw mode: reads the entire stream until the _end of stream_.
- Message body is a `byte[]`.
-
-IMPORTANT: The default mode is due to historically how the stream component was created.
-Therefore, you may want to set `stream:in?readLine=false` to use raw mode.
-
-=== Running local Kamelets
-
-You can also use Camel CLI to try local Kamelets, without the need to publish them on GitHub or package them in a jar.
-
-[source,bash]
-----
-camel run --local-kamelet-dir=/path/to/local/kamelets earthquake.yaml
-----
-
-TIP: When the kamelets are from local file system, then they can be live reloaded if they are updated, when you run
-Camel CLI in `--dev` mode.
-
-You can also point to a folder in a GitHub repository. For example, we have provided some custom Kamelets
-at https://github.com/apache/camel-kamelets-examples/tree/main/custom-kamelets, which can be used easily:
-
-[source,bash]
-----
-camel run --local-kamelet-dir=https://github.com/apache/camel-kamelets-examples/tree/main/custom-kamelets user.java
-----
-
-NOTE: If a kamelet is loaded from GitHub, then they cannot be live reloaded.
-
-=== Using the platform-http component
-
-NOTE: Camel CLI is only intended for working with `platform-http` as HTTP server component for rest-dsl,
-and for HTTP serer in general. It is not intended to work with `camel-servlet` or `camel-jetty`. If you find a need for using Jetty,
-then Camel CLI will not support seamless rest-dsl support and exporting.
-
-When a route is started from `platform-http` then Camel CLI will automatically include a VertX HTTP server
-running on port 8080. For example, the following route in a file named `server.yaml`:
-
-[source,yaml]
-----
-- route:
- from:
- uri: platform-http:/hello
- steps:
- - set-body:
- constant: "Hello World"
-----
-
-Can be run with
-
-[source,bash]
-----
-camel run server.yaml
-----
-
-And you can call the HTTP service with:
-
-[source,bash]
-----
-$ curl http://localhost:8080/hello
-Hello World%
-----
-
-=== Using Java beans and processors
-
-There is basic support for including regular Java source files together with Camel routes,
-and let Camel CLI runtime compile the Java source. This means you can include smaller utility
-classes, POJOs, Camel Processors and whatnot that the application needs.
-
-=== Dependency Injection in Java classes
-
-When running Camel integrations with camel-jbang, then the runtime is `camel-main` based. This means
-there is no Spring Boot or Quarkus available.
-However, we have added support for using annotation-based dependency injection in Java classes.
-
-==== Using Camel dependency injection
-
-You can use the following Camel annotations on Camel standalone:
-
-- `@org.apache.camel.BindToRegistry` on class level (for custom beans, processors, etc.) to create an instance of the class and register in the xref:registry.adoc[Registry].
-- `@org.apache.camel.Configuration` on class level for `CamelConfiguation` classes, which is used during Camel startup (only Camel Main runtime) to allow custom setup that requires some coding.
-
-And these annotations should work on all runtimes
-(if target runtime is either Quarkus or Spring Boot then favour using their annotations):
-
-- `@org.apache.camel.BeanInject` to dependency inject a bean on a class field.
-- `@org.apache.camel.PropertyInject` to inject a xref:using-propertyplaceholder.adoc[property placeholder]. Such as a property defined in `application.properties`.
-- `@org.apache.camel.BindToRegistry` on a method to create a bean by invoking the method.
-- `@org.apache.camel.Converter` on class level to auto-register the xref:type-converter.adoc[type converters] from the class.
-
-IMPORTANT: You can use `@BeanInject` annotation to refer to existing bean annotated with `@BindToRegistry`, however, this is possible if the dependency is registered before the dependant.
-
-==== Using Spring Boot dependency injection
-
-You can use the following Spring Boot annotations:
-
-- `@org.springframework.stereotype.Component` or `@org.springframework.stereotype.Service` on class level to create an instance of the class and register in the xref:registry.adoc[Registry].
-- `@org.springframework.beans.factory.annotation.Autowired` to dependency inject a bean on a class field. `@org.springframework.beans.factory.annotation.Qualifier` can be used to specify the bean id.
-- `@org.springframework.beans.factory.annotation.Value` to inject a xref:using-propertyplaceholder.adoc[property placeholder]. Such as a property defined in `application.properties`.
-- `@org.springframework.context.annotation.Bean` on a method to create a bean by invoking the method.
-
-==== Using Quarkus injection
-
-You can use the following Quarkus annotations:
-
-- `@jakarta.enterprise.context.ApplicationScoped` or `@jakarta.inject.Singleton` on class level to create an instance of the class and register in the xref:registry.adoc[Registry]. `@jakarta.inject.Named` can be used to specify the bean id.
-- `@jakarta.inject.Inject` to dependency inject a bean on a class field. `@jakarta.inject.Named` can be used to specify the bean id.
-- `@org.eclipse.microprofile.config.inject.ConfigProperty` to inject a xref:using-propertyplaceholder.adoc[property placeholder]. Such as a property defined in `application.properties`.
-- `@jakarta.enterprise.inject.Produces` on a method to create a bean by invoking the method. `@jakarta.inject.Named` can be used to specify the bean id.
-
-==== Using beans in Camel XML DSL
-
-Since Camel *4.0.0*, when using xref:components:others:java-xml-io-dsl.adoc[XML DSL],
-we can declare additional beans in a similar way as in xref:components:others:yaml-dsl.adoc[YAML DSL].
-Such beans will be added to the xref:registry.adoc[Registry] and can be referred to, for example, from routes.
-
-[source,xml]
-----
-<camel>
-
- <bean name="beanFromMap" type="com.acme.MyBean">
- <properties>
- <property key="foo" value="bar" />
- </properties>
- </bean>
-
-</camel>
-----
-
-The properties of the bean can be defined using either nested `<property>` and `<properties>` elements or using dotted properties style, as shown in the example below:
-
-[source,xml]
-----
-<camel>
-
- <!-- nested properties style -->
- <bean name="beanFromMap" type="com.acme.MyBean">
- <properties>
- <property key="field1" value="f1_p" />
- <property key="field2" value="f2_p" />
- <property key="nested">
- <properties>
- <property key="field1" value="nf1_p" />
- <property key="field2" value="nf2_p" />
- </properties>
- </property>
- </properties>
- </bean>
-
- <!-- dotted properties style -->
- <bean name="beanFromProps" type="com.acme.MyBean">
- <properties>
- <property key="field1" value="f1_p" />
- <property key="field2" value="f2_p" />
- <property key="nested.field1" value="nf1_p" />
- <property key="nested.field2" value="nf2_p" />
- </properties>
- </bean>
-
-</camel>
-----
-
-==== Using Spring beans in Camel XML DSL
-
-Since Camel *4.0.0*, when using xref:components:others:java-xml-io-dsl.adoc[XML DSL], we can also declare _beans_ using Spring Beans XML namespace.
-All these beans will be added to the xref:registry.adoc[Registry].
-
-This will not make the application managed by Spring Framework / Spring Boot. Simply Camel will leverage existing support for generic bean definition including:
-
-* dependency injection
-* constructor injection
-* dependency cycles
-* wiring existing Camel objects (like `org.apache.camel.CamelContext`)
-
-xref:components:others:java-xml-io-dsl.adoc[XML DSL] allows using XML documents that define routes, rests and route templates. Since Camel *4.0.0* these documents may use a new root XML element (either `<camel>` or `<beans>` to resemble Spring XML DSL), where other Camel elements (like `<routes>`) are contained.
-
-Here's an example `camel.xml` file, which defines both the routes and beans used (referred to) by the route definition:
-
-.camel.xml
-[source,xml]
-----
-<camel>
-
- <beans xmlns="http://www.springframework.org/schema/beans">
- <bean id="messageString" class="java.lang.String">
- <constructor-arg index="0" value="Hello"/>
- </bean>
-
- <bean id="greeter" class="org.apache.camel.main.app.Greeter">
- <description>Spring Bean</description>
- <property name="message">
- <bean class="org.apache.camel.main.app.GreeterMessage">
- <property name="msg" ref="messageString"/>
- </bean>
- </property>
- </bean>
- </beans>
-
- <route id="my-route">
- <from uri="direct:start"/>
- <bean ref="greeter"/>
- <to uri="mock:finish"/>
- </route>
-
-</camel>
-----
-
-This document contains embedded `<beans>` element using Spring Beans XML namespace (`http://www.springframework.org/schema/beans`) - Camel passes this element directly to Spring `org.springframework.beans.factory.xml.XmlBeanDefinitionReader` and all read beans are used to populate xref:registry.adoc[Camel Registry].
-
-The beans declared this way may use references to some predefined Camel beans.
-Currently, these are handled:
-
-* `_CamelContext_`: an instance of current `org.apache.camel.CamelContext`
-* `_MainConfiguration_`: an instance of `org.apache.camel.main.MainConfigurationProperties` used for `org.apache.camel.main.KameletMain`
-
-So we can use this XML fragment without actually defining what `CamelContext` is.
-
-[source,xml]
-----
-<camel>
-
- <beans xmlns="http://www.springframework.org/schema/beans">
- <bean id="greeter" class="org.apache.camel.main.app.Greeter">
- <property name="camelContext" ref="CamelContext"/>
- <!-- ... -->
- </bean>
- </beans>
-
- <route id="my-route">
- <from uri="direct:start"/>
- <bean ref="greeter"/>
- <to uri="mock:finish"/>
- </route>
-
-</camel>
-----
-
-What's more, we can declare some additional beans that can affect internal mechanics of `CamelContext` being run. `org.apache.camel.main.DefaultConfigurationConfigurer` is used by xref:components:others:main.adoc[Camel Main] to configure `CamelContext` using beans found in xref:registry.adoc[Camel Registry].
-
-For example, we can customize used `org.apache.camel.spi.UuidGenerator` with this XML fragment to replace UUID generator used by Camel (which defaults to `org.apache.camel.support.DefaultUuidGenerator`):
-
-[source,xml]
-----
-<camel>
-
- <beans xmlns="http://www.springframework.org/schema/beans">
- <bean id="customUUIDGenerator" class="org.apache.camel.support.ShortUuidGenerator" />
- </beans>
-
-</camel>
-----
-
-That's it - Camel context will then look up for the instances of `org.apache.camel.spi.UuidGenerator` and if one is found, it'll be used by Camel.
-
-=== Configuring JDBC DataSources
-
-When using SQL databases, then you would often need to configure a JDBC connection pool. You can do this:
-
-- Manually by adding 3rd party JAR dependency for the data source (and connection pool), and configure this from Java or XML/YAML DSL.
-- *Camel 4.6* Spring Boot style with `spring.datasource.` configuration in `application.properties` (uses Hikari connection-pool)
-
-==== Defining datasource in YAML DSL as a bean
-
-Here is a snippet how you can declare a bean as the `DataSource` for a Postgres database in YAML DSL:
-
-[source,yaml]
-----
-- beans:
- - name: PostgresqlDataSource
- properties:
- databaseName: "postgres"
- password: "postgres"
- portNumber: "5432"
- serverName: localhost
- user: postgres
- type: org.postgresql.ds.PGSimpleDataSource
-----
-
-You would then also need to add the JAR dependency with Maven coordinates: `org.postgresql:postgresql:42.7.3`.
-
-==== Using a Spring Boot JDBC data source
-
-NOTE: The `spring.datasource.` configuration is intended for rapid prototyping with Camel CLI,
-and for users who plan to export to the Spring Boot runtime.
-It is not supported when exporting to the default Camel Main runtime or Camel Quarkus.
-
-In `application.properties` you can set up the datasource such as:
-
-[source,properties]
-----
-spring.datasource.url= jdbc:sqlserver://db.example.net:1433;databaseName=test_db
-spring.datasource.username=user
-spring.datasource.password=password
-spring.datasource.driverClassName=com.microsoft.sqlserver.jdbc.SQLServerDriver
-----
-
-The name of the `DataSource` will be registered with `springDataSource`, however you can configure the name via:
-
-[source,properties]
-----
-spring.datasource.name=myDataSourceNameHere
-----
-
-TIP: Some JDBC drivers are automatic detected by camel-jbang.
-If not, then you need to add the JAR dependency manually.
-
-And you can configure the Hikari connection-pool (if needed), such as:
-
-[source,properties]
-----
-spring.datasource.hikari.connection-timeout=30000
-spring.datasource.hikari.maximum-pool-size=10
-spring.datasource.hikari.minimum-idle=5
-spring.datasource.hikari.idle-timeout=600000
-spring.datasource.hikari.max-lifetime=1800000
-spring.datasource.hikari.pool-name=collection-pool
-----
-
-And you can set logging to DEBUG on hikari to see the actual configuration:
-
-[source,properties]
-----
-logging.level.com.zaxxer.hikari = DEBUG
-----
-
-=== Debugging
-
-There are two kinds of debugging:
-
-* _Java debugging_: Java code debugging (Standard Java)
-* _Camel route debugging_: Debugging Camel routes (requires Camel tooling plugins)
-
-==== Java debugging
-
-Camel CLI makes it easy to do _Java debugging_ when you run your integration with the `--jvm-debug` option as shown below:
-
-[source,bash]
-----
-camel run hello.yaml --jvm-debug
-Listening for transport dt_socket at address: 4004
-----
-
-As you can see the default listening port is 4004 but can be configured as described in https://www.jbang.dev/documentation/guide/latest/debugging.html[JBang Debugging].
-
-This is a standard Java debug socket. You can then use the IDE of your choice. For instance, see the generic documentation for https://www.jetbrains.com/help/idea/attaching-to-local-process.html#create-rc[IntelliJ], https://code.visualstudio.com/docs/java/java-debugging#_attach[VS Code] and https://www.vogella.com/tutorials/EclipseDebugging/article.html#remote-debugging[Eclipse Desktop]. You will surely want to add `Processor` to be able to put breakpoints hit during route execution (as [...]
-
-===== Standard JBang debugging
-
-You can debug your integration scripts by making use of the `--debug` flag provided by JBang.
-
-[source,bash]
-----
-jbang --debug camel@apache/camel run hello.yaml
-Listening for transport dt_socket at address: 4004
-----
-
-This makes it possible to debug any of the Camel CLI commands, not only the `run` command as shown above.
-
-==== Camel route debugging
-
-With *Camel 4.2* onwards you can now easily debug Camel routes from the command shell with the `debug` command as shown below:
-
-[source,bash]
-----
-camel debug hello.yaml
-----
-
-This will run the integration (in background), and the current shell running in foreground will act as a CLI based debugger.
-You can see snippets from the log (in the top), the middle section shown the current breakpoint.
-And in the bottom you can see content of the message (similar to the `camel trace` command)
-
-[source,text]
-----
-2023-11-03 18:15:06.715 INFO 33384 --- [ main] g.apache.camel.main.BaseMainSupport : [Command Line] camel.debug.loggingLevel=DEBUG
-2023-11-03 18:15:06.715 INFO 33384 --- [ main] g.apache.camel.main.BaseMainSupport : [Command Line] camel.debug.singleStepIncludeStartEnd=true
-2023-11-03 18:15:06.787 INFO 33384 --- [ main] mel.cli.connector.LocalCliConnector : Camel CLI enabled (local)
-2023-11-03 18:15:06.833 INFO 33384 --- [ main] el.impl.engine.AbstractCamelContext : Apache Camel 4.7.0 (foo) is starting
-2023-11-03 18:15:06.906 INFO 33384 --- [ main] g.apache.camel.main.BaseMainSupport : Property-placeholders summary
-2023-11-03 18:15:06.906 INFO 33384 --- [ main] g.apache.camel.main.BaseMainSupport : [application.properties] my-name=Donald Duck
-2023-11-03 18:15:06.924 INFO 33384 --- [ main] el.impl.engine.AbstractCamelContext : Routes startup (started:1)
-2023-11-03 18:15:06.924 INFO 33384 --- [ main] el.impl.engine.AbstractCamelContext : Started route-07a6 (timer://yaml)
-2023-11-03 18:15:06.924 INFO 33384 --- [ main] el.impl.engine.AbstractCamelContext : Apache Camel 4.7.0 (foo) started in 91ms (build:0ms init:0ms start:91ms)
-2023-11-03 18:15:11.951 INFO 33384 --- [ - timer://yaml] foo.camel.yaml:10 : Before:
-
-Source: foo.camel.yaml:13 History
--------------------------------------------------------------------------------- ------------------------------------------------------------------------------------------
- 10: - log: route-07a6/from-c041 (0ms) 4: uri: timer
- 11: message: 'Before: ${body}' route-07a6/log1 (1ms) 10: - log:
- 12: id: log1
- 13: ---> - setProperty:
- 14: name: myProp
- 15: expression:
- 16: constant:
- 17: expression: '123'
- 18: id: constant-4004
-
-
-2023-11-03 18:15:11.951 33384 --- [ thread #4 - timer://yaml] route-07a6/setProperty-321c : 3 - Breakpoint (4ms)
- Exchange (DefaultExchange) InOnly D48642E54410AF9-0000000000000000
- Message (DefaultMessage)
- Body (null)
-
-
- Breakpoint suspended. Press ENTER to continue.
-----
-
-This is _basic_ but yet powerful, as you have this debugger always readily available, without having to start up VSCode or IDEA tooling.
-
-TIP: The `camel debug` can debug almost all the DSLs (there is a problem with groovy).
-
-===== Configuring breakpoints
-
-When using `camel debug` then breakpoints are by default added to every route.
-However, you can specify which breakpoints to use instead with the `--breakpoint` option.
-This parameter is able to match the Camel routes using a pattern style:
-
-1. Exact match by node ids
-2. Match node ids by pattern (wildcard and regular expression)
-3. Match by EIP kind (setHeader, setBody, choice, split, etc.)
-4. Match by source and line number
-5. Match by line number
-
-Multiple breakpoints can be separated by comma.
-
-For example, to set a breakpoint at the setHeader EIP, you do:
-
-[source,bash]
-----
-camel debug hello.yaml --breakpoint=setHeader
-----
-
-To set a breakpoint at line 18:
-
-[source,bash]
-----
-camel debug hello.yaml --breakpoint=18
-----
-
-To set a breakpoint at line 18 and 34
-
-[source,bash]
-----
-camel debug hello.yaml --breakpoint=18,34
-----
-
-===== Camel Spring Boot route debugging
-
-In *Camel 4.14* we added support for using Camel CLI to debug an existing Camel Spring Boot Maven based project.
-
-All that is needed is to execute:
-
-[source,bash]
-----
-camel debug pom.xml
-----
-
-This tells Camel CLI to look inside the Maven pom.xml file and if `camel-spring-boot-bom` is detected,
-then Camel CLI will automatically run Spring Boot with debugging enabled. This is done by letting Spring Boot
-compile and build a fat-jar, that then is launched in the background and the output is shown in the console; just as shown
-above. You will then get the same user experience as debugging plain Camel Main files.
-
-==== Editing code using VSCode or IDEA editors
-
-You can use JBang to edit the source code by using the `jbang` CLI to download dependencies,
-and set up a project for being ready to load into an IDE of choice, such as IDEA, VSCode, or Eclipse.
-
-This is typically in use when you use Java DSL and have Camel routes in .java source code.
-To let JBang understand which dependencies are in use, then you need to use JBang style for specifying
-dependencies by using `//DEPS` code comments in Java code.
-
-TIP: If you specify `//DEPS` in YAML DSL then this must be in the syntax as `\#//DEPS`
-as YAML uses leading `#` in commented lines.
-
-Given the following source file in `foo.java` file:
-
-[source,java]
-----
-//DEPS org.apache.camel:camel-bom:4.3.0@pom
-//DEPS org.apache.camel:camel-endpointdsl
-//DEPS org.apache.camel:camel-netty-http
-//DEPS org.apache.camel:camel-stream
-
-// add more dependencies here
-
-import org.apache.camel.builder.endpoint.EndpointRouteBuilder;
-import org.apache.camel.component.netty.http.NettyHttpMessage;
-import org.slf4j.Logger;
-import org.slf4j.LoggerFactory;
-
-public class foo extends EndpointRouteBuilder {
-
- private static final Logger LOG = LoggerFactory.getLogger(foo.class);
-
- @Override
- public void configure() {
- from(timer("trigger").period(5000).repeatCount(3))
- .to(nettyHttp("https://random-data-api.com/api/v2/banks").keepAlive(true))
- .process(e -> {
- // use classes from camel-netty-http dependency in the source code
- // and have jbang able to generate project with the dependencies ready
- // to use in your IDE of choice
- NettyHttpMessage msg = e.getMessage(NettyHttpMessage.class);
- LOG.info("Netty HTTP response:\n\n\n{}\n\n\n", msg.getHttpResponse());
- })
- .log("Found bank:")
- .to(stream("out"));
- }
-}
-----
-
-TIP: You can use `camel dependency update foo.java` to update the dependencies.
-
-Notice how we specify https://www.jbang.dev/documentation/guide/latest/dependencies.html[JBang dependencies] at the top of the file.
-We want JBang to know and prepare for the IDE of choice.
-The first `//DEPS` is the `@pom` which set up the Camel version to use.
-The following `//DEPS` declares the Camel component we use.
-
-You can now open this source file for editing in your IDE of choice by using jbang CLI as follows:
-
-[source,bash]
-----
-$ jbang edit -b foo.java
-----
-
-You can find this example at: https://github.com/apache/camel-kamelets-examples/tree/main/jbang/jbang-edit
-
-==== Updating dependencies in source code
-
-When working with Java source code, then you can keep the JBang dependencies up to date using the following command:
-
-[source,bash]
-----
-$ camel dependency update foo.java
-----
-
-TIP: You can use `--clean` to not keep any existing dependencies and generate a clean fresh list.
-
-This will then automatic insert or update the JBang dependencies (`//DEPS`) in the top of the source file.
-
-You may want to use this for making it easier to load the source into an IDE editor to do coding.
-See the previous section for more details.
-
-===== Updating dependencies in Maven projects
-
-Camel CLI can also help with keeping Camel Maven dependencies up-to-date for Maven based projects.
-
-For example if start using new Camel components, in your Camel routes. Then you would have to
-add the corresponding Camel JAR dependencies to the pom.xml file.
-
-You can use the `camel dependency update` command to automate this, by executing from the project folder:
-
-[source,bash]
-----
-$ camel dependency update pom.xml
-----
-
-Notice, that only adding new Camel dependencies is supported. If you remove a component,
-then you need to remove the dependency from the pom.xml manually.
-Also, this is only intended for production code from `src/main` folder.
-
-==== Camel route debugging using VSCode or IDEA editors
-
-The Camel route debugger is available by default (the `camel-debug` component is automatically added to the classpath). By default, it can be reached through JMX at the URL `service:jmx:rmi:///jndi/rmi://localhost:1099/jmxrmi/camel`.
-
-You can then use the Integrated Development Environment (IDE) of your choice. For instance, https://plugins.jetbrains.com/plugin/9371-apache-camel[IntelliJ], https://marketplace.visualstudio.com/items?itemName=redhat.vscode-debug-adapter-apache-camel[VS Code] or https://marketplace.eclipse.org/content/textual-debugging-apache-camel[Eclipse Desktop].
-
-A specific how-to is available for VS Code, see this https://youtu.be/owNhWxf42qk[video].
-
-TIP: When exporting to Maven projects, then you can use the maven profile `camel.debug` that will include the `camel-debug` JAR
-to make it possible for Camel IDE tools to do Camel route debugging.
-
-==== Health Checks
-
-The status of health checks can be accessed via Camel CLI from the CLI as follows:
-
-[source,bash]
-----
-camel get health
- PID NAME AGE ID RL STATE RATE SINCE MESSAGE
- 61005 mybind 8s camel/context R UP 2/2/- 1s/3s/-
-----
-
-Here we can see the Camel is _UP_. The application has just been running for 8 seconds, and there
- have been two health checks invoked.
-
-The output is showing the _default_ level of checks as:
-
-- `CamelContext` health check
-- Component-specific health checks (such as from `camel-kafka` or `camel-aws`, ...)
-- Custom health checks
-- Any check that are not UP
-
-The _RATE_ column shows 3 numbers separated by `/`. So `2/2/-` means two checks in total, two successes, and no failures.
-The two last columns will reset when a health check changes state as this number is the number of consecutive
-checks that was successful or failure. So if the health check starts to fail, then the numbers could be:
-
-[source,bash]
-----
-camel get health
- PID NAME AGE ID RL STATE RATE SINCE MESSAGE
- 61005 mybind 3m2s camel/context R UP 77/-/3 1s/-/17s some kind of error
-----
-
-Here we can see the numbers are changed to `77/-/3`. This means the total is 77. There is no success, but
-the check has been failing three times in a row. The _SINCE_ column corresponds to the _RATE_. So in this
- case, we can see the last check was 1 second ago, and that the check has been failing for 17 seconds in a row.
-
-You can use `--level=full` to output every health check, that will include consumer and route level checks
-as well.
-
-A health check may often be failed due to an exception was thrown which can be shown via `--trace` flag:
-
-[source,bash]
-----
-camel get health --trace
- PID NAME AGE ID RL STATE RATE SINCE MESSAGE
- 61038 mykafka 6m19s camel/context R UP 187/187/- 1s/6m16s/-
- 61038 mykafka 6m19s camel/kafka-consumer-kafka-not-secure... R DOWN 187/-/187 1s/-/6m16s KafkaConsumer is not ready - Error: Invalid url in bootstrap.servers: value
-
-
-------------------------------------------------------------------------------------------------------------------------
- STACK-TRACE
-------------------------------------------------------------------------------------------------------------------------
- PID: 61038
- NAME: mykafka
- AGE: 6m19s
- CHECK-ID: camel/kafka-consumer-kafka-not-secured-source-1
- STATE: DOWN
- RATE: 187
- SINCE: 6m16s
- METADATA:
- bootstrap.servers = value
- group.id = 7d8117be-41b4-4c81-b4df-cf26b928d38a
- route.id = kafka-not-secured-source-1
- topic = value
- MESSAGE: KafkaConsumer is not ready - Error: Invalid url in bootstrap.servers: value
- org.apache.kafka.common.KafkaException: Failed to construct kafka consumer
- at org.apache.kafka.clients.consumer.KafkaConsumer.<init>(KafkaConsumer.java:823)
- at org.apache.kafka.clients.consumer.KafkaConsumer.<init>(KafkaConsumer.java:664)
- at org.apache.kafka.clients.consumer.KafkaConsumer.<init>(KafkaConsumer.java:645)
- at org.apache.kafka.clients.consumer.KafkaConsumer.<init>(KafkaConsumer.java:625)
- at org.apache.camel.component.kafka.DefaultKafkaClientFactory.getConsumer(DefaultKafkaClientFactory.java:34)
- at org.apache.camel.component.kafka.KafkaFetchRecords.createConsumer(KafkaFetchRecords.java:241)
- at org.apache.camel.component.kafka.KafkaFetchRecords.createConsumerTask(KafkaFetchRecords.java:201)
- at org.apache.camel.support.task.ForegroundTask.run(ForegroundTask.java:123)
- at org.apache.camel.component.kafka.KafkaFetchRecords.run(KafkaFetchRecords.java:125)
- at java.base/java.util.concurrent.Executors$RunnableAdapter.call(Executors.java:515)
- at java.base/java.util.concurrent.FutureTask.run(FutureTask.java:264)
- at java.base/java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1128)
- at java.base/java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:628)
- at java.base/java.lang.Thread.run(Thread.java:829)
- Caused by: org.apache.kafka.common.config.ConfigException: Invalid url in bootstrap.servers: value
- at org.apache.kafka.clients.ClientUtils.parseAndValidateAddresses(ClientUtils.java:59)
- at org.apache.kafka.clients.ClientUtils.parseAndValidateAddresses(ClientUtils.java:48)
- at org.apache.kafka.clients.consumer.KafkaConsumer.<init>(KafkaConsumer.java:730)
- ... 13 more
-----
-
-Here we can easily see that the health check is failing because of the `org.apache.kafka.common.config.ConfigException`
-which is due to invalid configuration: `Invalid url in bootstrap.servers: value`.
-
-TIP: Use `camel get health --help` to see all the various options.
-
-
-== Running with Spring Boot or Quarkus
-
-Camel CLI is __primary__ intended to be Camel standalone only. In *Camel 4.6* onwards, we added limited
-support for running with Spring Boot or Quarkus, but there are some limitations.
-
-You use the `--runtime` option to specify which platform to use, as shown below:
-
-[source,bash]
-----
-camel run foo.camel.yaml --runtime=spring-boot
-----
-
-And for Quarkus:
-
-[source,bash]
-----
-camel run foo.camel.yaml --runtime=quarkus
-----
-
-When running this way, then Camel CLI is _essentially_ doing an _export_ to a temporary folder,
-and then running Spring Boot or Quarkus using Maven.
-
-You can do changes to the source file and have Quarkus and Spring Boot reload the routes, just as `camel run --dev` can do,
-but uses the natural Spring Boot _dev-tools_ and Quarkus _dev mode_ functionality.
-
-There are several limitations, one would be that Spring Boot and Quarkus cannot automatically detect new components and download JARs.
-(you can stop and run again to update dependencies).
-
-When using Quarkus, then you can only select the Quarkus version to run. That is locked to a specific Camel version.
-You can see the versions by `camel version list --runtime=quarkus`. On the other hand Spring Boot is more flexible
-where you can choose different Spring Boot and Camel versions (within reasonable range).
-
-For example:
-
-[source,bash]
-----
-camel run foo.camel.yaml --runtime=spring-boot --spring-boot-version=3.2.3 --camel-version=4.4.1
-----
-
-And for Quarkus:
-
-[source,bash]
-----
-camel run foo.camel.yaml --runtime=quarkus --quarkus-version=3.9.4
-----
-
-
-== Transforming message (data mapping)
-
-When integrating a system, you often need to transform messages from one system to another. Camel has a rich set
-of capabilities for this such as various data formats, templating languages, and much more. However, for basic
-data mapping such as taking an existing incoming JSON document and transforming this to a smaller JSON document,
-you may want to do this quickly with Camel.
-
-The `camel transform message` command can be used for such tasks, where it can take an existing source file as input,
-and then a template that defines how to transform the data, and then show the output (in real time).
-
-For example, given this JSon document (in a file named `random.json`), we want to combine the name, and select a few fields:
-
-[source,json]
-----
-{
- "id": 9914,
- "uid": "eb5fa603-1db6-45f9-912a-431a6ed59b18",
- "password": "ei7gvYKdnN",
- "first_name": "Khalilah",
- "last_name": "Monahan",
- "username": "khalilah.monahan",
- "email": "khalilah.monahan@email.com",
- "avatar": "https://robohash.org/utnumquamexcepturi.png?size=300x300&set=set1",
- "gender": "Agender",
- "phone_number": "+54 (421) 591-5640 x333",
- "social_insurance_number": "268418308",
- "date_of_birth": "1975-03-11",
- "employment": {
- "title": "Product Design Director",
- "key_skill": "Work under pressure"
- },
- "address": {
- "city": "New Fritzchester",
- "street_name": "Patrick Common",
- "street_address": "4538 Reggie Inlet",
- "zip_code": "16282-7045",
- "state": "New York",
- "country": "United States",
- "coordinates": {
- "lat": -1.9868753435474673,
- "lng": 39.09763956726292
- }
- },
- "credit_card": {
- "cc_number": "4493983042212"
- },
- "subscription": {
- "plan": "Student",
- "status": "Active",
- "payment_method": "Debit card",
- "term": "Monthly"
- }
-}
-----
-
-Then we can have a `transform.json` file as the beginning of the template, with the structure of the desired output:
-
-[source,json]
-----
-{
- "sid": 123,
- "name": "TODO",
- "country": "TODO",
- "phone": "TODO",
- "student": false
-}
-----
-
-We can then run `camel transform message` and have it update (in real time) the output every time we change the template.
-
-[source,bash]
-----
-$ camel transform message --body=file:random.json --language=simple --template=file:transform.json --pretty --watch
-----
-
-What happens is then Camel will output on the console as you go:
-
-[source,bash]
-----
- Exchange (DefaultExchange) InOut 23F5DD4CE6C260B-0000000000000002
- Message (DefaultMessage)
- Body (String) (bytes: 118)
- {
- "sid": 123,
- "name": "TODO",
- "country": "TODO",
- "phone": "TODO",
- "student": false
- }
-----
-
-Then you can update the `transform.json` file and save it and see the generated output:
-
-[source,json]
-----
-{
- "sid": ${jq(.id)},
- "name": "${jq(.first_name)} ${jq(.last_name)}",
- "country": "TODO",
- "phone": "TODO",
- "student": false
-}
-----
-
-And the output:
-
-[source,bash]
-----
- Exchange (DefaultExchange) InOut 23F5DD4CE6C260B-0000000000000018
- Message (DefaultMessage)
- Body (String) (bytes: 158)
- {
- "sid": 9914,
- "name": "Khalilah Monahan",
- "country": "TODO",
- "phone": "TODO",
- "student": false
- }
-----
-
-Then you can continue to update the `transform.json` until you have the desired result.
-And if you make a mistake, then you see an error (in red) with stacktrace that hopefully can help you out how to fix this.
-
-=== Transforming directly from the Camel DSL source
-
-In the example above we externalize the transformation into a template file named `transform.json`.
-However, it's possible to transform directly in the Camel DSL route.
-
-NOTE: Currently Java DSL is not working in --watch mode (reload on change)
-
-In the following, we cover the json-transform example from: https://github.com/apache/camel-kamelets-examples/tree/main/jbang/json-transform
-
-In this example, a random beer is fetched via the beer-source kamelet. The beer data is as follows:
-
-[source,json]
-----
- {
- "id": 2104,
- "uid": "cefb36e1-e42f-4083-8f97-fc4ff85e56fb",
- "brand": "Pabst Blue Ribbon",
- "name": "St. Bernardus Abt 12",
- "style": "Belgian Strong Ale",
- "hop": "Amarillo",
- "yeast": "1388 - Belgian Strong Ale",
- "malts": "Caramel",
- "ibu": "43 IBU",
- "alcohol": "3.8%",
- "blg": "16.0°Blg"
- }
-----
-
-We save this beer into a file named `sample.json` as we want to use this as source for message transformation.
-
-Now suppose we want to transform this to a smaller JSON document with only a few elements, then we can do this
-directly in the route:
-
-[source,yaml]
-----
-- route:
- nodePrefixId: route-c38
- id: route-66b0
- from:
- uri: kamelet:beer-source
- id: from-3996
- steps:
- - setBody:
- expression:
- simple:
- expression: >-
- TODO
- id: simple-b320
- id: setBody-fa01
- - log:
- message: ${body}
- id: log-0c79
-----
-
-As we can see the route has a `setBody` where we want to transform the message, which we can do with the simple
-language combined with JQ (or JSonPath). At first, we just write TODO to get started:
-
-[source,bash]
-----
-camel transform message --body=file:sample.json --source=beer-jq.yaml --watch --pretty
-----
-
-And the output from the transformation is:
-
-[source,text]
-----
- Exchange (DefaultExchange) InOut D9F909701338607-0000000000000004
- Message (DefaultMessage)
- Body (String) (bytes: 4)
- TODO
... 1365 lines suppressed ...