Running a Blueprint

This page covers validating a Blueprint and then running it, from a test, from the command line, or through an AI coding agent. It also covers the offline path, for when you have no live system to point it at.

For writing the document itself, see Building a Blueprint. For output variables and placeholder rules, see Variables and Placeholders.

Validating first

Validation is a structural check with no system access and no side effects. Run it after every edit and fix every finding before running anything.

cycle-cli --validate-blueprint create-customer-order.yml

The run path applies the same check before it executes, so a structurally broken Blueprint reports its findings rather than a false pass. Validating first is still the faster loop, because it never touches the target system.

Advanced Blueprint Techniques lists every check validation performs and every finding it can report.

Three ways to run

Three surfaces run a Blueprint, and all three use the same engine, so behavior does not change between them.

Surface	Use it for
CycleScript steps	Running data setup as part of a test. See Using a Blueprint in a Feature File.
cycle-cli	Authoring and debugging a Blueprint outside a test.
Cycle MCP tools	Letting an AI coding agent author, validate, and run a Blueprint.

Command-line flags

These are the command-line flags for the Blueprint path.

Flag	Purpose
--blueprint <path>	Runs a Blueprint and prints its realized variables. A bare cycle-cli <file>.yml does the same.
--validate-blueprint <path>	Structural check only. No execution and no system access.
-project-file <.cycproj>, or -p	Loads the project's settings, stored connections and credentials, and blueprint.libraryDir. Required when the connection or variables come from a system configuration.
-user-profile <user>, or -u	Selects the .cycuser supplying stored credentials. Meaningful only with -project-file.
-offline <db>	Runs against a local SQLite database file instead of the configured connection.
-offline-setup <fixture.sql>	Builds a fresh SQLite database from a .sql schema and seed file first. Used alone, it creates a temporary database per run.

MCP tools

The three MCP tools are blueprint_validate, blueprint_run, and blueprint_teardown. blueprint_run takes exactly one of blueprint_id for a catalog scenario, blueprint_file for a path, or blueprint_yaml for inline YAML. Only blueprint_id requires a project, because only that mode consults the catalog. blueprint_teardown uses a two-call protocol: the first call previews what would be removed and deletes nothing, and only a second call with confirmation executes.

A library-relative path stays inside the library

When blueprint_file is relative and you pass a project_path, it resolves against the project's blueprint.libraryDir, and a .. segment is refused. To point at a file outside the library, pass an absolute path instead. A system_config value and a Blueprint's own name: are library lookup keys as well, so they carry the same restriction: no .., and no absolute path.

Smoke testing without a live system

You do not need a live environment to prove a Blueprint holds together.

• A flat_file Blueprint is fully self-contained, because it only writes local files. It needs no project, connection, or credential, which makes it the quickest thing to run.
• A sql or moca Blueprint needs a datastore. Give it a live connection, the -offline options, or an inline type: sqlite connection pointing at a local file.
• An api or mongodb Blueprint has no offline backend, so it always reaches its real endpoint. An inline connection is enough to run it without a project.

cycle-cli create-customer-order.yml -offline ./crm.db -offline-setup ./crm-schema.sql

An offline moca run additionally needs a components block that maps each entity phrase to its physical table, such as order to ord. Declare it in the system configuration or inline in the Blueprint. List singular and plural phrases explicitly, because Cycle does not pluralize them for you. Without a matching component the run fails with an unknown entity error.

An offline run is a structural check, not a fidelity check

An offline run always uses SQLite, and the MOCA emulator translates bare verbs into SQL rather than reproducing server logic. Type affinity, rownum, date handling, and upsert semantics differ from Oracle, MySQL, and SQL Server, so a clean offline run does not prove the Blueprint works against the real system. Validate against the target system before relying on it.