Skip to main content

CLI client - Getting started guide

In this tutorial, you will learn to use the CLI client zbctl to interact with Camunda Cloud.

Prerequisites​

Set up​

Installation​

Quickly install via the package manager npm. The corresponding package is here.

npm i -g zbctl

You can also download a binary for your operating system from the Zeebe GitHub releases page.

Connection settings​

To use zbctl, it is recommended to define environment variables for the connection settings:

export ZEEBE_ADDRESS='[Zeebe API]'
export ZEEBE_CLIENT_ID='[Client ID]'
export ZEEBE_CLIENT_SECRET='[Client Secret]'
export ZEEBE_AUTHORIZATION_SERVER_URL='[OAuth API]'

When creating client credentials in Camunda Cloud, you have the option to download a file with the lines above filled out for you.

Alternatively, use the described flags (--address, --clientId, and --clientSecret) with the zbctl commands.

Test command​

Use the following command to verify everything is set up correctly:

zbctl status

As a result, you should receive a similar response:

Cluster size: 1
Partitions count: 2
Replication factor: 1
Gateway version: unavailable
Brokers:
  Broker 0 - zeebe-0.zeebe-broker-service.456637ef-8832-428b-a2a4-82b531b25635-zeebe.svc.cluster.local:26501
    Version: unavailable
    Partition 1 : Leader
    Partition 2 : Leader

Advanced process​

Use this process model for the tutorial.

processId

This process includes a service task and an XOR gateway. Select the service task and fill in the properties. Set the Type to test-worker.

process

The worker will return a JSON object as a result, which is used to decide which path to take.

Now, we can use the JSON object to route your process by filling in the condition expression on the two sequence flows after the XOR gateway.

Use the following conditional expression for the Pong sequence flow:

=result="Pong"

Use the following conditional expression for the else sequence flow:

=result!="Pong"

sequenceflows

Deploy a process​

Now, you can deploy the process. Navigate to the folder where you saved your process.

zbctl deploy resource gettingstarted_quickstart_advanced.bpmn

If the deployment is successful, you'll get the following output:

{
  "key": 2251799813685493,
  "processes": [
    {
      "bpmnProcessId": "camunda-cloud-quick-start-advanced",
      "version": 1,
      "processKey": 2251799813685492,
      "resourceName": "gettingstarted_quickstart_advanced.bpmn"
    }
  ]
}
note

You will need the bpmnProcessId to create a new instance.

Register a worker​

The process uses the worker with the type test-worker. Register a new one by using the following command:

zbctl create worker test-worker --handler "echo {\"result\":\"Pong\"}"

Start a new instance​

You can start a new instance with a single command:

zbctl create instance camunda-cloud-quick-start-advanced

As a result, you'll get the following output. This output will contain—among others—the processInstanceKey:

{
  "processKey": 2251799813685492,
  "bpmnProcessId": "camunda-cloud-quick-start-advanced",
  "version": 1,
  "processInstanceKey": 2251799813685560
}

Navigate to Operate to monitor the process instance.

operate-instances

Because the worker returns the following output, the process ends in the upper end event following the Ping sequence flow:

{
  "result": "Pong"
}

To end up in the lower end event you'll have to modify the worker to return a different result. Change the worker to the following:

zbctl create worker test-worker --handler "echo {\"result\":\"...\"}"

Creating a new instance leads to a second instance in Operate, which you'll see ending in the second end event following the else sequence flow:

operate-instance

Next, you can connect both workers in parallel and create more process instances:

while true; do zbctl create instance camunda-cloud-quick-start-advanced; sleep 1; done

In Operate, you'll see instances ending in both end events depending on which worker picked up the job.

operate-instances