Camel JBang

Camel JBang provides shell completion for bash and zsh out of the box. To enable shell completion for Camel JBang, run:

To make it permanent, run:

You can run more than 1 file, for example to run two YAML files you can do:

You can also mix different DSLs such as yaml and Java:

You can also use wildcards (i.e. *) to match multiple files, such as running all the yaml files:

Or you can run all files starting with foo*

And to run everything

For very small Java routes then it is possible to provide the route as CLI argument, as shown below:

This is very limited as the CLI argument is a bit cumbersome to use than files.

You can also run dev mode when running Camel with --source-dir, such as:

This starts Camel where it will load the files from the source dir (also sub folders).

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 too.

You can run Camel JBang by stubbing those components (or all of them).

For example suppose you need access to a JMS broker in the given route below.

Then you can run this by stub the jms component by:

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:

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:

Then only the jms:inbox endpoint is stubbed.

Camel JBang comes with the camel cmd stub command that allows to list all endpoints which 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.

And to browse the messages:

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:

Then while the Camel integration is running, you can update the YAML route and update when saving.

This works for all DLS even java, so you can do:

You can also run dev mode when running Camel with --source-dir, such as:

This starts Camel where it will load the files from the source dir (also sub folders). 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:

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 sub folders) are automatic detected and reloaded. You can also delete files to remove routes.

You can enable the developer console, which presents a variety of information to the developer.

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 pin-point, 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:

And if you have jq installed which can format and output the JSon data in colour, then do:

Camel JBang have the concept of profiles. A profile is essentially a name (id) that refers to which configuration to automatic load with Camel JBang. The default profile is named application which is a (smart default) to let Camel JBang automatic load application.properties (if present).

This means that creating profiles matching to a properties file with the same name.

For example having a profile named local, means that Camel JBang will load local.properties instead of application.properties.

To use a profile, you specify as command line option --profile such as:

You can only specify one profile name, i.e. --profile=local,two is not valid.

In the properties files you can configure all the configurations from Camel Main.

For example to turn off Stream Caching and enable log masking you can specify:

And you can also configure Camel components such as camel-kafka to declare the URL to the brokers:

By default, Camel JBang 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 automatic download the JARs (incl transitive).

Camel will download these JARs in the following order:

If you do not want Camel JBang to download over the internet, you can turn this off with --download, as shown below:

If you do not want Camel JBang to use your existing Maven settings file, you can use:

Camel JBang 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 --deps as CLI argument in Maven GAV syntax (groupId:artifactId:version), such as:

In case you need to explicit add a Camel dependency you can use a shorthand syntax (starting with camel: or camel-) such as:

You can specify multiple dependencies separated by comma:

Camel JBang 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

The configuration for the 3rd-party Maven repositories can also be configured in application.properties with the key camel.jbang.repos as shown:

And when running Camel then application.properties is automatically loaded:

However, you can also explicit specify the properties file to use:

And even better if you specify this as a profile:

Where the profile id is the name of the properties file.

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:

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:

The above password should be added to ~/.m2/settings-security.xml file like this:

Then a normal password can be configured like this:

Finally, such password 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. Location of the settings.xml file itself can be specified as well:

If you want to run Camel application without assuming any location (even ~/.m2/settings.xml), use this option:

You can run a route that is hosted on GitHub using Camels github resource loader.

For example to run one of the Camel K examples you can do:

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 JBang:

You can also use wildcards (i.e. *) to match multiple files, such as running all the groovy files:

Or you can run all files starting with rou*

We have made it easy for Camel JBang 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:

Then the files (not sub folders) are downloaded to the current directory. The example can then be run locally with:

You can also download to a new folder using the --directory option, for example to download to a folder named myproject, you would do:

You can also run in dev mode, to hot-deploy on source code changes.

You can also download a single file, such as one of the Camel K examples:

This is a groovy route, which you can run with (or use *):

You can specify which Camel version to run as shown:

In Camel 3.20.2 onwards the run command has built-in support, using --camel-version, for specifying Camel version to use for the running Camel integration.

You can also try bleeding edge development by using SNAPSHOT such as:

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 JBang CLI and run integrations using an older Camel version.

Here Camel JBang is using version 3.20.3. Now suppose we want to run Camel integrations with version 3.18.2.

And you can see what Camel version has been set by:

And when running an integration, then Camel JBang will show you the version override when starting.

If you want to unset the version, you can use the --reset option:

Then the Camel version in use will be the same version as Camel JBang.

Camel also supports running Camel K integrations and binding files, which are in CRD format (Kubernetes Custom Resource Definitions).

For example a pipe file named joke.yaml:

Can be run with camel:

You can also run Camel routes directly from the OS clipboard. This allows to copy some code, and then quickly run this.

