> For the complete documentation index, see [llms.txt](https://bluebricks.co/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://bluebricks.co/docs/orchestration/packages/artifacts-overview/creating-artifacts.md).

# Creating Artifacts via CLI

## Overview

This guide covers publishing artifacts using the [bricks CLI](/docs/bricks-cli/bricks-cli.md). Use this approach when Bluebricks cannot access your repository directly, for example with private repos without the [GitHub integration](/docs/integrations/github.md), or non-GitHub version control systems.

{% hint style="success" icon="box-open-full" %}
If you've connected GitHub or are using a public repo, you can create artifacts directly in the Bluebricks app during blueprint creation. [See Creating Blueprints to learn how](/docs/orchestration/packages/blueprints-overview/creating-blueprints.md)
{% endhint %}

## Supported IaC types

Bluebricks supports multiple IaC technologies:

* Terraform
* OpenTofu
* Helm
* CloudFormation
* Bicep
* Generic (container-based execution)

{% hint style="info" %}
Don't have code that defines your resources yet? Let the [cloud import agent](/docs/agent/codifying-infrastructure.md) codify them for you.
{% endhint %}

## How to publish artifacts via CLI

An artifact is automatically generated through a single CLI command from the code's directory.

**Prerequisites**

* Installed [bricks command line](https://bluebricks.co/docs/bricks-cli/bricks-cli)

{% stepper %}
{% step %}
**Navigate to your code's root folder**

For example:

```
my_s3_module/
├── main.tf              # Infrastructure definitions
├── variables.tf         # Input variables
├── outputs.tf           # Output values
└── versions.tf          # Provider versions
```

{% hint style="info" %}
Your code must be self-contained and executable with its native tool, such as terraform init/plan/apply or helm install. *For Terraform or OpenTofu, this means the **root module** you would normally navigate into and run directly.*
{% endhint %}
{% endstep %}

{% step %}
**Publish with the CLI**

Publish it from the artifact directory:

```bash
bricks blueprint publish
```

This command generates a slim metadata file (bricks.json) and publishes it into the Bluebricks catalog.
{% endstep %}

{% step %}
**View your artifacts**

Go to the [Artifacts page](https://app.bluebricks.co/packages) in Bluebricks to see your new artifact.
{% endstep %}
{% endstepper %}

## How to update your artifacts with CLI

Following any change to the underlying IaC you should update your artifact and re-publish it.

{% stepper %}
{% step %}
**Navigate to your code's root folder**
{% endstep %}

{% step %}
**Change the artifacts version**

Run the following command to update the semantic version

```bash
bricks blueprint bump
```

You can also manually open the bricks.json file of the artifact, change the version and save it.
{% endstep %}

{% step %}
**Publish the new version**

Publish the new version using

```bash
bricks blueprint publish
```

{% endstep %}
{% endstepper %}

## Artifact example

Every artifact is defined by a `bricks.json` file at its root.

This file describes:

* The artifact name
* Semantic version
* Inputs (`props`)
* Outputs (`outs`)
* The native IaC implementation (`native`)

**Example:**

```jsonc
{
  "name": "aws_vpc",
  "description": "Creates a VPC with public and private subnets",
  "version": "1.2.0",
  "native": {
    "type": "terraform",
    "path": "./terraform"
  }
}
```

A standard artifact repository:

```
my_s3_artifact/
├── bricks.json          # Artifact definition
├── main.tf              # Infrastructure definitions
├── variables.tf         # Input variables
├── outputs.tf           # Output values
└── versions.tf          # Provider versions
├── README.md            # Documentation
└── examples/            # Usage examples
    └── basic/
        ├── main.tf
```

## Publishing options

The `bricks blueprint publish` command accepts publish-specific flags:

| Flag                | Description                                                                |
| ------------------- | -------------------------------------------------------------------------- |
| `--src <path>`      | Publish from a specific directory instead of the current working directory |
| `--state`           | Include a `.tfstate` file in the published artifact for migration purposes |
| `--resolve-modules` | Resolve and include external Terraform module references (default: `true`) |

**Examples:**

```bash
# Publish from a different directory
bricks blueprint publish --src ./my_artifact

# Include state file for migration
bricks blueprint publish --state

# Disable external module resolution
bricks blueprint publish --resolve-modules=false
```

{% hint style="info" %}
Global CLI flags such as `--api-key` and `--non-interactive` are also available on this command. See the [CLI Reference](/docs/bricks-cli/cli-reference/bricks_blueprint/bricks_blueprint_publish.md) for the full list, and [CLI Authentication](/docs/bricks-cli/authentication.md) for details on API key usage.
{% endhint %}

## Publishing flow

When you run `bricks blueprint publish`, the CLI performs these steps:

{% stepper %}
{% step %}
**Validation**

The CLI validates your `bricks.json` configuration and checks that all required fields are present.
{% endstep %}

{% step %}
**Source preparation**

The artifact source code is packaged into a zip archive. External Terraform module references are resolved unless `--resolve-modules=false` is set.
{% endstep %}

{% step %}
**Upload**

The packaged artifact and `bricks.json` are uploaded to the Bluebricks platform as a single multipart request.
{% endstep %}

{% step %}
**Registration**

The artifact is registered in your organization's catalog with the version specified in `bricks.json`.
{% endstep %}

{% step %}
**Confirmation**

The CLI returns a success confirmation with the published artifact details.
{% endstep %}
{% endstepper %}

## Authentication for CI/CD

For automated pipelines, authenticate with an API key instead of interactive login:

```bash
# Environment variable (recommended)
export BRICKS_API_KEY="bbx_your_api_key_here"
bricks blueprint publish

# CLI flag
bricks blueprint publish --api-key "bbx_your_api_key_here"
```

For full details on API key creation and authentication methods, see [CLI Authentication](/docs/bricks-cli/authentication.md).

{% hint style="info" %}
For GitHub Actions workflows, use the [Bricks Action](/docs/integrations/githubactions.md) instead of running CLI commands directly.
{% endhint %}