> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mirage.strukto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Trello

> Virtualize Trello boards from Node or the browser.

`TrelloVFS` mounts Trello as read-only JSON files: workspaces, boards, lists,
cards with their comments, members and labels. Set up the API key and token as in [Trello setup](https://docs.mirage.strukto.ai/home/setup/trello.md).

## Install

```bash theme={null}
npm install @struktoai/mirage-node
```

## Configure

```ts theme={null}
import { MountMode, TrelloVFS, Workspace } from '@struktoai/mirage-node'

const trello = new TrelloVFS({
  apiKey: process.env.TRELLO_API_KEY!,
  apiToken: process.env.TRELLO_API_TOKEN!,
})
const ws = new Workspace({ '/trello': trello }, { mode: MountMode.READ })

const result = await ws.shell('tree -L 4 /trello/workspaces')
console.log(result.stdoutText)
await ws.close()
```

`workspaceId` or `boardIds` limits the mount to one workspace or some boards.
`baseUrl` points at a proxy.

### Fields

**timeout** `number` (default: DEFAULT\_TIMEOUT)

Seconds a request may wait to connect, or between two reads of its answer, before it fails; a download that keeps flowing is never cut off.

**apiKey** `string` *required*

Trello API key.

**apiToken** `string` *required*

Trello API token.

**workspaceId** `string`

Only this workspace and its boards are listed or readable. Unset shows every workspace of the token's member.

**boardIds** `string[]`

Only these boards are listed or readable. Unset shows every open board of the shown workspaces.

**baseUrl** `string` (default: '[https://api.trello.com/1](https://api.trello.com/1)')

Trello API root; override to point at a fake or proxy.

Fields marked secret are redacted in snapshots.

## Authentication

The mount needs an API key and a token authorized for it. `scope=read` is
enough for the mount; the [`trello`](https://docs.mirage.strukto.ai/home/setup/cli/trello) CLI needs
`write`. Keep the token secret: with the key it reaches the whole account.

## Layout

```text theme={null}
/trello/
  workspaces/
    Acme_Product__<workspace-id>/
      workspace.json
      boards/
        Sprint_Board__<board-id>/
          board.json
          members/
            Alice_Chen__<member-id>.json
          labels/
            bug__<label-id>.json
          lists/
            Doing__<list-id>/
              list.json
              cards/
                Fix_login_redirect__<card-id>/
                  card.json
                  comments.jsonl
```

* **Names:** every name ends in `__<id>`, so a command can take the id
  without a lookup. The readable part is sanitized, so `ls` the parent to
  find a name.
* **`workspace.json`, `board.json`:** the workspace's and the board's
  metadata.
* **`list.json`:** the list, with fields such as `list_id`, `list_name`,
  `board_id`, `closed` and `pos`.
* **`card.json`:** the card, with fields such as `card_id`, `board_id`,
  `list_id`, `member_ids`, `label_ids`, `due` and `url` that commands take as
  they are.
* **`comments.jsonl`:** the card's comments, one JSON object per line, ordered
  by `created_at`. It is a Mirage format, not a Trello one.
* **Members:** each file carries `member_id` and `username`, ready for
  commands such as `trello card assign`.
* **Labels:** each file carries `label_id`, `label_name`, `color` and
  `board_id`.

## Behavior

* **Read only:** the mount cannot change cards. Use the
  [`trello`](https://docs.mirage.strukto.ai/typescript/cli/trello) CLI to create, move, assign and comment on
  cards; the tree serves the same entities as JSON files. The CLI takes
  `workspaceId` and `boardIds` in its own config, so it covers the boards
  the mount lists only when both are configured alike.
* **Recent writes:** Trello indexes a write some time after it lands, so a
  search can miss a recent change. See Integration.

## Browser

The browser `TrelloVFS` from `@struktoai/mirage-browser` takes the same fields.

```bash theme={null}
npm install @struktoai/mirage-browser
```

```ts theme={null}
import { MountMode, TrelloVFS, Workspace } from '@struktoai/mirage-browser'

const trello = new TrelloVFS({
  apiKey: TRELLO_API_KEY,
  apiToken: TRELLO_API_TOKEN,
})
const ws = new Workspace({ '/trello': trello }, { mode: MountMode.READ })
```

* The key and token reach the page, so authorize the token with `scope=read`.

## Integration

Trello answers this command through its own API, so fewer files are read. See
[Integration](https://docs.mirage.strukto.ai/home/integration/overview.md).

* `grep -rw` and `rg -w`: Trello search runs for each word, and only the cards
  that hold every word are read, where the search names it or the listing
  keeps it. The listing keeps each card's other fields (ids, due date, flags,
  link) and each name or description word the search can miss, such as one
  inside a link; the cards are listed once more, so a change since the last
  listing is still found. Comments and the board's other files are always
  read. Every card is read when the word is a key of the card JSON (`desc`,
  `due`) or a JSON literal, has a digit or only the letters a to f, or when a
  search fails, returns 1,000 cards or finds nothing. `walk_limit: -1` in the
  mount's `"@all"` [command limit](https://docs.mirage.strukto.ai/home/limits.md#command-output) reads every file
  instead.

## VFS.md

The [VFS.md](https://docs.mirage.strukto.ai/home/setup/vfs-md.md) an agent reads with Trello mounted at `/<path>`.

> [tab] Rendered
>
> **Virtual Filesystem**
>
> | Path | Description |
> | - | - |
> | `/<path>` | `trello`, read |
>
> **VFS Layout**
>
> **`/<path>`**
>
> ```text theme={null}
> /<path>
>   workspaces/
>     <workspace-name>__<workspace-id>/
>       workspace.json
>       boards/
>         <board-name>__<board-id>/
>           board.json
>           members/
>             <full-name>__<member-id>.json
>           labels/
>             <label-name>__<label-id>.json
>           lists/
>             <list-name>__<list-id>/
>               list.json
>               cards/
>                 <card-name>__<card-id>/
>                   card.json
>                   comments.jsonl
> ```
>
> * A named segment is `<name>__<id>`; `ls` the parent for exact names.
> * To create, update, move, assign, label or comment on cards, use the
>   `trello` CLI if installed (`trello --help`).
>
> **Supported Unix Commands for VFS**
>
> Unix commands work on each path as on a local filesystem, as far as the path supports them:
>
> | Path | Supported |
> | - | - |
> | `/<path>` | Commands that read files (`ls`, `cat`, `grep`, `find`, `jq` and the rest). `grep -r` and `rg` with `-w` ask `trello` which files may match. |
>
> **Limitations of Unix Commands for VFS**
>
> Where a path differs from a local filesystem:
>
> | Path | Limitations |
> | - | - |
> | `/<path>` | Read only: no command changes files. Without `-w`, `grep -r` and `rg` read every file. `trello` answers only for `workspaces/*/boards/*/lists/*/cards/*/card.json`; `grep -r` and `rg` read every other file. `grep -r`, `find` and `du` stop after 1000 files; a glob matching more, `tar -c`, `cp -r` and `rm -r` are refused. |
>
> Run `man <cmd>` or `<cmd> --help` for one command's usage.

> [tab] Raw
>
> ````markdown theme={null}
> ---
> name: workspace-filesystem
> description: The virtual filesystem layout of this workspace.
> ---
>
> # Virtual Filesystem
>
> | Path | Description |
> | --- | --- |
> | `/<path>` | `trello`, read |
>
> ## VFS Layout
>
> ### `/<path>`
>
> ```text
> /<path>
>   workspaces/
>     <workspace-name>__<workspace-id>/
>       workspace.json
>       boards/
>         <board-name>__<board-id>/
>           board.json
>           members/
>             <full-name>__<member-id>.json
>           labels/
>             <label-name>__<label-id>.json
>           lists/
>             <list-name>__<list-id>/
>               list.json
>               cards/
>                 <card-name>__<card-id>/
>                   card.json
>                   comments.jsonl
> ```
>
> - A named segment is `<name>__<id>`; `ls` the parent for exact names.
> - To create, update, move, assign, label or comment on cards, use the
>   `trello` CLI if installed (`trello --help`).
>
> ## Supported Unix Commands for VFS
>
> Unix commands work on each path as on a local filesystem, as far as the path supports them:
>
> | Path | Supported |
> | --- | --- |
> | `/<path>` | Commands that read files (`ls`, `cat`, `grep`, `find`, `jq` and the rest). `grep -r` and `rg` with `-w` ask `trello` which files may match. |
>
> ## Limitations of Unix Commands for VFS
>
> Where a path differs from a local filesystem:
>
> | Path | Limitations |
> | --- | --- |
> | `/<path>` | Read only: no command changes files. Without `-w`, `grep -r` and `rg` read every file. `trello` answers only for `workspaces/*/boards/*/lists/*/cards/*/card.json`; `grep -r` and `rg` read every other file. `grep -r`, `find` and `du` stop after 1000 files; a glob matching more, `tar -c`, `cp -r` and `rm -r` are refused. |
>
> Run `man <cmd>` or `<cmd> --help` for one command's usage.
> ````


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.