CLI Outputs

CradleXC can produce several forms of output depending on the command used.

The main output types are:

• validation diagnostics
• intermediate representation output
• compiled YAML
• backend-generated target-specific files

These outputs serve different purposes and should not be treated as interchangeable.

Output overview

The main workflow is:

CRADLE source

↓

Validation diagnostics

↓

Intermediate representation

↓

Compiled YAML

↓

Backend-generated target files

Not every workflow requires every output.

For example, cxc dump-ir is optional during normal scenario development.

Validation diagnostics

Use:

cxc validate -i <scenario.cradle>

to check whether the CRADLE source syntax is valid.

For example:

cxc validate -i scenarios/HelloWorld.cradle

If the scenario contains problems, CradleXC reports diagnostics that can help identify the source of the error.

Validation does not produce the compiled YAML or target-specific backend files.

For detailed diagnostic guidance, see Diagnostics.

Intermediate representation

Use:

cxc dump-ir -i <scenario.cradle>

to display the intermediate representation produced by CradleXC.

For example:

cxc dump-ir -i scenarios/HelloWorld.cradle

This output is useful when:

• inspecting how CradleXC interpreted a scenario
• debugging unexpected compiler behavior
• comparing source structure with compiler output
• investigating backend integration

The intermediate representation is primarily an inspection and diagnostic output.

note

You do not need to use cxc dump-ir during every normal workflow.

Compiled YAML

Use cxc compile to produce the compiled YAML representation of a CRADLE scenario.

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

For example:

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

This creates:

HelloWorld.yml

The YAML file contains the compiled representation produced by CradleXC from the authored CRADLE source.

Source and compiled output

The .cradle file remains the authored scenario source.

For example:

scenarios/HelloWorld.cradle

The YAML file is generated output:

HelloWorld.yml

The relationship is:

HelloWorld.cradle

↓

CradleXC

↓

HelloWorld.yml

File	Purpose
.cradle	Human-authored scenario source.
.yml	Compiled representation generated by CradleXC.

When changing a scenario, edit the .cradle file and compile it again.

Do not treat the generated YAML as the authoritative source definition.

Inspect compiled YAML

You can inspect the generated YAML with any text editor.

From the terminal:

cat HelloWorld.yml

For longer output:

less HelloWorld.yml

The exact structure of the YAML depends on the scenario and the CradleXC release used to compile it.

What compiled output should represent

The compiled output should reflect the major elements defined in the source scenario.

For example, the Hello World scenario contains:

• the HelloWorld instance
• the router instance
• the lan_0 network
• the HelloWorld object
• scenario metadata
• lifecycle phases
• events initialize_client, collect_evidence and cleanup

These source elements should be represented in the compiled output produced by CradleXC.

Compiler defaults

Some values can appear in compiler output even when they were omitted from the CRADLE source.

The current documentation identifies defaults including:

Property	Current CradleXC default
eventType	sequence
Endpoint address	DHCP
needRoot	false
pauseBeforeRun	0
pauseAfterRun	0

If an output value was not explicitly present in the source, check whether it was supplied as a compiler default.

note

Compiler defaults are version-specific behavior. Check the documentation for the CradleXC release you are using.

Backend-generated output

Backend plugins generate target-specific files.

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 writes its generated files to:

./output

The exact files depend on the backend implementation.

Compiled output and backend output are different

Compiled YAML and backend-generated files serve different purposes.

Output	Produced by	Purpose
Validation diagnostics	cxc validate	Reports source problems.
Intermediate representation	cxc dump-ir	Shows how CradleXC interpreted the source.
Compiled YAML	cxc compile	Represents the processed scenario.
Target-specific files	cxc build and backend plugin	Represents the scenario for a particular target.

The relationship is:

CRADLE source

↓

CradleXC

↓

Compiled representation

↓

Backend plugin

↓

Target-specific files

Backend output structure

The output directory layout is defined by the selected backend.

For example:

output/
└── ...

One backend can generate a completely different set of files from another backend.

Do not assume that all backends:

• produce the same filenames
• use the same directory structure
• support the same CRADLE features
• require the same external tools
• use the same provider configuration

Refer to the documentation for the selected backend.

Generated files are not executed automatically

CradleXC does not automatically execute backend-generated target files.

The complete workflow is:

CRADLE source

↓

CradleXC

↓

Backend plugin

↓

Generated target files

↓

User's testbed tools

After generation, use the output with the corresponding target tools in your own testbed environment.

Recommended directory layout

Keeping source and generated output separate makes the project easier to understand.

For example:

.
├── scenarios/
│   └── HelloWorld.cradle
├── build/
│   └── HelloWorld.yml
└── output/
    └── ...

Here:

scenarios/

contains authored CRADLE source.

build/

contains compiler output.

output/

contains backend-generated target files.

note

These directory names are a suggested project organization pattern, not required CRADLE directory names.

Regenerating output

Generated files should be reproducible from the CRADLE source.

After modifying:

scenarios/HelloWorld.cradle

validate it again:

cxc validate -i scenarios/HelloWorld.cradle

Then regenerate the compiled YAML:

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

If target-specific files are required, regenerate them separately:

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

This keeps generated files synchronized with the authored scenario.

Investigate unexpected output

If generated output does not match what you expected, use the following sequence.

First, validate the source:

cxc validate -i scenarios/HelloWorld.cradle

Then inspect the intermediate representation:

cxc dump-ir -i scenarios/HelloWorld.cradle

Compile again:

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

If the compiled representation looks correct but backend output does not, investigate the selected backend separately.

This helps determine whether the problem occurs during:

source

↓

CradleXC processing

↓

backend generation

Output model

Compiled YAML and Deployment IR describe different stages of CradleXC processing. For the structured model passed to backend plugins, see Deployment IR.

Output and diagnostics

Different commands provide different levels of information.

A useful diagnostic sequence is:

cxc validate -i scenarios/HelloWorld.cradle

cxc dump-ir -i scenarios/HelloWorld.cradle

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

Then, if backend output is involved:

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

This separates source validation, compiler interpretation, compiled output and backend generation.

Do not store sensitive information in generated output

Generated files can contain values derived from scenario configuration or local environment settings.

Before sharing generated output:

• review repository paths
• review local filesystem paths
• review target-specific configuration
• remove credentials or tokens
• remove private environment details that are not required

important

Treat generated files according to the sensitivity of the scenario and environment from which they were produced.

Related documentation

• CLI Overview
• Command Reference
• CLI Configuration
• Backend Discovery
• Validate and Compile
• Inspect Output
• Use a Backend
• Diagnostics
• Troubleshooting

Next steps

Use Command Reference when you need command-specific information, or continue to the CRADLE guides for task-oriented workflows.