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 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 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 semver Show SemVer compatibility and local package changes against published packages in Ballerina Central graph Print the dependency graph in the console 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 the Ballerina client sources for a given GraphQL config file and generate the GraphQL schema for a given Ballerina GraphQL service. openapi Generate the Ballerina sources for a given OpenAPI definition and vice versa asyncapi Generate the 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 pullcommand.
$ 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
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 |
|run||Build and run a standalone |
|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 (|
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.|
|semver||Validate SemVer compatibility of the local package changes against any previously published version(s) in Ballerina Central.|
|graph||Print the dependency graph in the console.|
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/schema generation tool. For more information, see Ballerina GraphQL 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., |
|dist||Manage Ballerina distributions. For more information, see Update Tool.|
|update||Update the Ballerina Tool. For more information, see Update Tool.|