The syntax is

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 afterwards:

Available since Camel 4

When building integrations with Camel JBang, 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 connecting 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 scenarious, and should only be used as quick way.

Suppose you have a Camel route that consumes messages from an external MQTT broker:

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, 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 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 its better to refer to a local file.

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 have 1 route, then the send command will automatic 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:

Or to pick the first route that uses mqtt component:

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.

The source for this example is provided on GitHub at camel-jbang MQTT example.

To list the currently running Camel integrations you use the ps command:

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

You can also stop by the PID:

To stop all integrations, then execute without any pid:

The 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 JBang.

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:

With the PID you can then attach 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:

Then you can launch Hawtio using Camel JBang:

This will automatically download and start Hawtio, and open in web browser.

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:

It is also possible to do this with only one command, as follows:

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.

You can also execute a Camel JBang file as a script that can be used for terminal scripting with pipes and filters.

This requires to add the following line in top of the file, for example as in the upper.yaml file below:

To be able to execute this as a script, you need to set execute file permission:

Then you can then execute this as a script:

Which should output:

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.

You can also use Camel JBang to try local Kamelets, without the need to publish them on GitHub or package them in a jar.

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:

When a route is started from platform-http then Camel JBang will automatically include a VertX HTTP server running on port 8080. For example the following route in a file named server.yaml:

Can be run with

And you can call the HTTP service with:

There is basic support for including regular Java source files together with Camel routes, and let Camel JBang runtime compile the Java source. This means you can include smaller utility classes, POJOs, Camel Processors and whatnot that the application needs.

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.

There are two kinds of debugging:

The doc goal can show quick documentation for every component, dataformat, kamelets etc. For example to see the kafka component you run:

To see the documentation for jackson dataformat:

In some rare cases then there may be a component and dataformat with the same name, and the doc goal prioritizes components. In such a situation you can prefix the name with dataformat, i.e:

You can also see the kamelet documentation such as shown:

You can use the camel dependency copy command to copy the required JARs to a specific folder. This command reuses Maven by invoking the mvn dependency:copy-dependencies command.

By default, the JARs are copied to lib folder:

The command export --runtime=spring-boot will export your current Camel JBang file(s) to a Maven based Spring Boot project with files organized in src/main/ folder structure.

For example to export to Spring Boot using the Maven groupId com.foo and the artifactId acme and with version 1.0-SNAPSHOT you simply execute:

To export to another directly (copies the files) you execute:

When exporting to Spring Boot then the Camel version defined in the pom.xml or build.gradle is the same version as Camel JBang uses. However, you can specify the Camel version as shown below:

The command export --runtime=quarkus will export your current Camel JBang file(s) to a Maven based Quarkus project with files organized in src/main/ folder structure.

For example to export to Quarkus using the Maven groupId com.foo and the artifactId acme and with version 1.0-SNAPSHOT you simply execute:

To export to another directly (copies the files) you execute:

The command export --runtime=camel-main will export your current Camel JBang file(s) to a Maven based vanilla Camel Main project with files organized in src/main/ folder structure.

For example to export to Camel Main using the Maven groupId com.foo and the artifactId acme and with version 1.0-SNAPSHOT you simply execute:

To export to another directly (copies the files) you execute:

By default, Camel will export what was last run, or all files from the current directory. You can also explicit specify which files should be exported.

For example, you may have 3 files in a folder:

These are 3 Camel routes, and you want to export them into 2 different applications:

As you can see the first export command will only include Foo.java, and then 2nd export includes both bar.xml and cheese.yaml.

Camel JBang exports by default as a Maven based project. To use Gradle instead, you can specify the --build-tool=gradle when exporting, such as:

Usually when exporting to Spring Boot, Quarkus or Camel Main, then JMX management is not included out of the box. To include JMX, you need to add camel:management in the --deps option, as shown below:

Usually when exporting to Spring Boot, Quarkus or Camel Main, then Camel JBang CLI is not included out of the box. To be able to continue to use Camel CLI (i.e. camel), you need to add camel:cli-connector in the --deps option, as shown below:

The export command will by default load configuration from application.properties which also can be used to specific parameters for export such as selecting the runtime and java version.

The follow options related to exporting, can be configured in application.properties:

Every Camel JBang option is added to the user configuration. For example, to export a simple project such as

User configuration keys are unset using the following:

User configuration keys are listed using the following:

Following is the output for the above mentioned configuration.

To obtain a value for the given key, use the get command.

User configuration values can be used as placeholder substitutes with command line properties, for example:

In this example, since repos is set in the user configuration (config set) and the camel run command declares the placeholder #repos, camel run will replace the placeholder so that both repositories will be used during the execution. Notice, that to refer to the configuration value the syntax is #optionName eg #repos.