Skip to content

CLI Usage

CausalIQ Workflow provides the cqflow command (alias for causaliq-workflow) for executing workflows and managing caches.

Commands

Command Description
cqflow run Execute a workflow file
cqflow export-cache Export cache to directory or zip
cqflow import-cache Import cache from export

Running Workflows

Basic Execution

# Dry-run (validate and preview) - default
cqflow run workflow.yml

# Actually execute the workflow
cqflow run workflow.yml --mode=run

Execution Modes

Mode Description
dry-run Validate workflow and preview what would be done (default)
run Execute workflow with conservative execution
force Execute workflow, bypassing conservative execution
# Preview what would happen
cqflow run workflow.yml --mode=dry-run

# Execute with conservative execution (skip completed work)
cqflow run workflow.yml --mode=run

# Force re-execution of all steps
cqflow run workflow.yml --mode=force

Workflow Parameters

Supply or override workflow parameters with --param NAME=VALUE (repeatable):

# Override a declared default
cqflow run workflow.yml --mode=run --param sample_size=5000

# Replace a matrix dimension with a single value
cqflow run workflow.yml --mode=run --param network=asia

# Provide a list of values for a matrix dimension
cqflow run workflow.yml --mode=run --param algorithm='[pc, ges]'

Values are parsed as YAML, so numbers, booleans and lists keep their types. A name that matches a matrix dimension replaces that dimension; any other name overrides a declared parameter or supplies a required {{name}} placeholder. A value supplied for a null-default parameter replaces the omission. Names the workflow does not use are reported as validation errors, and repeating a name is rejected. A parameter change does not invalidate cached entries — use --mode=force to re-run.

Logging Depth

--log-depth sets the deepest workflow nesting level that prints messages. Each level above the default adds one layer:

Depth Description
0 No output
1 Top-level summary only (default)
2 Adds the top-level steps and their CALLING/COMPLETED call boundaries
3 Adds first-level sub-workflow steps, indented by two spaces
3+ Each further level adds the next level of sub-workflow messages
# Show the top-level steps and the workflows they call
cqflow run workflow.yml --mode=run --log-depth=2

Status Messages

With --log-depth=2 or higher, each entry displays a status:

Status Dry-run Equivalent Description
EXECUTED WOULD EXECUTE Entry processed successfully
FORCED — Entry processed (force mode)
SKIPPED WOULD SKIP Already completed (conservative execution)
IGNORED WOULD IGNORE Excluded by filter expression
FAILED — Action raised an exception
CALLING — A step calls another workflow
COMPLETED — A called workflow returned, with its cumulative step counts

Example output:

2026-03-15 14:23:01 [./hc_std.yml] CALLING Run bnlearn hc with standard ordering
2026-03-15 14:23:01   [evaluate] EXECUTED eval-step [network=asia]
2026-03-15 14:23:02 [./hc_std.yml] COMPLETED Run bnlearn hc with standard ordering (1 steps: 1 executed)

Messages from a sub-workflow are indented by two spaces per call level. A failed run finishes with an ERRORS: list that names each failing step with the matrix values that identify it, capped at ten entries followed by ... and N more errors.

The step name shown is the name expanded for that job, so a {{placeholder}} in a step's name appears with its value (see Step Names).

Cache Management

Export Cache

Export cache entries to a directory or zip file for sharing or archival:

# Export to directory
cqflow export-cache -i results/graphs.db -o ./exported

# Export to zip file
cqflow export-cache -i results/graphs.db -o results.zip

Import Cache

Restore cache entries from a previous export:

# Import from directory
cqflow import-cache -i ./exported -o results/restored.db

# Import from zip file
cqflow import-cache -i results.zip -o results/restored.db

Workflow File Conventions

Workflow files typically use .yml or .yaml extension:

workflows/
├── learn_graphs.yml
├── evaluate_all.yml
└── generate_tables.yml

Organise related workflows in a directory structure that matches your project.

Environment Variables

Variable Description
CAUSALIQ_ROOT Default root directory for workflows
CAUSALIQ_LOG_DEPTH Default logging depth

Exit Codes

Code Description
0 Success
1 Workflow validation error
2 Workflow execution error

API Reference

For complete CLI details including all options and parameters, see the CLI API Reference.