Local Development

Test and iterate on blueprints locally using bricks run before deploying to cloud environments

Use bricks run to test a published blueprint locally before deploying to a cloud environment. This lets you validate configuration, inspect execution plans, and iterate without affecting live infrastructure.

How it works

Run a published blueprint directly from the registry:

bricks run @namespace/blueprint-name@version [flags]

You can also point at a local directory after fetching a blueprint (see below):

bricks run ./my-blueprint [flags]

For the full flag reference, see bricks run.

Fetching a blueprint locally

Use bricks blueprint fetch to download a blueprint from the registry to your local machine:

bricks blueprint fetch @namespace/blueprint-name@version --output ./my-blueprint

If the blueprint contains child packages, include them with --include-children:

bricks blueprint fetch @namespace/blueprint-name@version --output ./my-blueprint --include-children

To inspect the expected inputs before running, use bricks blueprint get props:

bricks blueprint get props @namespace/blueprint-name@version

Then prepare a JSON properties file and run locally:

bricks run ./my-blueprint --props-file props.json

For the full flag reference, see bricks blueprint fetch.

The --props-file and --secrets-file flags accept JSON only. YAML is not supported. Passing a YAML file will cause a parsing error.

Development workflow

1

Choose a blueprint

Pick a published blueprint from the Bluebricks registry.

2

Fetch and inspect

Download the blueprint and review its expected inputs:

bricks blueprint fetch @namespace/blueprint-name@version --output ./my-blueprint
bricks blueprint get props @namespace/blueprint-name@version

3

Prepare properties

Create a JSON file with the required properties:

{
  "region": "us-east-1",
  "instance_type": "t3.medium"
}

4

Plan locally

Preview the execution plan without applying changes:

bricks run @namespace/blueprint-name@version --dry --props-file props.json

5

Apply locally

Execute the blueprint on your machine:

bricks run @namespace/blueprint-name@version --props-file props.json

6

Iterate

Review outputs, fix issues, adjust configuration, and repeat. Use --verbose to see detailed execution steps:

bricks run @namespace/blueprint-name@version --dry --verbose --props-file props.json

Common flags

Flag	Purpose
--dry	Generate plan without applying
--apply	Apply the plan instead of running in plan-only mode
--destroy	Generate destroy plan
--verbose	Print detailed execution steps
--props-file FILE	Load properties from a JSON file
--props JSON	Pass properties as an inline JSON string
--secrets-file FILE	Load secrets from a JSON file
--secrets JSON	Pass secrets as an inline JSON string
--output DIR	Set output directory for plan, state, and artifacts

Local state

When you run a blueprint locally, state is stored in the output directory:

./packages/
├── <package-id>/
│   ├── state.json
│   ├── plan.json
│   └── outputs.json

Local state is not uploaded to Bluebricks. It persists across local runs and can be cleared manually with rm -rf ./packages/.

Local vs cloud execution

	Local (bricks run)	Cloud (bricks install)
Cloud resources	Plans generated, no API calls	Full cloud provisioning
State	Local filesystem	Centralized in Bluebricks
Tracking	Not tracked	Full history in Bluebricks
Team visibility	Local only	Shared across team
Authentication	Local cloud credentials required	Collection-managed credentials

Transitioning to cloud

After local validation, deploy to a cloud environment:

bricks install @namespace/blueprint-name@version --collection development

Property files you used locally work with cloud deployments too:

bricks install @namespace/blueprint-name@version --collection production --props-file props.json

For Terraform/OpenTofu artifacts, you can also develop against remote state using bricks bp state-config. See Develop Terraform Locally for that workflow.

See also

• bricks run reference

• bricks blueprint fetch reference

• Develop Terraform Locally

• Inputs & Outputs