# primitives group

> Create, list, inspect and destroy groups in the local data directory.

Source: https://useprimitives.com/docs/cli/group

`primitives group` manages the [groups](/docs/concepts/groups) in the local data directory. A group starts empty; add primitives to it with [`primitives primitive create`](/docs/cli/primitive#create).

| Command | Description |
| --- | --- |
| [`group create <NAME>`](#create) | Create an empty group |
| [`group list`](#list) | List groups |
| [`group info <NAME>`](#info) | Show a group and its primitives |
| [`group destroy <NAME>`](#destroy) | Delete a group |

Group names are 1–63 characters from `a-z`, `0-9`, `-`, `_` and `.`, starting with a letter or digit, with no `..`.

## create

```bash
primitives group create agent-42
```

Prints the group's manifest:

```json
{
  "id": "01m5h39p027ffp4y4n7gs2g0ex",
  "namespace": "default",
  "name": "agent-42",
  "created_at": 1792648992770
}
```

Fails with `already_exists` if the name is taken.

## list

```bash
primitives group list
```

Prints every group's manifest:

```json
[
  {
    "id": "01m5h39p027ffp4y4n7gs2g0ex",
    "namespace": "default",
    "name": "agent-42",
    "created_at": 1792648992770
  }
]
```

## info

```bash
primitives group info agent-42
```

Prints the manifest and every primitive in the group:

```json
{
  "group": {
    "created_at": 1792648992770,
    "id": "01m5h39p027ffp4y4n7gs2g0ex",
    "name": "agent-42",
    "namespace": "default"
  },
  "primitives": [
    {
      "created_at": 1792648992795,
      "forked_from": null,
      "group": "agent-42",
      "id": "01m5h39p0vy29h524y1nzc9dh2",
      "name": "orders",
      "paused": false,
      "size_bytes": 0,
      "type": "db"
    }
  ]
}
```

## destroy

```bash
primitives group destroy agent-42
```

| Option | Description |
| --- | --- |
| `--force` | Also delete every primitive in the group, with its data and snapshots |

Without `--force`, a group that still has primitives isn't deleted:

```text
Error: Error { code: Conflict, message: "group \"agent-42\" still has 2 primitive(s); delete them first or pass force" }
```

On success it prints `destroyed agent-42` to stderr. This can't be undone.