Version: Current

Command Reference

This page provides a reference for the production CradleXC cxc command-line interface, with target generation ending at the build and rebuild workflow.

For the command list available in your installed version, run:

cxc --help

For command-specific options, use:

cxc <command> --help

For example:

cxc compile --help

note

Command options can change between CradleXC releases. Use the built-in --help output when you need the exact options supported by the installed version.

Command summary

Command	Purpose
`cxc validate`	Parse and validate CRADLE source syntax and structure.
`cxc compile`	Compile CRADLE source into structured YAML.
`cxc dump-ir`	Display CradleXC's intermediate representation.
`cxc build`	Generate target-specific files through a backend plugin.
`cxc rebuild`	Compare a scenario with the previous build and regenerate its complete file set.
`cxc plugin list`	List installed backend plugins, or available plugins when none are installed.
`cxc plugin install`	Install a backend plugin.
`cxc completions`	Generate shell completion scripts.
`cxc configs list`	List available configuration content.
`cxc heuristics list`	List available heuristic content.
`cxc doctor`	Check dependencies and environment readiness.
`cxc install-deps`	Display dependency installation guidance.
`cxc config`	Inspect the current CradleXC configuration.

`cxc validate`

Parses a CRADLE scenario and validates its syntax and structure.

Usage

cxc validate -i <scenario.cradle>

Use --json for structured diagnostics:

cxc validate -i <scenario.cradle> --json

Example

cxc validate -i scenarios/HelloWorld.cradle

Use this command before compilation to identify syntax problems in the source scenario.

For more information, see Validate and Compile.

`cxc compile`

Compiles a CRADLE scenario into structured YAML.

Usage

cxc compile \
  -i <scenario.cradle> \
  -o <output.yml>

Example

cxc compile \
  -i scenarios/HelloWorld.cradle \
  -o HelloWorld.yml

The input is the human-authored .cradle scenario.

The output is the compiled YAML representation produced by CradleXC.

Common arguments

Argument	Purpose
`-i`	Specifies the input `.cradle` file.
`-o`	Specifies the output YAML file.

For more information, see Validate and Compile.

`cxc dump-ir`

Displays the intermediate representation produced by CradleXC.

Usage

cxc dump-ir -i <scenario.cradle>

Example

cxc dump-ir -i scenarios/HelloWorld.cradle

This command is useful when:

inspecting how CradleXC interpreted a scenario
diagnosing unexpected compiler output
investigating compiler behavior
developing or debugging backend integration

cxc dump-ir does not replace validation or compilation.

For more information, see Inspect Output.

`cxc completions`

Generates shell completion definitions for the selected shell:

cxc completions <shell>

The command is hidden from the top-level help output because Debian package installation generates and installs completions automatically. Use it directly when maintaining a manual installation.

`cxc configs list` and `cxc heuristics list`

List the content available in the configured directories:

cxc configs list
cxc heuristics list

Use --config-dir or --heuristics-dir to inspect a specific local directory. These commands inspect content; they do not generate target files or deploy a scenario.

`cxc build`

Generates target-specific files through a compatible backend plugin.

Usage

cxc build \
  -i <scenario.cradle> \
  --target <plugin_name> \
  -o <output_directory>

Example

cxc build \
  -i scenarios/HelloWorld.cradle \
  --target vagrant \
  -o ./output

Arguments used in this workflow

Argument	Purpose
`-i`	Specifies the input `.cradle` scenario.
`--target`	Selects the backend target.
`-o`	Specifies the output location. When omitted, the default is `./build_<target>`.
`--backend-arg key=value`	Passes a repeatable backend-specific option.
`--config-dir`	Overrides the configured content directory for `config()` entries.
`--extra-config-dir`	Adds a lower-precedence directory for missing `config()` entries; repeatable.
`--heuristics-dir`	Overrides the configured content directory for instance heuristics.
`--extra-heuristics-dir`	Adds a lower-precedence directory for missing heuristic entries; repeatable.

A compatible backend plugin must be available for the selected target.

When a heuristic manifest or the packaged heuristics database supplies an instance's required operating system or configs, CradleXC resolves those requirements before validation. An explicit os() remains authoritative; a conflicting implied OS produces a warning, while conflicting implied operating systems without an explicit os() produce an error.

When no backend plugin is registered, build and rebuild are hidden from the top-level cxc --help command list, although direct invocation still reports the normal target-discovery error.

important

cxc build generates target-specific files. CradleXC does not automatically execute those files.

Use the generated files with the corresponding tools in your own testbed environment.

note

The default output directory is ./build_<target>, and build state is stored in .cxc-build.json and .cxc-build-ir.json.

Build state is refreshed after every successful render. A backend that exposes stage commands can also make cxc build print suggested boot, provision and event commands after generation; these are hints and are not run automatically.

For backend installation and configuration, see Use a Backend.

`cxc rebuild`

Compares the current scenario with the IR snapshot from the most recent successful cxc build or cxc rebuild, then regenerates the backend's complete file set in the same output directory.

Usage

cxc rebuild \
  -i <scenario.cradle> \
  --target <plugin_name> \
  -o <existing_output_directory>

Example

cxc rebuild \
  -i scenarios/HelloWorld.cradle \
  --target vagrant \
  -o ./output

The output directory must already exist and contain .cxc-build-ir.json from a successful build. Run cxc build once to create the required build state.

