Dokumentacja dla programistów

mcli - interfejs wiersza poleceń do monday.com GraphQL API

Aktualizacja 2026-09-08

MCLI to interfejs wiersza poleceń do monday.com GraphQL API. Jest pojedynczym, samodzielnym plikiem binarnym bez zależności, zaprojektowanym zarówno dla operatorów, jak i agentów LLM.

Kod źródłowy i wydania: github.com/mondaycom/mcli

Najważniejsze możliwości

Domyślnie JSON - wszystkie dane wyjściowe mają postać strukturalnego JSON-u (użyj --pretty, aby uzyskać czytelne dla człowieka formatowanie)
Pojedynczy plik binarny - bez zależności środowiska uruchomieniowego; zbuduj raz, wdrażaj wszędzie
Przystosowane do LLM - ścieżka odczytu nie wyświetla interaktywnych monitów; narzędzie opisuje samo siebie za pomocą mcli skill
Warstwa semantyczna - zapisuj zapytania i mutacje pod nazwami zrozumiałymi dla danej domeny, aby utworzyć biznesowe API działające na tablicach
Dynamiczne API - wykonuj dowolne operacje monday.com GraphQL za pomocą mcli api bez pisania zapytań GraphQL
Alternatywny dostęp - używaj surowych poleceń mcli query / mcli mutation do wszystkiego, czego nie obsługują polecenia CLI
Webhooki i demon - proces działający w tle, który odbiera webhooki i odpytuje o zdarzenia
Uwierzytelnianie - token jest bezpiecznie przechowywany w pęku kluczy systemu operacyjnego (macOS Keychain, Linux Secret Service)

Instalacja

Wymaga Go 1.26+.

# From source (recommended)
go install github.com/mondaycom/mcli/cmd/mcli@latest

# Or clone and build locally
git clone https://github.com/mondaycom/mcli.git
cd mcli
make build    # → bin/mcli

Gotowe pliki binarne dla macOS i Linux są też dostępne na stronie Releases.

Po użyciu go install upewnij się, że $(go env GOPATH)/bin znajduje się w zmiennej PATH.

Szybki start

# Authenticate (one-time, stores in OS keychain)
mcli auth login --token <your-monday-api-token>

# Verify
mcli me

# List your boards
mcli board list

# Get board structure (add --items for the first page of items with column values)
mcli board get 9832181507
mcli board get 9832181507 --items --items-limit 50

# List items with decoded column values (add --subitems to include each item's subitems)
mcli item list --board 9832181507
mcli item list --board 9832181507 --subitems

# Create an item with typed column shorthands
mcli item create --board 9832181507 --name "Ship feature" \
  --status "Working on it" --due 2026-06-01

# Or with raw column JSON, for any column type
mcli item create --board 9832181507 --name "Ship feature" \
  --col 'status={"label":"Working on it"}' \
  --col 'due_date={"date":"2026-06-01"}'

# Create or update many items in one command (rate-limit friendly)
echo '[{"name":"Ship v1","status":"Done"},{"name":"Write docs","due":"2026-06-10"}]' \
  | mcli item create --board 9832181507 -

# Run a raw GraphQL query
mcli query 'query { me { id name } }'

Opis poleceń

Uwierzytelnianie:

mcli auth login/logout/status

Użytkownik:

mcli me - informacje o bieżącym użytkowniku (id, imię i nazwisko, e-mail, konto, zespoły)

Wyszukiwanie:

mcli search <query> [-t boards|items|docs] [--limit N] - wyszukiwanie w różnych typach obiektów

Obszary robocze i organizacja:

mcli workspace list/get/create/update/delete
mcli folder list/create/rename/delete

Tablice:

mcli board list/get/create/rename/archive/delete
mcli board group list/create/rename/archive/delete
mcli board column list/create/rename/describe/delete

Elementy:

mcli item list/get/create/update/move/archive/delete
mcli item create/update ... --status/--due/--date/--number/--text/--checkbox - skróty typowanych wartości kolumn
mcli item create/update --board <id> - - zapis zbiorczy (wiersze ze standardowego wejścia)
mcli item find --board <id> --column <col> --value <text> - wyszukiwanie według wartości kolumny
mcli item post-update <id> --body <text> - opublikowanie komentarza
mcli item get-updates <id> [--limit N] - odczyt komentarzy i aktualizacji
mcli item description <id> [--set <md>|--set-file <path>] - odczyt lub zapis opisu

Dokumenty:

mcli doc read <id> - eksport dokumentu w formacie Markdown
mcli doc write <id> --content <md> - zastąpienie treści dokumentu

Dynamiczne API:

mcli api list [--type query|mutation] - przeglądanie około 250 operacji API ze schematu
mcli api describe <operation|type> - sprawdzanie sygnatury i typów argumentów
mcli api <operation> [--arg k=v]... - wykonywanie dowolnej operacji; argumenty JSON są automatycznie konwertowane do odpowiednich typów

