Skip to content
go-bpmn

Using CLI

To connect and use the go-bpmn command-line interface, the URL of a process engine HTTP API as well as an API key is required.

The URL’s host and port are specified in the environment variable GO_BPMN_HTTP_BIND_ADDRESS of the process engine daemon. The default value is 127.0.0.1:8080.

An API key must be created, using following command:

Terminal window
go-bpmn-pgd -create-api-key -secret-id test-worker > ~/test-worker-authorization

When done, the CLI must be configured. The URL can be provided as environment or as global CLI option --url. Whereas the authorization string must be configured per an environment variable.

Terminal window
export GO_BPMN_URL="http://127.0.0.1:8080"
export GO_BPMN_AUTHORIZATION="$(cat ~/test-worker-authorization)"

After URL and authorization string are set, the CLI can be used:

go-bpmn [command] [flags]

Debugging

Section titled “Debugging”

The --debug option allows to debug the HTTP communication. To enabled debugging for every command, set environment variable GO_BPMN_DEBUG to true.

Terminal window
go-bpmn --debug process-instance create --bpmn-process-id test --version 1

The debug output, includes HTTP method, URL, request body, status code, response headers and response body:

2025/05/24 13:15:15 POST http://localhost:8080/process-instances
2025/05/24 13:15:15 request body:
{
  "bpmnProcessId": "test",
  "version": "1",
  "workerId": "go-bpmn"
}
2025/05/24 13:15:15 status code: 404
2025/05/24 13:15:15 response headers:
2025/05/24 13:15:15 Content-Length: 123
2025/05/24 13:15:15 Content-Type: application/problem+json
2025/05/24 13:15:15 Date: Sat, 24 May 2025 11:15:15 GMT
2025/05/24 13:15:15 response body:
{
  "status": 404,
  "type": "NOT_FOUND",
  "title": "failed to create process instance",
  "detail": "process test:1 could not be found"
}
Error: failed to create process instance: process test:1 could not be found