# Local Development

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:

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

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

```bash
bricks run ./my-blueprint [flags]
```

For the full flag reference, see [`bricks run`](/docs/bricks-cli/cli-reference/bricks_run.md).

## Fetching a blueprint locally

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

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

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

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

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

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

Then prepare a JSON properties file and run locally:

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

For the full flag reference, see [`bricks blueprint fetch`](/docs/bricks-cli/cli-reference/bricks_blueprint/bricks_blueprint_fetch.md).

{% hint style="warning" %}
The `--props-file` and `--secrets-file` flags accept **JSON only**. YAML is not supported. Passing a YAML file will cause a parsing error.
{% endhint %}

## Development workflow

{% stepper %}
{% step %}
**Choose a blueprint**

Pick a published blueprint from the Bluebricks registry.
{% endstep %}

{% step %}
**Fetch and inspect**

Download the blueprint and review its expected inputs:

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

{% endstep %}

{% step %}
**Prepare properties**

Create a JSON file with the required properties:

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

{% endstep %}

{% step %}
**Plan locally**

Preview the execution plan without applying changes:

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

{% endstep %}

{% step %}
**Apply locally**

Execute the blueprint on your machine:

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

{% endstep %}

{% step %}
**Iterate**

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

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

{% endstep %}
{% endstepper %}

## Common flags

<table><thead><tr><th width="212.59375">Flag</th><th>Purpose</th></tr></thead><tbody><tr><td><code>--dry</code></td><td>Generate plan without applying</td></tr><tr><td><code>--apply</code></td><td>Apply the plan instead of running in plan-only mode</td></tr><tr><td><code>--destroy</code></td><td>Generate destroy plan</td></tr><tr><td><code>--verbose</code></td><td>Print detailed execution steps</td></tr><tr><td><code>--props-file FILE</code></td><td>Load properties from a JSON file</td></tr><tr><td><code>--props JSON</code></td><td>Pass properties as an inline JSON string</td></tr><tr><td><code>--secrets-file FILE</code></td><td>Load secrets from a JSON file</td></tr><tr><td><code>--secrets JSON</code></td><td>Pass secrets as an inline JSON string</td></tr><tr><td><code>--output DIR</code></td><td>Set output directory for plan, state, and artifacts</td></tr></tbody></table>

## 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

<table data-header-hidden><thead><tr><th width="176.74609375"></th><th></th><th></th></tr></thead><tbody><tr><td></td><td>Local (<code>bricks run</code>)</td><td>Cloud (<code>bricks install</code>)</td></tr><tr><td>Cloud resources</td><td>Plans generated, no API calls</td><td>Full cloud provisioning</td></tr><tr><td>State</td><td>Local filesystem</td><td>Centralized in Bluebricks</td></tr><tr><td>Tracking</td><td>Not tracked</td><td>Full history in Bluebricks</td></tr><tr><td>Team visibility</td><td>Local only</td><td>Shared across team</td></tr><tr><td>Authentication</td><td>Local cloud credentials required</td><td>Collection-managed credentials</td></tr></tbody></table>

## Transitioning to cloud

After local validation, deploy to a cloud environment:

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

Property files you used locally work with cloud deployments too:

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

{% hint style="info" %}
For Terraform/OpenTofu artifacts, you can also develop against remote state using `bricks bp state-config`. See [Develop Terraform Locally](https://bluebricks.co/docs/help/guides/develop-terraform-locally) for that workflow.
{% endhint %}

## See also

* [`bricks run` reference](/docs/bricks-cli/cli-reference/bricks_run.md)
* [`bricks blueprint fetch` reference](/docs/bricks-cli/cli-reference/bricks_blueprint/bricks_blueprint_fetch.md)
* [Develop Terraform Locally](https://bluebricks.co/docs/help/guides/develop-terraform-locally)
* [Inputs & Outputs](/docs/orchestration/packages/inputs-and-outputs.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://bluebricks.co/docs/orchestration/packages/blueprints-overview/local-development.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.