Schemat:

mcli schema status - sprawdzenie, który schemat jest używany i jak dawno został pobrany
mcli schema refresh - pobranie aktualnego schematu przy użyciu tokenu i zapisanie go w pamięci podręcznej

GraphQL (alternatywny dostęp):

mcli query '<graphql>' - wykonywanie surowych zapytań (wpisanych bezpośrednio, odczytanych z pliku lub ze standardowego wejścia)
mcli mutation '<graphql>' - wykonywanie surowych mutacji
mcli query save/list/run/delete - zarządzanie zapisanymi zapytaniami
mcli mutation save/list/run/delete - zarządzanie zapisanymi mutacjami

Webhooki i zdarzenia:

mcli daemon start/stop/status - odbiornik webhooków działający w tle
mcli webhook create/list/delete/events - zarządzanie rejestracją webhooków
mcli notification list/count/ack - odpytanie o zdarzenia webhooków

Konfiguracja:

mcli config set <key> <value> / mcli config get <key>

Narzędzia:

mcli skill - wyświetlenie dokumentu opisującego możliwości dla LLM
mcli version - wyświetlenie wersji

Uruchom mcli <command> --help, aby zobaczyć flagi i szczegółowe informacje o dowolnym poleceniu.

Warstwa semantyczna dla agentów LLM

Zapisuj wielokrotnego użytku zapytania i mutacje jako operacje z nazwami charakterystycznymi dla danej domeny. Dzięki temu modele LLM mogą operować na pojęciach biznesowych zamiast na identyfikatorach tablic i kolumn.

Schemat działania

Skonfiguruj tablice i kolumny (jednorazowo)
Zapisz zapytania i mutacje pod nazwami zrozumiałymi dla danej domeny, które uwzględniają strukturę tablic
Agenci wywołują mcli query run <name> / mcli mutation run <name>, przekazując zmienne biznesowe

Przykład

Zapisz zapytanie, które pobiera produkty z określonej tablicy:

mcli query save list_products --query 'query($boardId: ID!) {
  boards(ids: [$boardId]) {
    items_page(limit: 100) {
      items { id name column_values { id text } }
    }
  }
}'

Uruchom je, przekazując zmienne:

mcli query run list_products --var boardId=9832181507

Agenci nie muszą znać identyfikatorów tablic ani kolumn - wywołują operacje związane z daną domeną:

mcli query run list_products --var boardId=products_board
mcli mutation run create_order --var board=orders_board --var name="ORD-99" \
  --var cols='{"customer":"Acme Corp","status":{"label":"Draft"}}'
mcli mutation run update_order_status --var board=orders_board --var item=789 \
  --var cols='{"status":{"label":"Ordered"}}'

Demo e-commerce: produkty, zapasy i zamówienia

To demo pokazuje, jak agent LLM (lub człowiek) może używać uniwersalnych poleceń mcli, aby:

Tworzyć tablice z kolumnami określonych typów
Definiować warstwę semantyczną, czyli zapisane zapytania i mutacje z nazwami charakterystycznymi dla danej domeny biznesowej
Dodawać dane za pomocą ustrukturyzowanych poleceń dotyczących elementów
Składać zamówienia, korzystając wyłącznie z warstwy semantycznej (bez identyfikatorów tablic w „logice biznesowej”)

Wymagania wstępne

mcli auth login (lub ustawiona zmienna MONDAY_API_TOKEN)
jq w ścieżce PATH
Uruchom całe demo: ./examples/ecommerce-demo.sh w repozytorium mcli

Etap 1: Utwórz tablice

mcli board create --name "Products"  --kind public --empty   # → {"id":"..."}
mcli board create --name "Inventory" --kind public --empty
mcli board create --name "Orders"    --kind public --empty

Każda tablica jest początkowo pusta (nie zawiera domyślnych kolumn ani elementów).

Etap 2: Zdefiniuj kolumny

Produkty - nazwa elementu jest nazwą produktu; dodaj kolumny SKU, Description i Price:

mcli board column create --board $PRODUCTS_BOARD --title "SKU"         --type text
mcli board column create --board $PRODUCTS_BOARD --title "Description" --type long_text
mcli board column create --board $PRODUCTS_BOARD --title "Price"       --type numbers

Zapasy - nazwa elementu to SKU, co ułatwia szybkie wyszukiwanie:

mcli board column create --board $INVENTORY_BOARD --title "SKU"      --type text
mcli board column create --board $INVENTORY_BOARD --title "Quantity"  --type numbers

Zamówienia - nazwa elementu to identyfikator zamówienia; podelementy to pozycje zamówienia:

mcli board column create --board $ORDERS_BOARD --title "Customer" --type text
mcli board column create --board $ORDERS_BOARD --title "Status"   --type status \
  --defaults '{"labels":{"0":"Draft","1":"Ordered","2":"Shipped","3":"Delivered"}}'

Etap 3: Warstwa semantyczna

Zapisane zapytania i mutacje nadają operacjom nazwy zrozumiałe w kontekście biznesowym. LLM może wywołać mcli mutation run create_order --var ... bez znajomości GraphQL:

Zapytania

Nazwa	Zastosowanie
`list_products`	Wszystkie produkty wraz z wartościami kolumn
`get_inventory`	Pełny stan zapasów
`list_orders`	Zamówienia wraz z podelementami opisującymi ich pozycje
`get_order`	Szczegóły pojedynczego zamówienia według identyfikatora elementu

mcli query save list_products --query \
  'query($boardId: ID!) { boards(ids: [$boardId]) { items_page(limit:100) { items { id name column_values { id text value } } } } }'

Mutacje

Nazwa	Zastosowanie
`create_product`	Dodanie produktu do katalogu
`update_inventory`	Zmiana ilości towaru w zapasie
`create_order`	Utworzenie nowego zamówienia (początkowo w statusie Draft)
`add_order_line`	Dodanie pozycji zamówienia jako podelementu
`update_order_status`	Zmiana statusu zamówienia

mcli mutation save create_order --query \
  'mutation($board: ID!, $name: String!, $cols: JSON!) { create_item(board_id: $board, item_name: $name, column_values: $cols) { id } }'

Etap 4: Dodaj dane początkowe

Użyj ustrukturyzowanego polecenia tworzenia elementów (wygodniejszego podczas konfiguracji):

mcli item create --board $PRODUCTS_BOARD --name "Widget Pro" \
  --col "$PROD_SKU"='"WGT-001"' \
  --col "$PROD_PRICE"='"29.99"'

Możesz też użyć warstwy semantycznej:

mcli mutation run create_product \
  --var board=$PRODUCTS_BOARD \
  --var name="Widget Pro" \
  --var cols='{"sku":"WGT-001","price":"29.99"}'

Etap 5: Złóż zamówienie

Właśnie tutaj warstwa semantyczna pokazuje swoje zalety - agent przekazuje naturalny JSON w --var, a mcli automatycznie zajmuje się kodowaniem. Skalar JSON monday.com wymaga przesłania w formie ciągu znaków zawierającego JSON, ale mcli rozpoznaje zmienne zadeklarowane w zapytaniu jako JSON i przeprowadza ponowne kodowanie w sposób niewidoczny dla użytkownika. Nie trzeba stosować podwójnego escapowania.

# 1. Create order in Draft status
mcli mutation run create_order \
  --var board=$ORDERS_BOARD \
  --var name="ORD-1001" \
  --var cols='{"customer":"Acme Corp","status":{"label":"Draft"}}'

# 2. Add line items
mcli mutation run add_order_line \
  --var parent=$ORDER_ID \
  --var name="Widget Pro x2" \
  --var cols='{}'

mcli mutation run add_order_line \
  --var parent=$ORDER_ID \
  --var name="Doohickey x5" \
  --var cols='{}'

# 3. Confirm the order
mcli mutation run update_order_status \
  --var board=$ORDERS_BOARD \
  --var item=$ORDER_ID \
  --var cols='{"status":{"label":"Ordered"}}'

Etap 6: Sprawdź wynik

mcli query run list_products --var boardId=$PRODUCTS_BOARD --pretty
mcli query run get_order --var itemId="[$ORDER_ID]" --pretty

Najważniejsze informacje

Uniwersalne polecenia (board create, item create) obsługują konfigurację
Zapisane zapytania i mutacje tworzą warstwę API dostosowaną do danej domeny
Konwersja JSON-u - zmienne zadeklarowane w zapytaniu jako JSON są automatycznie konwertowane do ciągu znaków, więc --var cols='{"key":"val"}' działa bez dodatkowego kodowania
Agenci LLM mogą wykonywać wszystkie operacje za pomocą mcli mutation run <name> / mcli query run <name> bez znajomości szczegółów działania monday.com ani niuansów formatu przesyłanych danych
Warstwa semantyczna jest lokalna dla projektu (katalog .mcli/) i może być śledzona w systemie kontroli wersji

Wartości kolumn

Odczyt

Wartości kolumn są automatycznie dekodowane do czytelnej dla człowieka postaci (etykiety statusu stają się ciągami znaków, daty przyjmują format ISO itd.).

Zapis za pomocą skrótów typowanych

W przypadku często używanych typów kolumn skorzystaj z typowanych flag. Każdy skrót dotyczy jedynej kolumny danego typu na tablicy:

Flaga	Typ kolumny	Akceptowane wartości
`--status <label>`	status	etykieta skonfigurowana w kolumnie
`--date` / `--due`	date	`2026-05-10`, `2026-05-10T14:30` lub RFC3339
`--number <n>`	numbers	dowolna liczba; pusty ciąg znaków czyści wartość
`--text <s>`	text	dowolny ciąg znaków; pusty ciąg znaków czyści wartość
`--checkbox <b>`	checkbox	true/false, yes/no, 1/0

mcli item create --board 123 --name "Task" --status Done --due 2026-05-10 --number 3
mcli item update 456 --board 123 --status "Working on it"

Jeśli tablica nie ma kolumny danego typu albo ma ich więcej niż jedną, skrót zwróci błąd i wyświetli pasujące kolumny. Skróty nie są dostępne z flagą --parent (podelementy) - w takim przypadku użyj --col.

Zapis surowego JSON-u wartości kolumn

Przekaż surowy JSON wartości kolumn monday.com za pomocą --col <id>=<json> dla dowolnego typu kolumny:

mcli item create --board 123 --name "Task" \
  --col 'status={"label":"Done"}' \
  --col 'date={"date":"2026-05-10"}' \
  --col 'people={"personsAndTeams":[{"id":123,"kind":"person"}]}'

Użyj mcli board column list --board <id>, aby wyświetlić identyfikatory i typy kolumn oraz ich ustawienia.

Dynamiczne API (`mcli api`)

Możesz korzystać z każdej operacji API monday.com bez pisania zapytań GraphQL. Schemat (około 250 operacji) jest osadzony w pliku binarnym i można go odświeżyć dla określonej wersji API.

# Browse all operations
mcli api list
mcli api list --type mutation

# Inspect an operation or type
mcli api describe create_notification
mcli api describe Board

# Execute any operation - JSON arguments are auto-coerced
mcli api create_notification \
  --arg user_id=12345 --arg text="Hello" \
  --arg target_id=67890 --arg target_type=Project

# Preview generated GraphQL without executing
mcli api boards --arg limit=5 --dry-run

Dbaj o aktualność schematu:

mcli schema status
mcli schema refresh
mcli schema refresh --api-version 2026-08

Webhooki i demon

mcli zawiera demona działającego w tle, który odbiera webhooki monday.com i przechowuje je w skrzynce odbiorczej, z której agenci mogą pobierać zdarzenia.

Uruchom demona

# Foreground - opens a Cloudflare Quick Tunnel for a public URL
mcli daemon start

# Or supply your own public URL
mcli daemon start --url https://your-server.example.com

Demon:

Odbiera dane webhooków na porcie HTTP (domyślnie 8420)
Udostępnia gniazdo Unix do komunikacji IPC z poleceniami CLI
Automatycznie otwiera Cloudflare Quick Tunnel (wymaga cloudflared w ścieżce PATH)
Ponownie rejestruje webhooki, gdy zmieni się adres URL tunelu

Zarejestruj webhooki

# Register for item creation events on a board
mcli webhook create --board 9832181507 --event create_item

# List registered webhooks
mcli webhook list

# List supported event types
mcli webhook events

# Remove a webhook
mcli webhook delete <webhook-id>

Odpytuj o powiadomienia

# Check if there are unread events
mcli notification count

# List unread events
mcli notification list --unread

# Filter by board or event type
mcli notification list --board 9832181507 --event change_column_value

# Acknowledge (mark read)
mcli notification ack <event-id>
mcli notification ack --all

Wszystkie polecenia dotyczące powiadomień i webhooków wymagają uruchomionego demona.

Integracja z LLM

mcli został zaprojektowany specjalnie dla agentów LLM.

# Load the skill document into your LLM context
mcli skill

To polecenie wyświetla zwięzły przewodnik zorientowany na konkretne cele. W razie potrzeby LLM może sprawdzić dostępne flagi za pomocą mcli <command> --help.

Uwierzytelnianie

Token jest wybierany na podstawie poniższej kolejności (używane jest pierwsze znalezione źródło):

Flaga --token <t>
Zmienna środowiskowa MONDAY_API_TOKEN
Poświadczenie zapisane w pęku kluczy systemu operacyjnego (mcli auth login)

Poświadczenia są bezpiecznie przechowywane w pęku kluczy systemu operacyjnego (macOS Keychain, Linux Secret Service) albo w pliku zaszyfrowanym za pomocą age. Nigdy nie są przechowywane jako zwykły tekst.

Zmienne środowiskowe (mają pierwszeństwo przed plikiem konfiguracji):

Zmienna	Zastosowanie	Wartość domyślna
`MONDAY_API_TOKEN`	Token API	-
`MONDAY_API_URL`	Punkt końcowy API	`https://api.monday.com/v2`
`MONDAY_API_VERSION`	Nagłówek wersji API	`2026-07`

Licencja

MIT

Mam problem z tym tematem Źródło: developer.monday.com