Cheat Sheet for Ballerina Commands associated with Module Management

When it comes to learning how to code in ballerina, you might be worried about mastering the ballerina commands. Ballerina has many CLI commands that are used to build, execute and manage ballerina programs. Useful commands that are associated with module management which you should be knowing are briefed below.

Creating a ballerina project

The ‘init’ command can be used to create an initial project structure to get you started with a ballerina project.

ballerina init 
[-i| — interactive]

The artifacts created includes sample ballerina source files with modules and a Ballerina.toml. The Ballerina.toml can be used to manage your organization name and version for the project which are needed when pushing the module to Ballerina Central or when installing the module locally.

Running the init command in the interactive mode (using -i or — interactive) will allow you to create one or more modules with a service or a main function. The created artifacts will include a skeleton of a service or a main function along with a test skeleton that can be used to get started. To get started with the project first create a new folder. Then go inside the project folder and run the init command to generate the aforementioned artifacts into the project.

The ‘init’ command takes in the following options:

• i or — interactive : This will create a ballerina project in the interactive mode in which you will be guided through a set of questions on what source files to be generated (if it should be a main program or a service), modules to be created, configuration files to be generated, project version to be used and organization name to be used.

Initialize a project 
$ ballerina init
Initialize a project in the interactive mode
$ ballerina init -i or ballerina init --interactive

Compiling ballerina sources, executing tests and generating compiled binary files (executable)

The ‘build’ command can be used to compile the ballerina sources, to execute the tests and to generate executable.

ballerina build 
[ballerina-file-name | module-name]
[-o <output>] 
[ — offline] 
[ — skiptests]

By default for a module, the output filename is the module name suffixed with ‘.balx’. For a ballerina source file it will replace the ‘.bal’ suffix with ‘.balx’. But if the output file is specified with the -o flag, then the output will be written to the given output file name.

The ‘build’ command takes in the following options:

• -o <output-file-name> : The output will be written to the given file. The provided output filename may or may not contain the ‘.balx’ suffix.
• — offline : The sources or module are built offline without downloading dependencies from Ballerina Central
• — skiptests : The compilation and execution of the tests are skipped

Build the ballerina source file 'hello_service.bal' 
$ ballerina build hello_service.bal
This will generate the output binary file 'hello_service.balx' in the current directory of the user

Build the 'hello_service' module which resides within a project
$ ballerina build hello_service
This will generate the output binary file 'hello_service.balx' within the target folder of the project

Build the 'hello_service' module with the output name as 'service'
$ ballerina build math -o service
This will generate the output binary file 'service.balx' within the target folder of the project

Build 'hello_service' module by skipping the test compilation and execution
$ ballerina build 'hello_service' --skiptests
This will generate the output binary file 'hello_service.balx' without test execution within the target folder of the project

Uploading modules to Ballerina Central

Modules inside ballerina projects which contain reusable code can be shared with other users by uploading the module to Ballerina Central. The ‘push’ command can be used to push/upload the given module/modules to Ballerina Central. By default, the sources will be built before pushing the module.

ballerina push  
[module-name] 
[ — no-build] 
[ — repository home]

Before pushing a module to Ballerina Central, the access token of Ballerina Central should be specified in the ‘Settings.toml’ file which resides in your home repository (<USER_HOME>/.ballerina/). To get the access token you should first register on Ballerina Central. Then visit the user dashboard and paste the access token provided there in ‘Settings.toml’ as below:

[central]
accesstoken="aaa-bbb-ccc"

When you push a module to Ballerina Central the organizations for the user will be validated against the organization name defined in your project’s ‘Ballerina.toml’ file. If you have more than one organization in Ballerina Central ensure to pick the organization name that you intend to push the module into and set that as organization name in the project ‘Ballerina.toml’ file.

[project]
org-name = "natasha" // My organization in Ballerina Central
version = "0.0.1"

The ‘push’ command takes in the following options:

• — no-build : The sources will not be built before pushing to Ballerina Central
• — repository home : The modules will be pushed to the home repository. This is an alias to the ‘install’ command

Push the 'hello_service' module which resides in a project to Ballerina Central after building it
$ ballerina push hello_service

Push the 'hello_service' module to Ballerina Central without building it
$ ballerina push hello_service --no-build

Push the 'hello_service' module to the home repository after building it i.e. install the module
$ ballerina push hello_service --repository home
Push all modules in the project
$ ballerina push

Searching for modules in Ballerina Central

The ‘search’ command can be used to search for modules in Ballerina Central which has the given text appearing in the organization name, module name or module descriptions. The text searched is treated as case-insensitive when searching.

ballerina search <text>

The search command takes no options.

Search for the twitter module in Ballerina Central
$ ballerina search twitter

Search for modules from WSO2 in Ballerina Central
$ ballerina search wso2

Downloading modules from Ballerina Central

The ‘pull’ command will download the module specified from Ballerina Central and installs it to the home repository (<USER_HOME>/.ballerina/caches). If the version of the module is not specified, then it will download the latest version of the module in Ballerina Central. Else if the version is specified it will download the exact version of the module.

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

The pull command takes no options.

Download the latest version of the twitter module by WSO2 from Ballerina Central
$ ballerina pull wso2/twitter

Download the 0.9.7 version of the gmail module by WSO2 from Ballerina Central
$ ballerina pull wso2/gmail:0.9.7

