mcli — monday.com GraphQL CLI

MCLI is a command-line interface to monday.com's GraphQL API. It's a single static binary with no dependencies, designed for both human operators and LLM agents.

Key capabilities

JSON by default — all output is structured JSON (use --pretty for human-readable formatting)
Single binary — no runtime dependencies; build once, deploy anywhere
LLM-native — no interactive prompts on the read path; self-describing via mcli skill
Semantic layer — save domain-named queries/mutations to create a business-level API over boards
Escape hatch — raw mcli query / mcli mutation access for anything not covered by CLI commands
Webhooks & daemon — background process to receive and poll webhook events
Authentication — token stored securely in OS keychain (macOS Keychain, Linux Secret Service)

Installation

# From source (requires Go 1.26+)
go install github.com/arnon/mcli/cmd/mcli@latest

# Or build locally
git clone [email protected]:DaPulse/mcli.git
cd mcli
make build    # → bin/mcli

Quick 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
mcli board get 9832181507

# List items with decoded column values
mcli item list --board 9832181507

# Create an item with column values
mcli item create --board 9832181507 --name "Ship feature" \
  --col 'status={"label":"Working on it"}' \
  --col 'due_date={"date":"2026-06-01"}'

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

Command reference

Authentication:

mcli auth login/logout/status

User:

mcli me — current user info

Workspaces & organization:

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

Boards:

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

Items:

mcli item list/get/create/update/move/archive/delete

GraphQL (escape hatch):

mcli query '<graphql>' — run raw queries (inline, from file, or stdin)
mcli mutation '<graphql>' — run raw mutations
mcli query save/list/run/delete — manage saved queries
mcli mutation save/list/run/delete — manage saved mutations

Webhooks & events:

mcli daemon start/stop/status — background webhook receiver
mcli webhook create/list/delete/events — webhook registration
mcli notification list/count/ack — poll for webhook events

Utility:

mcli skill — print LLM skill document
mcli version — print version

Run mcli <command> --help for flags and detailed usage on any command.

Semantic layer for LLM agents

Save reusable queries and mutations as domain-named operations. LLMs then operate in business terms instead of board IDs and column IDs.

Pattern

Set up boards and columns (one-time)
Save domain-named queries/mutations that encode the board structure
Agents call mcli query run <name> / mcli mutation run <name> with business-level variables

Example

Save a query that lists products from a specific board:

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

Run it with variables:

mcli query run list_products --var boardId=9832181507

Agents never need to know board IDs or column IDs — they call domain operations:

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"}}'

Column values

Reading

Column values are automatically decoded to human-readable form (status labels become strings, dates become ISO format, etc.).

Writing

Pass monday's raw column-value JSON via --col <id>=<json>:

mcli item create --board 123 --name "Task" \
  --col 'status={"label":"Done"}' \
  --col 'date={"date":"2026-05-10"}' \
  --col 'priority={"label":"High"}'

Use mcli board column list --board <id> to discover column IDs, types, and settings.

Webhooks and daemon

mcli includes a background daemon that receives monday.com webhooks and stores them as an inbox for agents to poll.

Start the daemon

# 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

The daemon:

Listens for webhook payloads on HTTP port (default 6780)
Exposes a Unix socket IPC for CLI commands
Opens a Cloudflare Quick Tunnel automatically (requires cloudflared in PATH)
Re-registers webhooks when the tunnel URL changes

Register webhooks

# 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>

Poll notifications

# 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

All notification/webhook commands require the daemon to be running.

LLM integration

mcli is purpose-built for LLM agents.

# Load the skill document into your LLM context
mcli skill

This outputs a concise, goal-oriented guide. The LLM discovers exact flags via mcli <command> --help as needed.

Authentication

Token resolution (first match wins):

--token <t> flag
MONDAY_API_TOKEN environment variable
Stored credential in OS keychain (mcli auth login)

Credentials are stored securely in the OS keychain (macOS Keychain, Linux Secret Service) or an age-encrypted file. Never stored plaintext.

License

MIT