# primitives primitive

> Create, list, rename, delete, snapshot, restore, fork, pause and resume primitives by id.

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

`primitives primitive` manages databases, filesystems, queues, memories, vaults, KV stores and object stores in the local data directory. Every subcommand except `create` and `list` addresses a primitive by its immutable `id`, which `create` and `list` print.

| Command | Description |
| --- | --- |
| [`primitive create <NAME>`](#create) | Create a primitive in a group |
| [`primitive list`](#list) | List primitives, with ids |
| [`primitive info <ID>`](#info) | Show a primitive |
| [`primitive rename <ID> <NAME>`](#rename) | Rename it. The id stays the same |
| [`primitive delete <ID>`](#delete) | Delete it, with its data and snapshots |
| [`primitive snapshot <ID>`](#snapshot) | Take a snapshot |
| [`primitive snapshots <ID>`](#snapshots) | List its snapshots |
| [`primitive restore <ID> <SNAPSHOT>`](#restore) | Restore it to a snapshot |
| [`primitive fork <ID>`](#fork) | Copy it into a new primitive |
| [`primitive pause <ID>`](#pause-and-resume) | Pause every data operation |
| [`primitive resume <ID>`](#pause-and-resume) | Resume a paused primitive |

Types are `db`, `fs`, `queue`, `memory`, `vault`, `kv` and `storage`. The CLI manages the lifecycle; to read and write data, use [`primitives dev`](/docs/cli/dev) with an [SDK](/docs/sdk), the [REST API](/docs/api) or [MCP](/docs/mcp).

## create

```bash
primitives primitive create orders --type db --group agent-42
```

| Option | Description |
| --- | --- |
| `--type <TYPE>` | Required. `db`, `fs`, `queue`, `memory`, `vault`, `kv` or `storage` |
| `--group <GROUP>` | Required. The group to create it in. It must exist |

Prints the new primitive, including its `id`:

```json
{
  "id": "01m5h39p0vy29h524y1nzc9dh2",
  "group": "agent-42",
  "type": "db",
  "name": "orders",
  "created_at": 1792648992795,
  "paused": false,
  "size_bytes": 0,
  "forked_from": null
}
```

Names are unique per group and type: a second `db` named `orders` in `agent-42` fails with `already_exists`, while a `kv` named `orders` is fine.

## list

```bash
primitives primitive list --group agent-42 --type db
```

| Option | Description |
| --- | --- |
| `--group <GROUP>` | Only primitives in this group |
| `--type <TYPE>` | Only primitives of this type |

Prints an array of primitives in the same shape as `create`.

## info

```bash
primitives primitive info 01m5h39p0vy29h524y1nzc9dh2
```

Prints the primitive, with its current `size_bytes` and `paused` state.

## rename

```bash
primitives primitive rename 01m5h39p0vy29h524y1nzc9dh2 orders-v1
```

Renames within its group and prints the primitive. The id doesn't change, so nothing that holds the id breaks. Primitives can't move between groups; [fork](#fork) one into another group instead.

## delete

```bash
primitives primitive delete 01m5h39p0vy29h524y1nzc9dh2
```

Deletes the primitive, its data and its snapshots, and prints `deleted <id>` to stderr. This can't be undone.

## snapshot

```bash
primitives primitive snapshot 01m5h39p0vy29h524y1nzc9dh2 --label before-deploy
```

| Option | Description |
| --- | --- |
| `--label <LABEL>` | A name to restore or fork by. Optional |

```json
{
  "id": "01m5h39p1dxjqcq24fe4xdtztc",
  "name": "before-deploy",
  "created_at": 1792648992813,
  "primitive": "01m5h39p0vy29h524y1nzc9dh2"
}
```

## snapshots

```bash
primitives primitive snapshots 01m5h39p0vy29h524y1nzc9dh2
```

Prints the primitive's snapshots, newest first, in the same shape as `snapshot`.

## restore

```bash
primitives primitive restore 01m5h39p0vy29h524y1nzc9dh2 before-deploy
```

Replaces the primitive's data with the snapshot's, by label or snapshot id, and prints the snapshot. The primitive keeps its id. Take a snapshot first if you may want the current state back.

## fork

```bash
primitives primitive fork 01m5h39p0vy29h524y1nzc9dh2 --name orders-try
```

| Option | Description |
| --- | --- |
| `--name <NAME>` | Name of the copy. Defaults to `<name>-fork-<6 chars>` |
| `--group <GROUP>` | Target group. Defaults to the source's. It must exist |
| `--snapshot <SNAPSHOT>` | Fork this snapshot, by label or id, instead of the live data |

Prints the copy, with a new id and `forked_from` pointing at the source:

```json
{
  "id": "01m5h39p1thkjt8ka9bpm7z8ej",
  "group": "agent-42",
  "type": "db",
  "name": "orders-try",
  "created_at": 1792648992826,
  "paused": false,
  "size_bytes": 0,
  "forked_from": {
    "id": "01m5h39p0vy29h524y1nzc9dh2",
    "group": "agent-42",
    "type": "db",
    "name": "orders",
    "snapshot": null
  }
}
```

See [Fork and snapshot primitives](/docs/guides/forking) for how each type forks.

## pause and resume

```bash
primitives primitive pause 01m5h39p0vy29h524y1nzc9dh2
primitives primitive resume 01m5h39p0vy29h524y1nzc9dh2
```

While paused, every data operation on the primitive fails with `paused` (`423` over REST). Info, snapshots, restore, fork and resume still work. Both print the primitive with its new `paused` value. Pausing survives restarts.