Installing modules to home repository

The ‘install’ command will install the given module from the project repository to the home repository. The project repository resides within the project home (<PROJECT_DIR/.ballerina>). The home repository resides within the home folder (<USER_HOME>/.ballerina/repo). By default, the sources will be built before installing the module/modules to the home repository.

ballerina install <module-name> 
[ — no-build]
// Alias for the install command
ballerina push <module-name> — repository home 

The ‘install’ command takes in the following options:

• — no-build : The sources will not be built before installing to the home repository

Install the 'hello_service' module which resides in a project to the home repository after building it
$ ballerina install hello_service

Install the 'hello_service' module to the home repository without building it
$ ballerina install hello_service --no-build
Install all modules in the project
$ ballerina install

Uninstalling modules from the home repository

Modules that are installed to the home repository can be uninstalled or removed using the ‘uninstall’ command. This will remove the modules which are installed locally and pulled from Ballerina Central. The home repository resides within the home folder

ballerina uninstall <org-name>/<module-name>:<version>

The uninstall command takes no options.

Uninstall the 'hello_service' module installed locally
$ ballerina uninstall org_name/hello_service:0.0.1

Uninstall 'hello_service' module pulled from Ballerina Central 
$ ballerina uninstall org_name/hello_service:0.0.1

Listing dependencies in ballerina projects and modules

The ‘list’ command will print a complete tree of dependent modules for a given ballerina project or module.

ballerina list 
[module-name]

The list command takes no options.

List dependencies of the 'hello_service' module which resides in a project
$ ballerina list hello_service
List dependencies of all modules in a project
$ ballerina list

Generating API documentation for ballerina sources

The ‘doc’ command is used to generate API documentation for a given ballerina program or module. If a source file name or module name is not given, then it will generate API documentation for all the modules in the current project folder. By default, the generated API documentation will be placed inside the ‘api-docs’ folder in the current project directory.

ballerina doc 
[ballerina-file-name | module-name]
[-t| — template]
[ — sourceroot <path>] 
[-o <path>| — output <path>] 
[-n| — native]
[-e <modules to be excluded>| — exclude <modules to be excluded>] 
[-v| — verbose] 

The ‘doc ’ command takes the following options:

• -t <path> or — template <path>: The custom template file given will be used to format the genearted API documentation.
• — sourceroot <path> : The project directory path which contains the sources files and modules.
• -o <path> or — output <path>: The outputs of the generated API documents will be placed inside this directory.
• -n or — native : The sources given will be read as native ballerina code
• -e <modules to be excluded> or — exclude <modules to be excluded> : The modules provided will be excluded from generated documentation. The modules should be provided in a coma separated list.
• -v or — verbose : The debug level logs will be printed while generating the documentation.

Generate API documentation for the current project
$ ballerina doc
Generate API documentation for the 'hello_service' module which resides in a project
$ ballerina doc hello_service
Generate API documentation for 'hello_service.bal' 
$ ballerina doc hello_service.bal 

Generate API documentation for 'hello_service.bal' and write 
the generated docs to the 'docs' folder
$ ballerina doc -o docs hello_service.bal 

Executing tests and getting a summary of the test results

The ‘test’ command is used to compile and run ballerina test sources. Tests in a single test file, a test module and an entire project can be executed. This will also print a summary of the test results i.e. how many tests passed, failed and skipped and the status of each test.

ballerina test 
[ballerina-file-name | module-name]
[-lg| — list-groups] 
[ — groups <groups to be executed>]
[ — disable-groups <groups to be excluded>] 
[ — sourceroot <path>] 
[-c <config_file>] 
[ — exclude-modules <modules to be excluded>] 
[ — config <config_file>] 

The ‘test ’ command takes the following options:

• -lg or — list-groups : The test groups available in the test sources will be listed. The test functions in test sources can be grouped together. These groupings are used to control the execution of test functions by specifying one or more groups which needs to be executed when running tests. A test function can be grouped within the @test:config annotation using the ‘groups’ parameter.
• — groups <groups to be executed> : This will specify the groups to be executed. The test groups should be provided in a coma separated list.
• — disable-groups <groups to be disabled> : This will specify the test groups to be excluded. The test groups should be provided in a coma separated list.
• — sourceroot <path> : This will define the path of the remote ballerina project with source files. All test executions will be relative to the sourceroot path.
• — exclude-modules <modules to be excluded> : This will specify the modules to be excluded when executing test sources. The modules should be provided in a coma separated list.
• -c <config_file> or — config <config_file> : This will provide the path to the ballerina configuration file. If the configuration file is not provided, it will use the default configuration file ‘ballerina.conf’ which is placed in the project directory. The configuration file format is a subset of the TOML file format.

Run all tests in the current project
$ ballerina test
Run all tests in 'hello_service' module which resides in a project
$ ballerina test hello_service
Run all tests 'hello_service_test.bal' file
$ ballerina test hello_service_test.bal 
List all test groups specified in test source files in the 'hello_service' module which resides in a project
$ ballerina test -lg hello_service 

Run tests belonging to group_a in test source files in 'hello_service' module which resides in a project
$ ballerina test --groups group_x  tests

So this is just an overview of commands used frequently by users to build, execute and test ballerina programs. You can try these commands out by downloading ballerina.

Now as for how to end with a bang? Well, that’s another blog post for another time :) :) Till we meet again :)