CLI
The Kubling CLI is a single, statically compiled executable named kdv.
The main goal of the CLI is to facilitate common tasks required when configuring instances. It is designed to be easily embedded into pipelines, as well as into developers’ environments.
A note on its size
kdv is larger than a typical filesystem-oriented CLI because bundle
validation and the integration test command reuse engine, data-source and
JavaScript runtime components. That allows pipelines to validate artifacts and
execute declarative integration plans without starting a Kubling instance for
every intermediate change.
Distribution
Use the native binary in a developer workstation or the
kubling/kubling-cli
image in pipelines and containerized workflows.
Commands
• bundle
It aggregates various utilities for working with bundle files, like Modules.
Subcommands
→ genmod
Generates a JavaScript Module file.
Name | Type | Description | Default Value |
|---|---|---|---|
| Directory Path | Parameter(0) | Path to the root of the directory containing Module’s code. | |
-o, --output | Option | Full file name of the generated bundle zip file. | |
-p, --parse | Option | When enabled, all JavaScript files are parsed before bundle is generated. | false |
Sample usage:
kdv bundle genmod ./javascript/module \
--output ./javascript-module-bundle.zip \
--parse• test
Utilities for performing tests.
Subcommands
→ integration
Runs an Integration test plan.
| Name | Type | Description | Default Value |
|---|---|---|---|
| File Path | Parameter(0) | Test plan manifest file path. |
Sample usage:
kdv test integration ./integration-test-plan.yamlMore about the test framework in the next section.
• cert
Utilities for working with Kubling Server and Client certificates.
Subcommands
→ create
Creates a pair of certificate stores to use in Server and Client.
KeyStore type used during generation is PKCS12, whereas for the digital signature, the SHA512withRSA encryption is used.
Name | Type | Description | Default Value |
|---|---|---|---|
-v, --validity | Option | SERVER and CLIENT certificate store validity expressed in days. | 180 |
-s, --server | Option | Full path to the generated SERVER keystore (contains private key and chain). | ./server.ks |
-st, --serverTrust | Option | Full path to the generated SERVER truststore (used for verifying client certs in mTLS). | ./server-truststore.ks |
-c, --client | Option | Full path to the generated CLIENT truststore (trusts server CA). | ./client-truststore.ks |
-cc, --clientCred | Option | Full path to the generated CLIENT keystore (.p12) containing client private key and certificate chain. | ./client.p12 |
-p, --clientPass | Option | CLIENT keystore/truststore password. | (Random String) |
-x, --serverPass | Option | SERVER keystore/truststore password. | (Random String) |
-H, --san | Option | Subject Alternative Names (SANs) for the certificate. Supports multiple values separated by comma or space (e.g. localhost,127.0.0.1). Repeatable flag. | Empty |
--san-file | Option | Optional file path pointing to a list of SAN entries (one per line). Lines starting with # are ignored. | None |
-o, --overwrite | Flag | Overwrite store files if they already exist. | false |
Sample usage:
kdv cert create -s /certs/server.ks -c /certs/client.ks -x myserverpass -p myclientpass -oGenerated Certificate Files Overview
The certificate generation process produces multiple files, each with a specific purpose depending on whether the file is used by the server (Kubling instance) or the client in mutual TLS (mTLS) scenarios.
| File | Contains | Used By | Purpose / EKU Role |
|---|---|---|---|
server.ks | Server certificate + private key + full chain (root + intermediate) | Kubling Server | Transport-level certificate transports.[protocol].sslConfig.storeFilePath |
server-truststore.ks | Root CA that issued the client certificate | Kubling Server | Used by Kubling Server to trust client certificate/s when in mTLS mode. |
client.p12 | Client certificate + private key + full chain | Client (for mTLS) | Used by clients to establish a mTLS connection. Use p12 as extension for compatibility |
client-truststore.ks | Root CA that issued the server certificate | Client | Used by clients to trust server certificate, i.e. via props file |
In mTLS (mutual TLS), both the server and the client validate each other using their respective truststores.
Each side must trust the CA that signed the other side’s certificate.
→ create-http
Creates a pair of certificate stores to use in Kubling HTTP Server.
KeyStore type used during generation is PKCS12, whereas for the digital signature, the SHA512withRSA encryption is used.
Name | Type | Description | Default Value |
|---|---|---|---|
-v, --validity | Option | Certificate store validity expressed in days. | 180 |
-s, --server | Option | Full path to the generated SERVER keystore (contains server private key and certificate chain). | ./server-http.ks |
-c, --client | Option | Full path to the generated CLIENT truststore (used to validate server certificate). | ./client-http-trust.ks |
-p, --pass | Option | Password for both server and client certificate stores. | (Random String) |
-H, --san | Option | Subject Alternative Names (DNS names or IP addresses). Can be provided as a comma/space-separated list or repeated. | (None) |
--san-file | Option | Path to a file containing SAN entries (one per line). Lines beginning with # are ignored. | (None) |
-o, --overwrite | Flag | Overwrite existing certificate store files if they already exist. | false |
Sample usage:
kdv cert create-http -s /certs/server-http.ks -c /certs/client-http-trust.ks -p mypass -oUsing the containerized version
Mount the project into the container and use paths visible inside that mount:
docker run --rm \
--volume "$PWD:/workspace" \
kubling/kubling-cli:latest \
[command] [subcommand] [params] [options]The image entrypoint is kdv, so the arguments after the image name are the
same commands accepted by the native executable.
For example, from the root of a cloned
kubling-samples
repository:
docker run --rm \
--volume "$PWD:/workspace" \
kubling/kubling-cli:latest \
bundle genmod /workspace/javascript/module \
--output /workspace/javascript-module-bundle.zip \
--parse