Trello

The Trello VFS exposes workspaces, boards, lists, cards, members, and labels as a virtual filesystem mounted at some prefix such as /trello/. For API key setup, see Trello Setup.

Config

import os

from mirage import MountMode, Workspace
from mirage.vfs.trello import TrelloConfig, TrelloVFS

config = TrelloConfig(
    api_key=os.environ["TRELLO_API_KEY"],
    api_token=os.environ["TRELLO_API_TOKEN"],
)
vfs = TrelloVFS(config=config)
ws = Workspace({"/trello": vfs}, mode=MountMode.READ)

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

Fields marked secret are redacted in snapshots.

VFS.md

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

Rendered
Raw

Virtual Filesystem

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

`/<path>` layout

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

## `/<path>` layout

```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
  Always 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.

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

Example:

/trello/
  workspaces/
    engineering__abc123def/
      workspace.json
      boards/
        product-roadmap__brd_001/
          board.json
          members/
            alice__mem_001.json
            bob__mem_002.json
          labels/
            bug__lbl_001.json
            feature__lbl_002.json
          lists/
            backlog__lst_001/
              list.json
              cards/
                fix-login__crd_001/
                  card.json
                  comments.jsonl
                add-search__crd_002/
                  card.json
                  comments.jsonl
            in-progress__lst_002/
              list.json
              cards/
                ...

Directory and file names embed the Trello ID after __ so that trello CLI commands can take an ID without extra lookups.

Workspaces

Each workspace directory is named:

<workspace-name>__<workspace-id>

Inside the workspace directory:

workspace.json is the normalized workspace metadata
boards/ contains one directory per board

Boards

Each board directory is named:

<board-name>__<board-id>

Inside the board directory:

board.json is the normalized board metadata
members/ contains one JSON file per board member
labels/ contains one JSON file per board label
lists/ contains one directory per list

Lists

Each list directory is named:

<list-name>__<list-id>

Each list directory contains:

list.json — normalized list metadata with fields such as list_id, list_name, board_id, closed, pos
cards/ contains one directory per card

Cards

Each card directory is named:

<card-name>__<card-id>

Each card directory contains:

card.json — normalized card metadata with command-aligned fields such as card_id, board_id, list_id, member_ids, label_ids, due, url
comments.jsonl — normalized comment stream ordered by created_at

comments.jsonl is a Mirage representation chosen for shell-friendly workflows. It is not a native Trello file format.

Members

Each member file is named:

<full-name>__<member-id>.json

Member JSON includes command-aligned identifiers such as member_id and username so the value can be reused directly in commands like trello card assign.

Labels

Each label file is named:

<label-name>__<label-id>.json

Label JSON includes label_id, label_name, color, and board_id.

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.

grep -rw and rg -w ask Trello search for each word and read only the cards that hold every word, where the search names it or the listing keeps it. The listing keeps the 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 for this, 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, which an id can hold, and when a search fails, returns 1,000 cards or finds nothing. walk_limit: -1 in the mount’s "@all" command limit reads every file instead, since Trello indexes a write some time after it lands.

Cache

Uses IndexCacheStore (same as other mounts).

Example

See examples/python/vfs/trello/trello.py for the full working example.

# List workspaces
ls /trello/workspaces/

# Read workspace metadata
cat /trello/workspaces/engineering__abc123/workspace.json

# List boards
ls /trello/workspaces/engineering__abc123/boards/

# Read board metadata
cat /trello/workspaces/engineering__abc123/boards/roadmap__brd_001/board.json

# List lists
ls /trello/workspaces/engineering__abc123/boards/roadmap__brd_001/lists/

# Read a card
cat /trello/workspaces/engineering__abc123/boards/roadmap__brd_001/lists/backlog__lst_001/cards/fix-login__crd_001/card.json

# Read card comments
cat /trello/workspaces/engineering__abc123/boards/roadmap__brd_001/lists/backlog__lst_001/cards/fix-login__crd_001/comments.jsonl

# Extract card ID with jq
cat /trello/workspaces/engineering__abc123/boards/roadmap__brd_001/lists/backlog__lst_001/cards/fix-login__crd_001/card.json \
  | jq '.card_id'

# Read last 5 comments
tail -n 5 /trello/workspaces/engineering__abc123/boards/roadmap__brd_001/lists/backlog__lst_001/cards/fix-login__crd_001/comments.jsonl

# List members
ls /trello/workspaces/engineering__abc123/boards/roadmap__brd_001/members/

# List labels
ls /trello/workspaces/engineering__abc123/boards/roadmap__brd_001/labels/

# Tree view
tree -L 2 /trello/workspaces/

Finding IDs

IDs are embedded in directory and file names after __:

# Workspace ID -- embedded in directory name
ls /trello/workspaces/
# -> engineering__abc123   <- workspace_id = abc123

# Board ID -- embedded in board directory name
ls /trello/workspaces/engineering__abc123/boards/
# -> roadmap__brd_001   <- board_id = brd_001

# List ID -- embedded in list directory name
ls /trello/workspaces/engineering__abc123/boards/roadmap__brd_001/lists/
# -> backlog__lst_001   <- list_id = lst_001

# Card ID -- embedded in card directory name
ls /trello/workspaces/engineering__abc123/boards/roadmap__brd_001/lists/backlog__lst_001/cards/
# -> fix-login__crd_001   <- card_id = crd_001

# Member ID -- embedded in member file name
ls /trello/workspaces/engineering__abc123/boards/roadmap__brd_001/members/
# -> alice__mem_001.json   <- member_id = mem_001

# Label ID -- embedded in label file name
ls /trello/workspaces/engineering__abc123/boards/roadmap__brd_001/labels/
# -> bug__lbl_001.json   <- label_id = lbl_001

# Use stat for structured metadata
stat /trello/workspaces/engineering__abc123/boards/roadmap__brd_001/lists/backlog__lst_001/cards/fix-login__crd_001/card.json

# Extract fields with jq
cat /trello/workspaces/engineering__abc123/boards/roadmap__brd_001/lists/backlog__lst_001/cards/fix-login__crd_001/card.json \
  | jq '{card_id, board_id, list_id, member_ids, label_ids}'

Shell Commands

Standard commands available on the mounted Trello tree:

Command	Notes
`ls`	List workspaces, boards, lists, cards
`cat`	Read .json metadata or .jsonl comments
`head` / `tail`	First/last N lines
`grep` / `rg`	Pattern search (file or directory level)
`jq`	Query JSON fields
`wc`	Line/word/byte counts
`stat`	File metadata (name, size, type)
`find`	Recursive search with `-name`, `-maxdepth`
`tree`	Directory tree view
`basename`	Extract file name from path
`dirname`	Extract directory from path
`realpath`	Resolve path to absolute form

Acting on Trello

Reads and writes on Trello entities by ID (boards, members, lists, labels, cards, comments) go through the trello CLI when installed; the mounted tree serves the same entities as normalized JSON files. The CLI takes workspace_id and board_ids in its own config, so it covers the boards the mount lists only when both are configured alike.

Getting Started

Access

AI Agents

VFS

CLIs

Runtimes

Config

VFS.md

Virtual Filesystem

`/<path>` layout

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Workspaces

Boards

Lists

Cards

Members

Labels

Integration

Cache

Example

Finding IDs

Shell Commands

Acting on Trello

​Config

​VFS.md

​Virtual Filesystem

​/<path> layout

​Supported Unix Commands for VFS

​Limitations of Unix Commands for VFS

​Workspaces

​Boards

​Lists

​Cards

​Members

​Labels

​Integration

​Cache

​Example

​Finding IDs

​Shell Commands

​Acting on Trello

Config

VFS.md

Virtual Filesystem

`/<path>` layout

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Workspaces

Boards

Lists

Cards

Members

Labels

Integration

Cache

Example

Finding IDs

Shell Commands

Acting on Trello