# Drawings

Sketch free-form diagrams with Excalidraw, in Markdown notes that the Obsidian Excalidraw plugin can open too.

A drawing is a free-form whiteboard made with Excalidraw: shapes, arrows, a pen, text and images. Each drawing is a note named `<name>.excalidraw.md`, written so that the Obsidian Excalidraw plugin opens it too.

## Create a drawing

1. In the app, choose **New Drawing**.
2. Or run the command from the CLI. It prints the path of the new drawing.

```bash
loam --vault ~/Notes excalidraw.new folder=Drawings title=Kickoff
```

## Read what a drawing says

Search and agents read the text of a drawing and the links of its shapes. Loam writes both into the note on every save.

```bash
loam --vault ~/Notes excalidraw.list
loam --vault ~/Notes excalidraw.read path=Drawings/Kickoff.excalidraw.md
```

`excalidraw.read` returns the texts, the shape links, the images and the number of elements.

## Edit a drawing

- Open the `.excalidraw.md` note in the app. The editor is the full Excalidraw, and it works offline.
- Images you paste or drop go to the vault's attachments folder (`Attachments/` by default), with a name that starts with the drawing's name.
- The shape library is shared by every drawing in the vault. It is saved in `.loam/excalidraw/library.excalidrawlib`.
- A plain `.excalidraw` file from excalidraw.com opens in the same editor, and is saved as it came.

> **Warning:** An edit made less than 400 ms before Cmd+Q can be lost.

## Commands

| Command | Arguments | What it does |
| --- | --- | --- |
| excalidraw.new | folder (default Inbox), title (default Drawing) | Creates an empty drawing and returns its path. |
| excalidraw.list | none | Lists every drawing: `.excalidraw` files and notes flagged as Excalidraw. |
| excalidraw.read | path | Returns the texts, shape links, images and element count. |

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