Skip to main content
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.

Install

Configure

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

Fields

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.
string
required
secret
Trello API key.
string
required
secret
Trello API token.
string
Only this workspace and its boards are listed or readable. Unset shows every workspace of the token’s member.
string[]
Only these boards are listed or readable. Unset shows every open board of the shown workspaces.
string
default:"'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 CLI needs write. Keep the token secret: with the key it reaches the whole account.

Layout

  • 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 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.
  • 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.
  • 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 reads every file instead.

VFS.md

The VFS.md an agent reads with Trello mounted at /<path>.
Virtual FilesystemVFS Layout/<path>
  • 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 VFSUnix commands work on each path as on a local filesystem, as far as the path supports them:Limitations of Unix Commands for VFSWhere a path differs from a local filesystem:Run man <cmd> or <cmd> --help for one command’s usage.