Commands Reference

• witboost — CLI entrypoint command
• witboost governance — Witboost Computational Governance (WCG) allows for the creation, evolution, and enforcement of Governance Entities (policies or metrics) within development processes, ensuring governance is automated and not bypassable. This CLI allows interaction with WCG by evaluating a resource against Governance Entities.
• witboost builder — Commands to interact with the Witboost Builder module.
• witboost utils — Utility commands

witboost

Command-line interface to interact with the Witboost platform. This CLI provides commands for the Witboost Builder module, Witboost Computational Governance, and utility operations.

Usage

witboost [options] [command]

Options

Flag	Required	Default	Description
-V, --version		-	output the version number
-l, --log-level <level>		info	Set log level
-v, --verbose		-	Enable verbose output (same as --log-level debug)

Additional help notes

Command-line interface to interact with the Witboost platform.
This CLI provides commands for the Witboost Builder module, Witboost
Computational Governance, and utility operations.

Run "witboost [command] --help" for details about a specific command.

For more details, see the official documentation: https://docs.witboost.com/p3_tech/p15_cli

witboost builder

Commands to interact with the Witboost Builder module.

Usage

witboost builder [options] [command]

witboost builder build-descriptor

Build a complete product descriptor or the descriptor for a specific component.

Usage

witboost builder build-descriptor (--entity-path <ENTITY_PATH> | --full --system-path <SYSTEM_PATH> --components-path <COMPONENTS_PATH>) --environment <ENVIRONMENT> [--include <PATH_OR_GLOB>]

Options

Flag	Required	Default	Description
--witboost-base-url <WITBOOST_BASE_URL>	✅	env/config	It is the URL you use to access Witboost e.g. https://witboost.my-example-company.com . Must be provided via either CLI, environment variable (WITBOOST_BASE_URL), or config file (key: "WITBOOST_BASE_URL")
--token <TOKEN>	✅	env/config	User/Service Account Access Token to authenticate with the Witboost API. Must be provided via either CLI, environment variable (ACCOUNT_ACCESS_TOKEN), or config file (key: "ACCOUNT_ACCESS_TOKEN")
--full		false	If specified, build full descriptors including all details
--entity-path <ENTITY_PATH>		-	Path to the entity (system or component) for which to build the descriptor (if --full is not used)
--system-path <SYSTEM_PATH>		-	Path to the folder containing the system files used to build the descriptor (if --full is used)
--components-path <COMPONENTS_PATH>		-	Path to the folder containing the component directories whose files are used to build the descriptor (if --full is used)
--include <PATH_OR_GLOB>		-	Additional file, folder, or glob pattern to include in the descriptor generation input. Repeat the option to include multiple entries.
--environment <ENVIRONMENT>	✅	-	Target environment for which to build the descriptor

Additional help notes

Build a descriptor in YAML format from local system or component files.

  Required inputs:
  - Witboost base URL
  - target environment
  - either --entity-path, or --full with both --system-path and --components-path

  Optional inputs:
  - --include, to add extra local files, folders, or glob patterns
      
  Notes:
  - Only --witboost-base-url and --token can come from environment variables or config file (.witboost-cli/config.yaml). All other options must be provided via CLI.
  - Authentication options are resolved with the following precedence: CLI arguments > environment variables > configuration file.
  - By default the CLI uses the standard set of files required by Witboost for descriptor generation (catalog-info.yaml, parameters.yaml, etc.).
  - Use --include when descriptor generation also needs extra local files or folders. One possible use case is when parameters.yaml declares refs to local files.
  - Include patterns are resolved relative to --entity-path or, with --full, relative to --system-path and each component directory under --components-path.

  Examples:

  # 1. Build a single entity resource using options via CLI
  witboost builder build-descriptor \
    --witboost-base-url https://witboost.my-example-company.com \
    --token $ACCOUNT_ACCESS_TOKEN \
    --entity-path ./entity \
    --environment production

  # 2. Build a full resource using options via CLI
  witboost builder build-descriptor \
    --witboost-base-url https://witboost.my-example-company.com \
    --token $ACCOUNT_ACCESS_TOKEN \
    --full \
    --system-path ./system \
    --components-path ./components \
    --environment production

  # 3. Use environment variables (token, witboost-base-url)
  export ACCOUNT_ACCESS_TOKEN=xxx
  export WITBOOST_BASE_URL=https://witboost.my-example-company.com
  witboost builder build-descriptor \
    --entity-path ./entity \
    --environment production

  # 4. Add extra local files
  witboost builder build-descriptor \
    --witboost-base-url https://witboost.my-example-company.com \
    --token $ACCOUNT_ACCESS_TOKEN \
    --entity-path ./entity \
    --environment production \
    --include README.md \
    --include docs \
    --include 'resources/**/schema.yaml'

witboost governance

Witboost Computational Governance (WCG) allows for the creation, evolution, and enforcement of Governance Entities (policies or metrics) within development processes, ensuring governance is automated and not bypassable. This CLI allows interaction with WCG by evaluating a resource against Governance Entities.

Usage

witboost governance [options] [command]

Additional help notes

Witboost Computational Governance (WCG) allows for the creation, evolution, and
enforcement of Governance Entities (policies or metrics) within development
processes, ensuring governance is automated and not bypassable.
This CLI allows interaction with WCG by evaluating a resource against Governance
Entities.

Prerequisites:
  - A resource type must be defined in Witboost.
  - At least one Governance Entity must be registered in the Witboost Computational Governance.

For more details, see the official documentation: https://docs.witboost.com/docs/p3_tech/p11_managing_policies/p11_1_overview

witboost governance evaluate

Evaluate resource descriptors against registered Governance Entities.

