CLI
The Kubling CLI (Command Line Interface) is a single, statically compiled, dependency-free 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
Although Kubling is not a heavy application (its OCI Image is ~125MB), and its Community Edition (CE) version includes nearly all the features needed during development—making it a perfect fit for local development environments—certain tasks like testing can be challenging and time-consuming if every small change to a Script Module requires restarting a test container.
On the other hand, CLI tools and packages are typically small, often just a few KB in size, especially in the Linux ecosystem.
However, the first thing you’ll notice is that kdv is relatively large compared to other CLI tools.
This is because kdv contains roughly half of the packages and dependencies used by the server itself,
including the Query Engine, Data Sources layer, including translators and adapters, and the JavaScript interpreter.
The reason for embedding all these packages into the CLI is that we have created a special test command, which helps you write and execute integration tests declaratively. This is part of our effort to integrate with popular IDEs like Visual Studio Code.
We are planning to release a smaller version without testing related commands. See our roadmap for more information.
Distribution
For local development environments we recommend using the binary file whose distribution channel is still under development.
In pipelines, workflows or in case you prefer using containers, you can find them here.
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 /dbvirt-samples/azure/modules/delegate -o /dbvirt-samples/azure/modules/azure-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 /dbvirt-samples/appmodel/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
The general usage, assuming you use Docker, is as follows:
docker run --rm -v [/your/project/path]:[/path/in/container] kubling/dbvirt-cli:latest [command] [subcommand] [params] [options][/your/project/path]: Any system’s directory that contains one or several Kubling project (like modules), needed by the command.[path/in/container]: The mount point inside the container.command: Thekdvcommand to be executed, along with its subcommand, parameters and options.
Sample usage:
docker run --rm -v /root/dbvirt-samples/:/dbvirt-samples/ kubling/dbvirt-cli:latest bundle genmod /dbvirt-samples/azure/modules/delegate -o /dbvirt-samples/azure/modules/delegate/azure-module-bundle.zip