Extending Ballerina CLI Functionality with Additional Tools
This article was written using Ballerina Swan Lake Update 8 (2201.8.5)
Ballerina CLI
Ballerina CLI is the Ballerina Swan Lake command line interface. It packs a ton of functionalities justifying the batteries included claim of Ballerina. Ballerina CLI helps manage Ballerina source code. It provides the following functionalities.
- Manage Ballerina packages and modules.
- Build, run, and test Ballerina programs.
- Manage Ballerina distributions.
- Generate Ballerina source code from schemas and vice versa.
To learn more about Ballerina CLI we can type bal help in the terminal to get a summary of all commands. We can use the bal help <command> to learn about a particular command. To get a comprehensive understanding of the CLI commands, we can refer to the CLI commands official documentation.
Why extend the Ballerina CLI?
Ballerina CLI functionalities are more than enough for most of the users. However, Ballerina being a programming language designed for integration, has provided commands that address specific business requirements. Following are a few of such commands.
- health — Generate a Ballerina package or template for a given health specification file.
- copybook — Generate Ballerina record types for copybook definition.
- edi — Generate the Ballerina records and parsing functions or a Ballerina package for a given EDI schema or collection of schemas.
Since these commands or tools are only required by users working on integrations with related industries or standards, they are not packed with the Ballerina distribution. Instead, from Swan Lake 2201.8.0 onwards, Ballerina has provided the tool command to manage these commands.
Tool Command
SYNOPSIS
bal tool <command> [<-h> |<--help>]
bal tool <command> [args]The tool command manages the entire lifecycle of a tool that is not packed with the distribution. These tools are distributed via the Ballerina Central. The tool command provides the following subcommands to manage the life cycle of tools.
There can be cases where a given tool version is incompatible with the locally installed Ballerina distribution. However, the tool subcommands are aware of the compatibility of a tool version with the distribution. Therefore, we, as tool users do not have to put extra effort into finding out the distribution compatibility of a tool.
Let’s understand how we can use the commands to manage a tool effectively using the health tool as an example. The health tool produces Ballerina library packages and templates designed for developing healthcare integrations, with a focus on implementing Fast Healthcare Interoperability Resources (FHIR) standards in Ballerina.
Searching for a tool
Before installing the health tool, let’s find information about it. For this purpose, the bal tool search command can be used.
$ bal tool search health
| ID | PACKAGE | DESCRIPTION | DATE | VERSION |
|--------|-------------------|-----------------------------|----------------|---------|
| health | ballerinax/health | This project contains an …. | 2024-01-31-Wed | 2.1.1 |
1 tools found.Here we can observe that there is only one tool that matches the keyword health and its latest version is 2.1.1.
Let’s install this tool and explore the functionalities.
Installing a tool
To fetch and install the health tool, we have to use the bal tool pull command.
$ bal tool pull health
ballerinax/health:2.1.1 [central.ballerina.io ->[central cache]/bala/ballerinax/health/2.1.1] 100% [==========] 93575/93575 KB
ballerinax/health:2.1.1 pulled from central successfully
tool 'health:2.1.1' pulled successfully.
tool 'health:2.1.1' successfully set as the active version.Since we haven’t specified the tool version, it pulls the latest version. We also can specify the version along with the tool ID to pull an exact version of the tool.
$ bal tool pull health:2.1.0
ballerinax/health:2.1.0 [central.ballerina.io ->[central cache]/bala/ballerinax/health/2.1.0] 100% [==========] 93136/93136 KB
ballerinax/health:2.1.0 pulled from central successfully
tool 'health:2.1.0' pulled successfully.
tool 'health:2.1.0' successfully set as the active version.We cannot pull and use a tool version that is not compatible with the current distribution.
Let’s assume health:2.2.0 is built with a newer distribution of Ballerina Swan Lake than the currently used 2201.8.5. This makes health:2.2.0 incompatible with 2201.8.5. The resultant error will be as follows.
$ bal tool pull health:2.2.0
ballerinax/health:2.2.0 [central.ballerina.io ->[central cache]/bala/ballerinax/health/2.2.0] 100% [==========] 93136/93136 KB
ballerinax/health:2.2.0 pulled from central successfully
tool 'health:2.2.0' pulled successfully.
ballerina: tool ''health:2.2.0' is not compatible with the current Ballerina distribution '2201.8.5'. Use 'bal tool search' to select a version compatible with the current Ballerina distribution.Verifying the tool installation
We can verify the installation of a tool by typing in bal help. In our case, we can see that the health tool is included in the Tool Commands section.
$ bal help
NAME
The build system and package manager of Ballerina
SYNOPSIS
bal <command> [args]
bal [OPTIONS]
OPTIONS
-v, --version
Print version information.
-h, --help
Print the usage details of a command.
COMMANDS
The available subcommands are:
Core Commands:
build Compile the current package
. . .
Package Commands:
new Create a new Ballerina package
. . .
Other Commands:
clean Clean the artifacts generated during the build
. . .
Tool Commands:
health Ballerina Health Artifact Generator Tool
Update Commands:
dist Manage Ballerina distributions
update Update the Ballerina tool
Use 'bal help <command>' for more information on a specific command.Executing a tool
Once a tool is installed, Ballerina treats it as a first-class citizen just like the other tools that are packed with the distribution. bal health will work akin to bal build or bal openapi. If we type in bal health --help, the help text of health tool is printed.
% bal health --help
NAME
ballerina-health - Generate a Ballerina package or template for a
given health specification (eg.:FHIR implementation guides) files.
SYNOPSIS
bal health fhir [-m | --mode] package --package-name <package-name> \
<FHIR-specification-directory-path>
[-m | --mode] template --dependent-package <dependent-package> \
<FHIR-specification-directory-path>
DESCRIPTION
Generate a Ballerina package or template with relevant records and types
from a given health specification (eg.:FHIR implementation guides) files.
The generated Ballerina sources will be written into the provided
output location. Make sure to add the directory path which contains
FHIR specification, as the last argument.
You can download FHIR specification files from the respective
Implementation Guide's official website. (Published list of
Implementation Guides can be found in http://fhir.org/guides/registry/)
The ballerina-health tool is compatible with Ballerina
version 2201.8.1 (Swan Lake Update 8) onwards.
OPTIONS
-v, --version
Print version information.
-h, --help
Print the usage details of a command.
COMMANDS
fhir
Refer to the FHIR specification when generating the Ballerina artifacts.
. . .We can execute the health tool to generate the FHIR API templates as below.
$ bal health fhir -m package -o ig-carinbb/gen --org-name healthcare_samples --package-name carinbb_package ig-carinbb/definitions/
[INFO] Generating templates for all FHIR profiles...
[INFO] Ballerina FHIR API templates generation completed successfully. Generated templates can be found at: /tmp/healthcare-samples/working-with-health-tool/template-generation/ig-uscore/genUpdating a tool
Say a new version of health is published to Ballerina Central. We can run bal tool update to bump the version in our local environment.
Here, I am updating the health tool version from 2.1.0 to the latest compatible version.
$ bal tool update health
ballerinax/health:2.1.1 [central.ballerina.io ->[central cache]/bala/ballerinax/health/2.1.1] 100% [==========] 93637/93637 KB
ballerinax/health:2.1.1 pulled from central successfully
tool 'health:2.1.1' pulled successfully.
tool 'health:2.1.1' successfully set as the active version.In this case, the latest compatible version is 2.1.1.
Listing installed tools
When there are many tools with different versions installed in the local environment, it’s helpful to view a summary of all installed tools in one place. The bal tool list subcommand helps with this.
$ bal tool list
| TOOL ID | VERSION |
|----------|----------|
| health | * 2.1.1 |
| health | 2.0.0 |
| edi | * 0.8.6 |
| edi | 0.8.5 |
| copybook | * 0.1.1 |
5 tools found.Note that the above list will vary according to the tools that we have installed in our programming environment. The version with * before the version number is the active version of a tool.
Switching between tool versions
The bal tool use subcommand allows us to seamlessly switch between different versions of a tool.
In the below example, I switch from 2.1.1 to 2.1.0 of health.
$ bal tool use health:2.1.0
tool 'health:2.1.0' successfully set as the active version.If the specified version is not compatible with the current Ballerina distribution, switching is not allowed.
$ bal tool use health:2.2.3
ballerina: tool health:2.2.3' is not compatible with the current Ballerina distribution '2201.8.5'. Use 'bal tool search' to select a version compatible with the current Ballerina distribution.Removing a tool
We can use the bal tool remove command to remove a specific version or all locally available versions of a tool.
If we specify a version along with the tool ID, it will remove only that specific version.
$ bal tool remove health:2.1.1
tool 'health:2.1.1' successfully removed.However, the current active version cannot be removed. If 2.1.0 is the currently active version, trying to remove it results in the below error.
$ bal tool remove health:2.1.0
ballerina: cannot remove active tool health:2.1.0.Furthermore, it is not allowed to remove incompatible versions.
If we do not specify a version, the entire tool, including the currently active version, will be removed from the local environment.
$ bal tool remove health
tool 'health' successfully removed.In conclusion, the tool command in Ballerina Swan Lake effectively extends the core CLI functionality by enabling the management of additional tools that cater to specific integration needs. This empowers users to leverage a wider range of functionalities beyond the core Ballerina distribution.
We encourage you to explore the available tools and experiment with their capabilities to enhance your Ballerina development experience. If you have doubts or improvement suggestions regarding the tool command, feel free to raise them on the Ballerina Discord server or in Stackoverflow with the ballerina tag. To learn more about the health tool, you can refer to the health tool documentation.
Happy coding in Ballerina Swan Lake!
