# Managing Collections

## Overview

Manage the lifecycle of your collections through the Bluebricks app or the `bricks collection` CLI commands. You can list all collections, check their status, and enable, disable, or delete them as your infrastructure needs change.

{% hint style="info" icon="book" %}
To create a new collection, see [Creating Collections](/docs/orchestration/collections/create-an-environment.md). For the conceptual overview, see [Collections](/docs/orchestration/collections.md).
{% endhint %}

## How to list collections

{% tabs %}
{% tab title="Bluebricks app" %}
Open the **Collections** page in the Bluebricks app. The table shows all active collections with their cloud provider, cloud account, and latest deployment status. Use the filters to narrow results by status or provider.
{% endtab %}

{% tab title="CLI" %}

```bash
# List active collections
bricks collection ls

# Include inactive and deleted collections
bricks collection ls --all
```

The command outputs a table with the following fields:

```
GUID                                NAME           CLOUD PROVIDER   CLOUD ACCOUNT   SLUG              STATUS
----------------------------------- -------------- ---------------- --------------- ----------------- -------------------------
env-uuid-123                        production    AWS              aws-prod        production        DEFAULT, web-app (running)
env-uuid-456                        development   AWS              aws-dev         development       api-service (completed)
env-uuid-789                        staging       GCP              gcp-staging     staging           INACTIVE
```

<table><thead><tr><th width="184.71875">Field</th><th>Description</th></tr></thead><tbody><tr><td><strong>GUID</strong></td><td>Unique identifier, used in API calls and some CLI commands (<code>--id</code>)</td></tr><tr><td><strong>NAME</strong></td><td>Display name set during creation</td></tr><tr><td><strong>CLOUD PROVIDER</strong></td><td>Connected provider (AWS, GCP, Azure). Shows <code>-</code> if no cloud account is connected</td></tr><tr><td><strong>CLOUD ACCOUNT</strong></td><td>Connected cloud account name. Shows <code>-</code> if none</td></tr><tr><td><strong>SLUG</strong></td><td>Short identifier used in CLI commands (<code>--slug</code>, <code>--collection</code>)</td></tr><tr><td><strong>STATUS</strong></td><td>Flags and latest deployment info (see below)</td></tr></tbody></table>
{% endtab %}
{% endtabs %}

### Status indicators

<table><thead><tr><th width="237.4921875">Indicator</th><th>Meaning</th></tr></thead><tbody><tr><td><strong>DEFAULT</strong></td><td>Collection is the default target when <code>--collection</code> is omitted</td></tr><tr><td><strong>INACTIVE</strong></td><td>Collection is disabled</td></tr><tr><td><em>deployment-name</em> <em>(stage)</em></td><td>Most recent deployment and its current stage (<code>running</code>, <code>completed</code>, <code>failed</code>)</td></tr><tr><td><code>-</code></td><td>No deployments in this collection</td></tr></tbody></table>

## Collection states

<table><thead><tr><th width="100.25">State</th><th>Description</th></tr></thead><tbody><tr><td>Active</td><td>Collection is enabled and ready for deployments</td></tr><tr><td>Inactive</td><td>Collection is disabled; enable it before deploying</td></tr><tr><td>Default</td><td>Collection is the default target for <code>bricks install</code> when no <code>--collection</code> flag is specified</td></tr></tbody></table>

## How to enable a collection

Reactivate a disabled (locked) collection so it can receive deployments again.

{% tabs %}
{% tab title="Bluebricks app" %}

1. Open the **Collections** page
2. Click the three-dot menu on the inactive collection
3. Click **Unlock**
4. Confirm in the dialog
   {% endtab %}

{% tab title="CLI" %}

```bash
# Enable by slug
bricks collection enable --slug "my-collection"

# Enable by ID
bricks collection enable --id "env-uuid-here"
```

{% endtab %}
{% endtabs %}

## How to disable a collection

Disable (lock) a collection to prevent new deployments. Existing infrastructure is not affected.

{% tabs %}
{% tab title="Bluebricks app" %}

* Open the **Collections** page
* Click the three-dot menu on the collection
* Click **Lock**
* Confirm in the dialog
  {% endtab %}

{% tab title="CLI" %}

```bash
# Disable (prompts for confirmation)
bricks collection disable --slug "my-collection"

# Skip the confirmation prompt
bricks collection disable --slug "my-collection" --y

# Disable by ID
bricks collection disable --id "env-uuid-here"
```

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
Disabling a collection does not destroy deployed resources. It only prevents new deployments from targeting this collection.
{% endhint %}

## How to delete a collection

Before deleting, destroy or [archive](/docs/orchestration/environments/archiving-environments.md) all active environments in the collection. Bluebricks blocks deletion if any non-archived environments remain.

{% tabs %}
{% tab title="Bluebricks app" %}

1. Open the **Collections** page
2. Click the three-dot menu on the collection
3. Click **Delete**
4. Review the list of associated deployments and confirm
   {% endtab %}

{% tab title="CLI" %}

```bash
bricks collection delete --slug "my-collection"
```

{% endtab %}
{% endtabs %}

The cloud account is not affected by the deletion. It remains available in your organization and can be added to a new collection at any time.

{% hint style="danger" %}
Deleting a collection is irreversible. Archived environments in a deleted collection cannot be un-archived.
{% endhint %}

## How to set a default collection

The default collection is used when you run `bricks install` without specifying `--collection`.

{% tabs %}
{% tab title="Bluebricks app" %}

1. Open the **Collections** page
2. Click the three-dot menu on the collection
3. Click **Set as Default**
4. Confirm in the dialog
   {% endtab %}

{% tab title="CLI" %}
You can set a collection as the default during creation:

```bash
bricks collection create --name "development" --default
```

{% endtab %}
{% endtabs %}

## How to clone a collection

Duplicate an existing collection with its configuration.

### Using the app

1. Open the **Collections** page
2. Click the three-dot menu on the collection
3. Click **Clone**
4. Confirm in the dialog


---

# 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/collections/managing-collections.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.