# 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`](https://bluebricks.co/docs/bricks-cli/cli-reference/bricks_run).

## 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`](https://bluebricks.co/docs/bricks-cli/cli-reference/bricks_blueprint/bricks_blueprint_fetch).

{% 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](https://bluebricks.co/docs/bricks-cli/cli-reference/bricks_run)
* [`bricks blueprint fetch` reference](https://bluebricks.co/docs/bricks-cli/cli-reference/bricks_blueprint/bricks_blueprint_fetch)
* [Develop Terraform Locally](https://bluebricks.co/docs/help/guides/develop-terraform-locally)
* [Inputs & Outputs](https://bluebricks.co/docs/core-concepts/packages/inputs-and-outputs)