# Boards, tags and diagrams (https://docs.vitrinka.ai/dev/cli/boards)



## Turn a set into a board [#create]

A screenshots push already lands on its journey board, `<project>-<branch>-<key>`, and prints that URL; a document push lands as a doc card at `/a/<id>`. Reach for `board create` only when you want another slug or title, or a branching `--journey` tree from the same set:

```bash
vitrinka board create --title "Checkout — pass 3"
```

| Flag                   | What it does                                                           |
| ---------------------- | ---------------------------------------------------------------------- |
| `--title` / `--btitle` | Board title.                                                           |
| `--slug`               | Board slug. Defaults to `<project>-<branch>-<key>`, the set's address. |
| `--journey`            | Build a branching journey tree instead of a flat flow board.           |
| `--actor`              | `X-Board-Actor` attribution. Defaults to the stored operator.          |
| `--root`               | Capture root. Default `.vitrinka/screenshots`.                         |

## Find a board [#find]

`list` filters by the three axes a board is filed under — project, subgroup and tag — plus its type.

```bash
vitrinka board list --project myapp --type journeys
vitrinka board view checkout-pass-3
```

| Flag         | What it does                                                 |
| ------------ | ------------------------------------------------------------ |
| `--project`  | Only boards owned by this project.                           |
| `--subgroup` | Only boards in this sidebar subgroup.                        |
| `--type`     | Only boards of this type — `brainstorm`, `docs`, `journeys`… |
| `--tags`     | Comma-separated. Prefix one with `-` to exclude it.          |
| `--match`    | How to combine tags: `all` (default) or `any`.               |
| `--archived` | Include archived boards.                                     |

## Open a board [#open]

`board open` opens the capture root's live board when a set exists, otherwise vitrinka home. The QR mode is for getting a board onto a tablet without typing a URL.

```bash
vitrinka board open
vitrinka board open --qr      # scan with an iPad, annotate with the Pencil
vitrinka board open --print   # just print the URL
```

| Flag        | What it does                                                |
| ----------- | ----------------------------------------------------------- |
| `--qr`      | Render the URL as a terminal QR code instead of opening it. |
| `--print`   | Print the URL only.                                         |
| `--browser` | Force the https URL even when Vitrinka.app is installed.    |

## Open in the desktop app [#edit]

`board edit` focuses the resident Vitrinka.app on a file or project, and records the repo in the project registry so the app's project list stays current. It is macOS only and needs the Vitrinka desktop app, which ships separately from the CLI; elsewhere, or without it, you get the deep link printed.

```bash
vitrinka board edit .
vitrinka board edit --print   # print the deep link only
```

## Put things on a board [#put]

`upload` puts arbitrary files on as cards. `dump` lands a whole directory of captures in one go — it creates the board when missing, uploads every image in name order and, when the directory carries a render-audit `audit.json`, composes one ledger card from it. `import-chat` publishes a chat transcript — an eve run or NDJSON — as a chat card.

```bash
vitrinka board upload ./report.html ./notes.md --board checkout-pass-3
vitrinka board dump ./captures/round-3 --board checkout-round-3
vitrinka board import-chat run.ndjson --board checkout-pass-3 --redact
```

| `dump` flag          |                                                                    |
| -------------------- | ------------------------------------------------------------------ |
| `--board`            | Target slug. Omitted: `render-audit-<date>-<label>-<sha7>`.        |
| `--project`          | Owning project when the board is created (default `benchmarking`). |
| `--workspace`        | Write into this workspace instead of the bound one.                |
| `--label`, `--title` | Round label (default: the directory name) and board title.         |

| `upload` flag         |                                                                                          |
| --------------------- | ---------------------------------------------------------------------------------------- |
| `--board`             | Target slug. Required.                                                                   |
| `--section`           | Land inside the named section frame.                                                     |
| `--anchor` · `--side` | Dock beside a card id, to its `right` or `below`.                                        |
| `--create-section`    | Create `--section` as a new frame even when its name is a near match of an existing one. |

`board cards rm` takes cards off again — softly: they go to the board's Trash tab, where the operator can restore them. Ids take comma lists and ranges. Your own cards go straight to trash, up to 25 per call and 30% of the board; anyone else's cards, or a bigger batch, need `--why` with a reason of 20 characters or more.

```bash
vitrinka board cards rm checkout-pass-3 362-370
vitrinka board cards rm checkout-pass-3 412,415 --why "pass-2 duplicates, superseded by the pass-3 shots"
```

## Share with outside people [#share]

`share` mints a capability link on the public share origin. The URL is the credential: whoever holds it opens the board without an account. Every link shares the whole board. `--card` only chooses where it opens: on that element as a document rather than on the canvas, which is how you share an artifact from its `/a/<id>` view. The recipient can still switch to the board and read every card on it, so keep artifacts for outside eyes on a board with nothing private beside them. Personal boards never mint.

```bash
vitrinka board share checkout-pass-3 --mode annotate --expires 7d
vitrinka board share docs-board --card 336
```

| Flag        | What it does                                                                        |
| ----------- | ----------------------------------------------------------------------------------- |
| `--mode`    | `view` (default) or `annotate`, which lets link holders leave feedback.             |
| `--expires` | `24h`, `7d`, `30d` (default) or `never`.                                            |
| `--card`    | Element id the link opens on, as a document. The link still grants the whole board. |

## Tags [#tags]

The third axis beside project and subgroup.

```bash
vitrinka tag add checkout-pass-3 regression payments
vitrinka tag list
vitrinka tag remove checkout-pass-3 regression
```

## Diagrams [#diagrams]

`import` parses a file you already maintain — OpenAPI, SQL DDL or docker-compose — into a diagram; `schema push` introspects a live Postgres locally and pushes what it finds. Both take `--section` to land inside a frame and `--rev` for the source revision the card's ↻ micro-label shows.

```bash
vitrinka board diagram import docker-compose.yml --board checkout-pass-3
vitrinka board diagram schema push --db postgres://localhost/app --board checkout-pass-3   # psql runs locally; the URL never leaves the machine
```