> ## 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

> Mount Trello boards, lists, and cards as a Mirage filesystem.

`TrelloVFS` exposes a Trello workspace as a tree of boards, lists, and cards.

Setup steps for the API key/token live at [Trello Credentials](https://docs.mirage.strukto.ai/home/setup/trello.md).

## Node

```bash theme={null}
pnpm add @struktoai/mirage-node
```

```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 })
await ws.shell('ls /trello/')
```

## Browser

```bash theme={null}
pnpm add @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,
})
```

## Config

| Field | Description |
| - | - |
| `timeout` 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` required, secret | Trello API key. |
| `apiToken` required, secret | Trello API token. |
| `workspaceId` | Only this workspace and its boards are listed or readable. Unset shows every workspace of the token's member. |
| `boardIds` | Only these boards are listed or readable. Unset shows every open board of the shown workspaces. |
| `baseUrl` default `'https://api.trello.com/1'` | Trello API root; override to point at a fake or proxy. |

Fields marked secret are redacted in snapshots.

## Mount mode

`read`.

For board/list/card layout see the [Python Trello docs](https://docs.mirage.strukto.ai/python/vfs/trello.md).
Reads and writes by ID go through the [trello CLI](https://docs.mirage.strukto.ai/typescript/cli/trello.md),
which takes `workspaceId` and `boardIds` in its own config.

## 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
> ```
>
> * `ls` directories first to discover exact names.
> * To act on boards and cards (list boards, members, lists, labels, cards
>   and comments; create, update, move, assign, label and 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
> ```
>
> - `ls` directories first to discover exact names.
> - To act on boards and cards (list boards, members, lists, labels, cards
>   and comments; create, update, move, assign, label and 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.
> ````

## Integration

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

| Command | On Trello |
| - | - |
| `grep -r`, `rg` | Trello search and the text the listing keeps, for whole words. It can miss recent writes. |

The [Python Trello docs](https://docs.mirage.strukto.ai/python/vfs/trello.md#integration) list when each search answers and what it can miss.


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