cxc rebuild reports every instance as added, removed, recreated, reprovisioned or unchanged, with reasons for recreate and reprovision changes. It then asks the backend to render the complete current file set. It is not a partial file writer.

Difference	Classification
Platform, OS version, architecture, CPU, memory, interfaces or router/Windows status	Recreate
Configs, objects, roles, routes or heuristic membership	Reprovision
Instance only in the current scenario	Added
Instance only in the previous build	Removed
No deployment-relevant change	Unchanged

A pure reordering of the same heuristics is unchanged. Adding, removing or replacing a heuristic is a reprovision change.

important

cxc rebuild only updates generated files. It does not create, change or remove a live deployment. If network identity or addressing changed, it stops and asks you to run cxc build into a fresh output directory instead.

After a successful rebuild, compatible backends may print boot or provision commands scoped to the affected instances. These are suggestions only and are not executed by CradleXC.

`cxc plugin list`

Lists installed backend plugins. If none are installed, it lists the plugins available from the configured release source.

Usage

cxc plugin list

Backend executables follow the naming convention:

cxc-backend-<name>

CradleXC discovers compatible backend executables from:

PATH

the default system-wide directory:

/opt/cxc/plugins/

or the per-user directory:

~/.cxc/plugins/

Use this command after installing a backend to confirm that CradleXC can discover it.

For more information, see Backend Discovery.

`cxc plugin install`

Installs a backend plugin.

Usage

sudo cxc plugin install <plugin_name>

Example

sudo cxc plugin install vagrant

After installation, check whether the backend is available:

cxc plugin list

The default install location is /opt/cxc/plugins/. Use cxc plugin install --user <plugin_name> only when you explicitly want a per-user installation in ~/.cxc/plugins/.

The exact plugin names available depend on the backend plugins published for CRADLE.

For more information, see Use a Backend.

`cxc doctor`

Checks dependencies and the current CradleXC environment.

Usage

cxc doctor

Use this command when:

setting up CradleXC
checking required dependencies
diagnosing environment problems
investigating backend-related dependency problems

If required dependencies are missing, use:

cxc install-deps

For troubleshooting guidance, see Troubleshooting.

`cxc install-deps`

Displays dependency installation guidance.

Usage

cxc install-deps

A typical dependency workflow is:

cxc doctor
cxc install-deps
cxc doctor

The first cxc doctor identifies dependency problems.

cxc install-deps provides installation guidance.

Run cxc doctor again after resolving the reported issues.

`cxc config`

Displays the current CradleXC configuration.

Usage

cxc config

Use this command when checking:

local CradleXC settings
configured paths
repository-related configuration
other CLI configuration values

Detailed configuration behavior is covered in CLI Configuration.

Global help

Display the main CLI help:

cxc --help

Display the installed version:

cxc --version

For command-specific help:

cxc <command> --help

Examples:

cxc validate --help

cxc compile --help

cxc build --help

Typical scenario workflow

For normal CRADLE scenario development:

cxc validate -i scenarios/HelloWorld.cradle

Then compile:

cxc compile \
  -i scenarios/HelloWorld.cradle \
  -o HelloWorld.yml

If you need to inspect the intermediate representation:

cxc dump-ir -i scenarios/HelloWorld.cradle

If target-specific files are required, confirm the backend:

cxc plugin list

Then generate the files:

cxc build \
  -i scenarios/HelloWorld.cradle \
  --target <plugin_name> \
  -o ./output

The overall workflow is:

CRADLE source

↓

cxc validate

↓

cxc compile

↓

Compiled representation

↓

cxc build

↓

Target-specific files

Command groups

Scenario processing

Validate CRADLE source syntax.

cxc validate

Compile CRADLE source into YAML.

cxc compile

Inspect the intermediate representation.

cxc dump-ir

Backend plugins

List discovered backend plugins.

cxc plugin list

Install a backend plugin.

sudo cxc plugin install

Generate target-specific files.

cxc build

Environment

Check the current environment.

cxc doctor

Display dependency installation guidance.

cxc install-deps

Inspect CradleXC configuration.

cxc config

Command summary​

cxc validate​

Usage​

Example​

cxc compile​

Usage​

Example​

Common arguments​

cxc dump-ir​

Usage​

Example​

cxc completions​

cxc configs list and cxc heuristics list​

cxc build​

Usage​

Example​

Arguments used in this workflow​

cxc rebuild​

Usage​

Example​

cxc plugin list​

Usage​

cxc plugin install​

Usage​

Example​

cxc doctor​

Usage​

cxc install-deps​

Usage​

cxc config​

Usage​

Global help​

Typical scenario workflow​

Command groups​

Scenario processing​

Backend plugins​

Environment​

Related documentation​

Command summary

`cxc validate`

Usage

Example

`cxc compile`

Usage

Example

Common arguments

`cxc dump-ir`

Usage

Example

`cxc completions`

`cxc configs list` and `cxc heuristics list`

`cxc build`

Usage

Example

Arguments used in this workflow

`cxc rebuild`

Usage

Example

`cxc plugin list`

Usage

`cxc plugin install`

Usage

Example

`cxc doctor`

Usage

`cxc install-deps`

Usage

`cxc config`

Usage

Global help

Typical scenario workflow

Command groups

Scenario processing

Backend plugins

Environment

Related documentation