Trello

TrelloVFS exposes a Trello workspace as a tree of boards, lists, and cards. Setup steps for the API key/token live at Trello Credentials.

Node

pnpm add @struktoai/mirage-node

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

pnpm add @struktoai/mirage-browser

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. Reads and writes by ID go through the trello CLI, which takes workspaceId and boardIds in its own config.

VFS.md

The VFS.md an agent reads with Trello mounted at /<path>.

Rendered
Raw

Virtual Filesystem

Path	Description
`/<path>`	`trello`, read

VFS Layout

`/<path>`

/<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.

---
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 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 list when each search answers and what it can miss.

Getting Started

Access

AI Agents

VFS

CLIs

Runtimes

Node

Browser

Config

Mount mode

VFS.md

Virtual Filesystem

VFS Layout

`/<path>`

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Integration

​Node

​Browser

​Config

​Mount mode

​VFS.md

​Virtual Filesystem

​VFS Layout

/<path>

​Supported Unix Commands for VFS

​Limitations of Unix Commands for VFS

​Integration

Node

Browser

Config

Mount mode

VFS.md

Virtual Filesystem

VFS Layout

`/<path>`

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Integration