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


---

# 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/artifacts-overview/creating-artifacts.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.