Usage

witboost governance evaluate --base-url <BASE_URL> --witboost-base-url <WITBOOST_BASE_URL> --token <TOKEN> --env <ENV> --resource-type <RESOURCE_TYPE> --resource-id <RESOURCE_ID> --descriptor-file <INPUT_FILE> [options]

Options

Flag	Required	Default	Description
--base-url <BASE_URL>	✅	env/config	Base URL of the Witboost Computational Governance Platform. Must be provided via either CLI, environment variable (WCG_BASE_URL), or config file (key: "WCG_BASE_URL")
--witboost-base-url <WITBOOST_BASE_URL>	✅	env/config	It is the URL you use to access Witboost e.g. https://witboost.my-example-company.com . Must be provided via either CLI, environment variable (WITBOOST_BASE_URL), or config file (key: "WITBOOST_BASE_URL")
--token <TOKEN>	✅	env/config	User/Service Account Access Token to authenticate with the Witboost API. Must be provided via either CLI, environment variable (ACCOUNT_ACCESS_TOKEN), or config file (key: "ACCOUNT_ACCESS_TOKEN")
--jwt-duration <JWT_DURATION>		-	(Optional) User/Service Account JWT duration in seconds
--env <ENV>	✅	-	Witboost environment in which the resource is evaluated
--resource-type <RESOURCE_TYPE>	✅	-	Resource type of the resource to be evaluated
--resource-id <RESOURCE_ID>	✅	-	Assign an identifier to the resource being evaluated
--resource-name <RESOURCE_NAME>		-	(Optional) Assign a display name to the resource being evaluated. If not provided, the resource ID will be used as the name
--resource-version <RESOURCE_VERSION>		-	(Optional) Assign a version to the resource being evaluated
--descriptor-file <INPUT_FILE>	✅	-	Path to a YAML file containing the resource descriptor. JSON descriptors can be converted to YAML using the 'utils json-to-yaml' command
--exit-on-failure		-	(Optional) Exit with non-zero code if evaluation completes with policy errors
--output <OUTPUT>		none	(Optional) Format of the evaluation report given at the end of the evaluation process
--output-file <OUTPUT_FILE>		-	(Optional) Path where to write the evaluation report either as a table or formatted as JSON (depending on the --output option). Note that --output-file report.json --output json is equivalent to piping stdout to a file named report.json e.g. witboost governance evaluate ... --output json > report.json
--compact-summary		false	(Optional) Print a compact summary table to stdout (recommended for narrow or CI environments)
--poll-interval <POLL_INTERVAL>		3	(Optional) Polling interval in seconds
--timeout <TIMEOUT>		300	(Optional) Maximum evaluation timeout in seconds

Additional help notes

This command evaluates a resource descriptor against the Governance Entities (policies and metrics) registered in the Witboost platform.
During evaluation, a resource is evaluated against a Governance Entity only if it falls within its perimeter. The perimeter is defined by:
  • Resource Type: the type of resources the Governance Entity applies to
  • Environment: the environment the Governance Entity applies to
  • Selectors: a set of key-value pairs that further filter the resources the Governance Entity applies to
  • Infrastructure Template ID and Use Case Template ID: further filters that can be used to restrict the resources the Governance Entity applies to
    
Notes:
- Only --witboost-base-url and --token can come from environment variables or config file (.witboost-cli/config.yaml). All other options must be provided via CLI.
- Authentication options are resolved with the following precedence: CLI arguments > environment variables > configuration file.
- Make sure that the relevant resource types, policies, and metrics are already registered in the Witboost platform.
- For more details about the evaluation, see: https://docs.witboost.com/docs/p3_tech/p11_managing_policies/p11_6_evaluation_and_testing

Examples:

# 1. Evaluate a resource using options via CLI
witboost governance evaluate \
  --base-url https://governance.example.com \
  --witboost-base-url https://witboost.example.com \
  --token $ACCOUNT_ACCESS_TOKEN \
  --env dev \
  --resource-type dataproduct \
  --resource-id my-dp \
  --descriptor-file ./dp.yaml

# 2. Use environment variables (token, witboost-base-url and wcg-base-url)
export ACCOUNT_ACCESS_TOKEN=xxx
export WITBOOST_BASE_URL=https://witboost.my-example-company.com
export WCG_BASE_URL=https://governance.example.com
witboost governance evaluate \
  --env dev \
  --resource-type dataproduct \
  --resource-id my-dp \
  --descriptor-file ./dp.yaml

# 3. Generate JSON evaluation report to a custom file
witboost governance evaluate \
  --base-url https://governance.example.com \
  --witboost-base-url https://witboost.my-example-company.com \
  --token $ACCOUNT_ACCESS_TOKEN \
  --env prod \
  --resource-type myrestype \
  --resource-id myres-42 \
  --descriptor-file ./myres.yaml \
  --output json \
  --output-file ./myres_report.json

# 4. Exit with non-zero code on policy failures
witboost governance evaluate \
  --base-url https://governance.example.com \
  --witboost-base-url https://witboost.my-example-company.com \
  --token $ACCOUNT_ACCESS_TOKEN \
  --env dev \
  --resource-type dataproduct \
  --resource-id my-dp \
  --descriptor-file ./dp.yaml \
  --exit-on-failure

witboost utils

Utility commands

Usage

witboost utils [options] [command]

witboost utils json-to-yaml

Convert a JSON file to a YAML file

Usage

witboost utils json-to-yaml [options]

Options

Flag	Required	Default	Description
-i, --input <filePath>	✅	-	Path to the input JSON file
-o, --output <filePath>		-	Path to the output YAML file. Defaults to input file path with '.json' replaced with '.yaml'