trellang

Trello REST client for Erlang/OTP

Build

$ rebar3 compile

Configuration

trellang reads your Trello credentials from the Erlang application environment.

• Required keys:
  • trellang.trello_key
  • trellang.trello_token

Recommended: keep credentials in a non‑committed dev.config and run with ERL_FLAGS. See docs/dev.config.example.

Minimal dev.config example:

[
  {trellang, [
    {trello_key, "..."},
    {trello_token, "..."}
  ]}
].

Run with the config file:

ERL_FLAGS="-config ./dev.config" rebar3 ct

You can also set the values at runtime before the first API call, even after the application is started:

application:set_env(trellang, trello_key, "...").
application:set_env(trellang, trello_token, "...").
{ok, Me} = trello:me().

Run

• Compile: rebar3 compile
• Generate docs: rebar3 ex_doc (output in doc/, git-ignored)

Getting started

See the module docs for trello (ExDoc HTML) for API reference and examples. For CI setup, extended examples, and contributor/test notes, see AGENTS.md.

Examples

Assumes your key/token are provided via dev.config.

How to get your board id:

• Open the board in your browser and copy the 8‑character short link after /b/ in the URL (e.g., abcd1234). Trello accepts this short link wherever a board id is required, or you can resolve the full id via GET /1/boards/{shortLink}?fields=id.

Create and update a card

%% board id (short link or full id)
BoardId = <<"abcd1234">>,

%% pick a list on that board
{ok, Lists} = trello:list_lists(BoardId),
ListId = maps:get(<<"id">>, hd(Lists)),

%% create
{ok, Card} = trello:create_card(ListId, #{name => <<"Hello Trello">>}),
CardId = maps:get(<<"id">>, Card),

%% set desc and due
{ok, _} = trello:set_desc(CardId, <<"Created from Erlang">>),
{ok, _} = trello:set_due(CardId, <<"2031-01-02T03:04:05.000Z">>),

%% add a green label by color
{ok, _} = trello:add_label_by_color(BoardId, CardId, <<"green">>),

%% fetch card
{ok, Card2} = trello:get_card(CardId).

Custom fields (text/date/checkbox)

BoardId = <<"abcd1234">>,
{ok, Lists} = trello:list_lists(BoardId),
ListId = maps:get(<<"id">>, hd(Lists)),
{ok, Fields} = trello:list_custom_fields(BoardId),
TextId = maps:get(<<"id">>, hd([F || F <- Fields, maps:get(<<"type">>, F, <<>>) =:= <<"text">>])),
{ok, Card} = trello:create_card(ListId, #{name => <<"CF demo">>}),
CardId = maps:get(<<"id">>, Card),
{ok, _} = trello:set_custom_field_text(CardId, TextId, <<"hello-cf">>),
{ok, CardCF} = trello:get_card_with_custom_fields(CardId).

Discover lists and dump a board

BoardId = <<"abcd1234">>,
{ok, Lists} = trello:list_lists(BoardId),
{ok, Dump} = trello:dump_board(BoardId, #{}).
%% Dump = #{ board => #{<<"id">> := _, <<"name">> := _},
%%           lists => [ #{<<"id">> := _, <<"name">> := _, <<"cards">> := [#{<<"id">> := _} | _]} | _ ] }