Skip to main content

Build descriptors locally

If you work on data products or components directly in your IDE, the build-descriptor command lets you generate a fully resolved descriptor.yaml from your local files — the same output the Witboost Builder service produces — without ever opening the browser.

How to use it​

Below are some examples of how to use build-descriptor. Replace the <WITBOOST_BASE_URL> and <TOKEN> values with your information following the commands reference page. The other parameter values should be replaced based on your specific input data and target environment.

Build a single entity descriptor​

To generate a descriptor for a single entity (e.g., a component or a system), use the --entity-path option pointing to the directory that contains your entity files:

witboost builder build-descriptor \
    --witboost-base-url <WITBOOST_BASE_URL> \
    --token <TOKEN> \
    --entity-path ./entity \
    --environment production

The resolved descriptor.yaml for the specified entity will be written to the current directory.

Build a full project descriptor​

To generate a descriptor covering a system and all its components, add the --full flag together with --system-path and --components-path:

witboost builder build-descriptor \
    --witboost-base-url <WITBOOST_BASE_URL> \
    --token <TOKEN> \
    --full \
    --system-path ./system \
    --components-path ./components \
    --environment production

The resulting descriptor.yaml encompasses the entire project — system metadata and all component definitions in a single file.

Using environment variables​

Authentication options (--token, --witboost-base-url) can be provided via environment variables so you don't have to pass them on every invocation:

export ACCOUNT_ACCESS_TOKEN=xxx
export WITBOOST_BASE_URL=https://witboost.example.com

witboost builder build-descriptor \
    --entity-path ./entity \
    --environment production

Authentication options are resolved with the following precedence: CLI arguments > environment variables > configuration file (.witboost-cli/config.yaml).

Combining with Governance evaluation​

A common local workflow is to generate the descriptor and immediately validate it against registered governance policies and metrics:

# Step 1 — Generate the descriptor
witboost builder build-descriptor \
    --witboost-base-url <WITBOOST_BASE_URL> \
    --token <TOKEN> \
    --entity-path ./entity \
    --environment production

# Step 2 — Evaluate the generated descriptor against Governance Entities
witboost governance evaluate \
    --base-url <WCG_BASE_URL> \
    --witboost-base-url <WITBOOST_BASE_URL> \
    --token <TOKEN> \
    --env production \
    --resource-type dataproduct \
    --resource-id my-dp \
    --descriptor-file ./descriptor.yaml

For more details about the Governance evaluation step, see the Embed governance in CI/CD page.