Ballerina is a general-purpose programming language particularly intended for the implementation of distributed network applications. Ballerina has built-in modules to build a distributed web application with only a few lines of code. Ballerina provides a CLI tool for the maintenance of your Ballerina project. This article is a brief introduction to the Ballerina CLI tool and how it was used.

You can download Ballerina distribution from the official Ballerina website. You can begin writing a Ballerina program once you download and install it. You can check the version of the ballerina installation by executing the following command.

ballerina version

This command prints the installed version of the Ballerina. You can also check the Ballerina installed folder by running the following command.

ballerina home

You may also like: Data Integration With Ballerina

Creating a New Ballerina Project Using CLI

You can use the following Ballerina CLI command to create a new Ballerina project. This command creates a new folder containing the Ballerina.toml file and the src directory. All of your Ballerina descriptions and dependencies are included in this Ballerina.toml file.

ballerina new <project-name>

Now, you can begin working on your project in the freshly created Ballerina project. The following command generates a module to begin writing your own Ballerina code. You should change the current directory to the Ballerina project folder to perform this command.

ballerina add <module-name>

This command generates the Ballerina folder structure inside the Ballerina module along with the Hello World Code sample in Ballerina. <project_home>/src/<module_name>/main.bal becomes the main entry point for your application.

Tests for the module should be placed inside <project_home>/src/<module_name>/tests/ the directory. The “Hello, World” program in the main.bal is as follows: 

import ballerina/io;

public function main() {
    io:println("Hello World!");

You can build the project together with the test by running the following command. You can prevent running test cases by adding the —skip-test option at the end of the build command.

ballerina build <module-name>

The build command builds the source code and converts it into a Java program in the <project_home>/target/bin/ folder. If you inspect this folder, you can see a jar file with the name of the module. You can run this jar file on JVM the same way you run the standard Java program.

If you need to run a module without building, you can try the following command. Here, you can run either the module or the Ballerina file.

ballerina run {<bal-file> | <module-name>}

Ballerina keep cache inside the Ballerina project. It keeps following caches in-order to speed up the building process.

  • BALO files fetched from Central.
  • BIR files generated during the compilation.
  • JAR file generated during the compilation

By executing the following command, Ballerina clears the cache inside the ballerina project.

ballerina clean

You can run tests only with the Ballerina program by running the following command. You can test the whole module by adding the -a  option, or you can only test the particular module by specifying the name of the module.

ballerina test <module-name>

Collaborate With Others Through the Ballerina Central

Ballerina Central landing page

Ballerina Central landing page

Ballerina Central is the main place where developers can share their software with other developers. Ballerina Central functions the same way that git works. By pushing the modules, you can upload your modules to Ballerina Central. In the same way, you can use the module constructed by others by pulling modules. You can browse the available modules on the Ballerina Central website.

The following command can be used to search for a Ballerina module by using CLI instead of searching from Ballerina central website.

ballerina search <key-word>

Once you list the necessary module, you can pull the module into your project by running the following command.

ballerina pull <org-name>/<module-name>[:<version>]

The organization name is a logical name used for grouping modules under a common namespace. For instance, you can take the Twitter module that can be used to access the Twitter API by running the following command.

ballerina pull wso2/twitter:0.9.26

You can use a twitter client to write a simple Ballerina code as follows to send a tweet.

import wso2/twitter;

twitter:TwitterConfiguration twitterConfig = {
    clientId: testClientId,
    clientSecret: testClientSecret,
    accessToken: testAccessToken,
    accessTokenSecret: testAccessTokenSecret,
    clientConfig: { secureSocket: {
                        trustStore: {
                            path: "${ballerina.home}/bre/security/ballerinaTruststore.p12",
                            password: "ballerina"

public function main() {
twitter:Client twitterClient = new(twitterConfig);

string status = "Twitter endpoint test";
    var result = twitterClient->tweet(status);
    if (result is twitter:Status) {
        // If successful, print the tweet ID and text.
        io:println("Tweet ID: ",;
        io:println("Tweet: ", result.text);
    } else {
        // If unsuccessful, print the error returned.
        io:println("Error: ", result);

If you need to publish a module in Ballerina Central, you need to create an account in Ballerina Central. Then you can get a secret token and put it into the <USER_HOME>/.ballerina/Settings.toml file. Always remember to set organization name correctly in Ballerina.toml file in your <project_home>.

Secure Passwords With Ballerina Encrypt Command

In some scenarios, you may need to use a password inside your code. Assume, for example, that you need to create a Twitter bot. Here, we just keep security tokens as plain text inside the code itself. But keeping a password inside the code is a bad practice, as it reveals a password to someone else who can see your source code. Ballerina provides support to hide your password from the source code and only reveal it during runtime.

To encrypt a value, you need to run the following command first. This command first asks for a value to be encrypted. Then, you can ask for a password and verify that password.

ballerina encrypt

This command generates an encrypted value using the CBC mode with the AES method. You can now read the secret value from the source code as follows.

import ballerina/io;
import ballerina/config;

public function main() {

Here, we use the config module to read the config file. secret.password is an alias for the real value. When this application is running, you should provide an encrypted value as a command line argument.

ballerina run sample --secret.password="@encrypted:{MOT+c6216tQLzSxiDfXclFg75q1ktY6+3VlCa6uhn40=}"

When Ballerina starts running, ask for a password. Use the password you used to encrypt the value. This program will print the word you set with the ballerina encrypt command.


In this blog post, we’ve gone through the CLI features provided by the Ballerina. You can easily create, build and test Ballerina projects using the Ballerina CLI. Ballerina Central can be used to re-use modules developed by other Ballerina developers. You can also share your module with others. 

Related Articles

Source link

Write A Comment