CLI commands

The Ballerina Tool is your one-stop-shop for all the things you do in Ballerina.

Use the Ballerina tool

The Ballerina Tool is a command-line tool for managing Ballerina source code. It helps you to manage Ballerina packages and modules, test, build, and run programs, etc.

It also enables you to easily install, update, and switch among Ballerina distributions.

In the CLI, execute the bal help command to view all the actions you can perform with the Ballerina Tool as shown below.

→ bal help
NAME
       The Ballerina Tool

SYNOPSIS
       bal [-v | --version]
       bal help
       bal <command> [-h | --help]


DESCRIPTION
       Ballerina is a statically-typed, concurrent programming language focusing on network
       interaction and structured data. It is intended to be the core of a language-centric
       middleware platform. It not only has all the general-purpose functionality expected
       from a modern programming language but also has several unusual aspects that make it
       particularly suitable for its intended purpose.

       Find more information at: https://ballerina.io


OPTIONS
       -v, --version
           Print the Ballerina version information.

       -h, --help
           Print the usage details of a command.


BALLERINA COMMANDS
        Below is a list of the available subcommands:

   Core Commands:
        build           Compile the current package
        run             Compile and run the current package
        test            Run package tests
        doc             Generate current package's documentation
        pack            Create distribution format of the current package

   Package Commands:
        new             Create a new Ballerina package
        init            Create a new Ballerina package in an existing directory
        add             Add a new Ballerina module to the current package
        pull            Pull a package from Ballerina Central
        push            Publish a package to Ballerina Central
        search          Search Ballerina Central for packages

   Other Commands:
        clean           Clean the artifacts generated during the build
        format          Format Ballerina source files
        grpc            Generate the Ballerina sources for a given Protocol Buffer definition
        graphql         Generate Ballerina client sources for a given GraphQL schema(SDL) 
                        and GraphQL queries
        openapi         Generate the Ballerina sources for a given OpenAPI definition and
                        vice versa
        asyncapi        Generate Ballerina sources for a given AsyncAPI definition
        bindgen         Generate the Ballerina bindings for Java APIs
        shell           Run Ballerina interactive REPL
        version         Print the Ballerina version

   Update Commands:
        dist            Manage Ballerina distributions
        update          Update the Ballerina tool

You can use it in the following format.

bal <COMMAND> <ARGUMENTS>

Tip: You can view details of the commands by executing the bal help <COMMAND>. For example, the following is the output of the bal help pull command.

→ bal help pull
NAME
       ballerina-pull - Fetch packages from Ballerina Central

SYNOPSIS
       bal pull <org-name>/<package-name>[:<version>]


DESCRIPTION
       Download the specified package from Ballerina Central along with its
       dependencies and cache it in the '.ballerina' directory in the user home.

       Ballerina Central is a package repository hosted at
       https://central.ballerina.io/. A package repository organizes packages
       into a three-level hierarchy: organization, package name, and version.
       Organizations are unique within a repository and can be mapped to an
       individual user or organization registered with the repository.


EXAMPLES
       Pull the latest version of the 'gmail' connector in the 'wso2' organization
       from Ballerina Central.
           $ bal pull wso2/gmail

       Pull the '1.1.0' version of the 'gmail' connector in the 'wso2' organization
       from Ballerina Central.
           $ bal pull wso2/gmail:1.1.0

Core commands

These everyday commands are your best friends! They address the very basics of programming in Ballerina such as compiling, running, testing programs, and generating their documentation.

build Compile a standalone .bal file, or an entire package into an executable JAR file. For more information, see Getting started with Ballerina.
run Build and run a standalone .bal file, an entire package, or a previously-built program. For more information, see Getting started with Ballerina.
test Run tests of a Ballerina package. For more information, see Testing a Simple Function.
doc Generate API documents for all public symbols of a Ballerina package. For more information, see Generating code documentation.
pack Create the distribution format (.bala) of the current package

Package commands

Ballerina packages are the way to organize real-world Ballerina development tasks. The last 3 commands given below allow you to work with the Ballerina Central and also to share Ballerina packages with others in a safe, secure, and dependable way.

new Create a Ballerina package. For more information, see Create a new package.
init Create a new Ballerina package in the current directory.
add Add a new module to the current package.
pull Pull a package from Ballerina Central.
push Publish a package to Ballerina Central. For more information, see Publish packages to Ballerina Central.
search Search Ballerina Central for packages.

Other commands

These powerful supporting tools extend Ballerina to various ecosystem technologies that are inherently cloud-native. This functionality will grow over time and will even be developer extensible in the future.

clean Clean all artifacts generated by the build command for a package.
format Format Ballerina source files as per the Coding Conventions.
grpc This is the gRPC stub/skeleton generation tool. For more information, see gRPC/Protocol Buffers.
graphql This is the GraphQL client generation tool. For more information, see Ballerina GraphQL client tool support.
openapi This is the OpenAPI (Swagger) stub/skeleton generation tool. For more information, see Ballerina OpenAPI support.
asyncapi Tool to generate Ballerina sources for a given AsyncAPI definition. For more information, see Ballerina AsyncAPI support.
bindgen Use this tool for auto-generating Ballerina bridge code for Java APIs. For more information, see Call Java code from Ballerina.
shell Use this to run a REPL instance of Ballerina and execute small snippets of code.
version Tells you the version of the distribution you are currently using, the language specification version on which it is based, and the update tool version, which is currently in use.
help Prints the usage details of any Ballerina command (e.g., bal help pull).

Update commands

dist Manage Ballerina distributions. For more information, see Update Tool.
update Update the Ballerina Tool. For more information, see Update Tool.