Skip to main content
Version: Current

CLI Overview

CradleXC provides the cxc command-line interface for working with CRADLE scenarios.

The CLI is used to:

  • validate CRADLE source
  • compile scenarios
  • inspect intermediate output
  • inspect configuration
  • manage dependencies
  • discover backend plugins
  • generate target-specific files

Check the installed version​

Confirm that CradleXC is installed with:

cxc --version

For installation instructions, see Install CradleXC.

View command help​

Use:

cxc --help

to display the available commands and options for the installed CradleXC version.

For help with a specific command, use:

cxc <command> --help

For example:

cxc validate --help

or:

cxc compile --help
note

The exact command options available can vary between CradleXC releases. Use --help to confirm the interface provided by the version installed on your system.

Core workflow​

The most common workflow uses:

cxc validate
cxc compile
cxc dump-ir
cxc build

Conceptually:

CRADLE source
↓
cxc validate
↓
cxc compile
↓
Compiled representation
↓
cxc build
↓
Target-specific files

cxc dump-ir can be used separately when you want to inspect the intermediate representation produced by CradleXC.

Validate a scenario​

Use cxc validate to parse a scenario and check its syntax and structure:

cxc validate -i <scenario.cradle>

For example:

cxc validate -i scenarios/HelloWorld.cradle

Validation reports syntax problems that need to be corrected before continuing.

For more information, see Validate and Compile.

Compile a scenario​

Use cxc compile to compile a CRADLE scenario into YAML:

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

For example:

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

The resulting YAML is the compiled representation produced by CradleXC.

Inspect the intermediate representation​

Use cxc dump-ir when you need to inspect how CradleXC interpreted the source scenario:

cxc dump-ir -i <scenario.cradle>

For example:

cxc dump-ir -i scenarios/HelloWorld.cradle

This command is mainly useful for inspection, diagnostics and backend development.

It is not required during every normal workflow.

For more information, see Inspect Output.

Generate target-specific files​

CradleXC uses external backend plugins for target-specific generation.

Use:

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

For example:

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

The selected backend generates files for its supported target.

To regenerate an existing output directory after changing the scenario, use the previous build as a comparison baseline:

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

cxc rebuild reports what changed and rewrites the complete generated file set. It does not modify a live deployment. See the Command Reference for its baseline and network-change rules.

important

CradleXC does not automatically execute backend-generated files. Use those files with the corresponding tools in your own testbed environment.

For backend setup and usage, see Use a Backend.

Backend commands​

CradleXC provides commands for working with backend plugins.

List backends​

Use:

cxc plugin list

to list compatible backend plugins currently discovered by CradleXC.

Backend executables follow the convention:

cxc-backend-<name>

CradleXC discovers compatible backend executables from the system PATH, /opt/cxc/plugins/ or:

~/.cxc/plugins/

Install a plugin​

Use:

sudo cxc plugin install <plugin_name>

to install a backend plugin.

For example:

sudo cxc plugin install vagrant

Backend installation and discovery are documented in Use a Backend.

Check dependencies​

Use:

cxc doctor

to inspect dependencies required by the current CradleXC environment.

If dependencies are missing, view installation guidance with:

cxc install-deps

For installation-related information, see Install CradleXC.

View configuration​

Use:

cxc config

to inspect the current CradleXC configuration.

Configuration can include values used by the CLI and local environment.

Detailed configuration documentation is provided in CLI Configuration.

Command groups​

The current CLI can be thought of in several groups.

Scenario processing​

Check whether CRADLE source syntax is valid.

cxc validate

Compile CRADLE source into structured YAML.

cxc compile

Inspect CradleXC's intermediate representation.

cxc dump-ir

Backend generation​

Discover backend plugins available to CradleXC.

cxc plugin list

Install a compatible backend plugin.

sudo cxc plugin install

Generate target-specific files through a backend.

cxc build

Compare with the previous build and regenerate the complete file set.

cxc rebuild

Environment and utilities​

Check dependencies and environment readiness.

cxc doctor

Display dependency installation guidance.

cxc install-deps

Inspect current CradleXC configuration.

cxc config

CLI responsibilities​

The CLI sits between CRADLE source and the other CradleXC processing stages.

AreaResponsibility
Source validationCheck CRADLE syntax.
CompilationProduce the compiled representation.
InspectionExpose intermediate representation and diagnostics.
Backend discoveryLocate compatible external backend plugins.
Backend generationPass a scenario to a selected backend for target-specific output.
Environment checksInspect dependencies and configuration.

CLI and backend boundaries​

Backend commands do not make target-specific functionality part of CradleXC itself.

The separation remains:

cxc
↓
External backend plugin
↓
Generated target-specific files

Backend executables remain separate components from the core CradleXC CLI.

Troubleshooting CLI commands​

If a command fails, start by checking:

cxc --version

then:

cxc doctor

For command-specific usage:

cxc <command> --help

For example:

cxc build --help

See Troubleshooting for additional diagnostic guidance.

Next steps​

Continue with CLI Command Reference for the command-by-command reference.