# Collections

Show your notes as a table, a kanban board or a gallery, driven by a .base file that reads the notes' properties.

A collection shows a set of notes as a table, a kanban board or a gallery. It is a `.base` file in the Obsidian Bases format. Its entries are the notes it finds, and its fields are their frontmatter properties.

## Turn a folder into a collection

1. In the app, choose **Turn into Collection** on a folder.
2. Or run the command with the folder name.

```bash
loam --vault ~/Notes collection.create folder=Reading
```

The command writes `Reading/Reading.base`, with a table of the folder's notes. The folder then opens as a collection.

## Add views and fields

A view is a `table`, a `kanban` or `cards` (the gallery). A kanban groups by the first select field. If there is none, it adds a `status` field with To do, In progress and Done.

```bash
loam --vault ~/Notes collection.add-view path=Reading/Reading.base type=kanban name=Board
loam --vault ~/Notes collection.set-property path=Reading/Reading.base property=status type=select options="To do,In progress,Done"
```

Field types are `text`, `number`, `checkbox`, `date`, `url`, `select` and `multiselect`. For a select, `options` sets the values, in order.

## Add an entry

A new entry is a note in the collection's home folder, with the properties its filter asks for. Without a home folder, it goes to the Inbox.

```bash
loam --vault ~/Notes collection.new-entry path=Reading/Reading.base title="Book three" values='{"status":"To do","author":"Cleo"}'
```

## Edit and read from the CLI

Use `collection.edit` to change several things in one call. It takes a JSON array of edits, and keeps the YAML keys Loam does not know.

```bash
loam --vault ~/Notes collection.edit path=Reading/Reading.base edits='[{"addView":{"type":"kanban","name":"Queue"}},{"setGroupBy":{"view":"Queue","groupBy":{"property":"status","descending":false}}}]'
loam --vault ~/Notes collection.entries path=Reading/Reading.base view=Queue
```

## Commands

| Command | Arguments | What it does |
| --- | --- | --- |
| collection.list | none | Lists every collection in the vault. |
| collection.create | folder | Turns a folder into a collection and returns the `.base` path. |
| collection.show | path | Shows the name, home folder, fields and views, as JSON. |
| collection.entries | path, view (optional) | Runs one view: its notes, filtered, sorted and grouped. |
| collection.add-view | path, type (table, kanban or cards), name (optional) | Adds a view to the collection. |
| collection.set-property | path, property; optional type, options, display-name | Sets a field's type and options. |
| collection.new-entry | path; optional title, values (JSON object) | Creates a note that matches the filter, and returns its path. |
| collection.edit | path, edits (JSON array) | Applies edits to the collection's YAML. |

Pass `path` for a `.base` file. To act on a base block inside a note, pass its YAML as `yaml` and the note's path as `host`.

> **Tip:** For AI agents: `loam list` shows the `collection.*` commands with their arguments.