Learn all the command line interface (CLI) commands you need to get started, build, test and run programs, work with Ballerina Central, and manage packages.
ballerina, cli, command line interface, programming language
The Ballerina Tool is your one-stop-shop for all the things you do in Ballerina.
Using 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 The below is a list of the available subcommands: Core Commands: build Compile a Ballerina program into an executable run Build and run a Ballerina program test Run package tests doc Generate API documentation clean Clean the artifacts generated during the build format Format Ballerina sources Package Commands: new Create a new Ballerina package init Initialise a new Ballerina package in the current directory add Add a new Ballerina module in the package pull Pull a package from Ballerina Central push Upload a package to Ballerina Central search Search Ballerina Central for packages Other Commands: grpc Generate the Ballerina sources for a given Protocol Buffer definition openapi Generate the Ballerina sources for a given OpenAPI definition and vice versa [EXPERIMENTAL] version Print the Ballerina version bindgen Generate the Ballerina bindings for Java APIs shell Run Ballerina interactive REPL [EXPERIMENTAL]
You can use it in the below format.
bal <THE-COMMAND> <ITS-ARGUEMENTS>
Tip: You can view details of the commands below by executing the
bal help <COMMAND>. For example, the below 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> 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 `.bal` file, or an entire package into an executable JAR file. For more information, see Writing Your First Ballerina Program.|
|run||Build and run a standalone `.bal` file, an entire package, or a previously-built program. For more information, see Writing Your First Ballerina Program.|
|test||Run tests of a Ballerina package. For more information, see Testing Ballerina Code.|
|doc||Generate API documents for all public symbols of a Ballerina package. For more information, see Documenting Ballerina Code.|
|clean||Clean all artifacts generated by the build command for a package.|
|format||Format Ballerina source files as per the Coding Conventions.|
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 Ballerina Packages.|
|init||Create a new Ballerina package in the current directory.|
|add||Create a new Ballerina module in a package.|
|pull||Pull a package from Ballerina Central.|
|push||Upload a package to Ballerina Central. For more information, see Publishing a library package to Ballerina Central.|
|search||Search Ballerina Central for packages.|
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.
|encrypt||Use this tool to encrypt sensitive data and pass them to a Ballerina program via the configuration system.|
|grpc||This is the gRPC stub/skeleton generation tool. For more information, see Generating Ballerina Code for Protocol Buffer Definitions.|
|openapi||This is the OpenAPI (Swagger) stub/skeleton generation tool. For more information, see Using the OpenAPI Tools.|
|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.|
|bindgen||Use this tool for auto-generating Ballerina bridge code for Java APIs. For more information, see Calling Java Code from Ballerina.|
|help||Prints the usage details of any Ballerina command (e.g., `bal help pull`).|
|dist||Manage Ballerina distributions. For more information, see Keeping Ballerina Up to Date.|
|update||Update the Ballerina Tool. For more information, see Keeping Ballerina Up to Date.|