Miro CLI Skill

A comprehensive guide for using the Miro CLI tool to interact with the Miro Platform API from the command line.

⚠️ Trust Model & Security Declaration

Metadata Declaration: - Type: CLI tool wrapper (external binary management) - External Binary: mirocli (npm package: davitp/mirocli) - Manages Credentials: YES (stores in system keyring, NOT in skill) - Credential Storage: System keyring (local-only, OS-managed) - Capabilities: Read-only access to boards, teams, organization, logs - Limitations: No create/update/delete; requires OAuth setup

Critical Trust Requirements:

1. You must trust the mirocli npm package: - Author: @davitp (community-maintained, not official Miro) - Package: https://www.npmjs.com/package/mirocli - Source: https://github.com/davitp/mirocli - Verification: Check npm downloads, last update date, issues, GitHub stars - Why it matters: This external binary handles your Client ID, Client Secret, and OAuth tokens

2. You must trust your system keyring: - macOS: Keychain - Linux: Secret Service - Windows: Credential Manager - This skill does NOT: Store credentials, cache tokens, or transmit them

3. Helper binaries are standard Unix tools: - jq — JSON processor (widely used, open source) - column — Text formatter (standard utility) - These are optional and do NOT handle credentials

4. Network access: - Direct HTTPS calls to api.miro.com (official Miro endpoint) - OAuth browser-based authentication on your machine - No data proxying or credential transmission through third parties

Recommendation: Before using with production credentials: 1. Review mirocli source code: https://github.com/davitp/mirocli 2. Test with a non-sensitive Miro account 3. Verify OAuth token storage in ~/.mirocli/ 4. Run in isolated environment initially

What It Does

Miro CLI enables command-line access to Miro resources and enterprise features: - Boards — List, search, and manage boards - Teams — View and organize teams - Organization — View org details and members - Board Export — Export boards as PDF, PNG, SVG - Content Logs — View activity/change logs (enterprise) - Audit Logs — Access audit logs (enterprise)

Perfect for automation, scripting, and bulk operations.

Requirements

Binaries (required): - mirocli — Miro CLI tool (installed via npm) - jq — JSON query processor (for filtering/scripting) - column — Text column formatter (for table output in helper scripts)

Credentials (interactive entry required): - Organization ID — Your Miro organization identifier - Client ID — OAuth app client ID - Client Secret — OAuth app client secret

Optional (for JSON workflows): - jq — JSON processor for advanced filtering and data transformation

Installation & Setup

1. Install Dependencies

mirocli (required):

npm install -g mirocli

jq (optional, but recommended):

# macOS
brew install jq

# Linux (Debian/Ubuntu)
sudo apt install jq

# Linux (Fedora)
sudo dnf install jq

2. Configure Context (One-time)

mirocli context add

This will prompt for: - Context name (e.g., default) - Organization ID (from your Miro settings) - Client ID (from your Miro app) - Client Secret (from your Miro app)

Credentials are stored securely by mirocli in ~/.mirocli/ (system keyring on macOS/Linux).

3. Authenticate with OAuth

mirocli auth login        # Opens browser for OAuth flow
mirocli auth whoami       # Verify authentication

Quick Start

View Organization

mirocli organization view

List Boards

mirocli boards list                    # All boards
mirocli boards list --json             # JSON output
mirocli boards list --team-id <id>     # Filter by team
mirocli boards list --sort "name"      # Sort by field

List Teams

mirocli teams list
mirocli teams list --name "Design"     # Filter by name
mirocli teams list --json

Export Board

mirocli board-export <board-id> --format pdf
mirocli board-export <board-id> --format png
mirocli board-export <board-id> --format svg

Common Workflows

Find Board by Name

mirocli boards list --json | jq '.[] | select(.name | contains("Design"))'

Export All Boards from Team

See scripts/export-team-boards.sh

List Boards with Owner Info

mirocli boards list --json | jq '.[] | {name, id, owner: .owner.name}'

Filter Boards by Date

mirocli boards list --modified-after "2026-03-01" --json

Setup Flow

Install dependencies → npm install -g mirocli (+ jq/column if needed)
Add context → mirocli context add (enter Org ID, Client ID, Client Secret interactively)
Authenticate → mirocli auth login (browser opens for OAuth, one-time)
Verify → mirocli auth whoami (confirm authentication works)
Use CLI → mirocli boards list, mirocli teams list, etc.

Credential Storage: mirocli stores credentials in ~/.mirocli/ using system keyring (secure, local-only)

Global Options

-c, --context <name>    # Use specific context
-h, --help             # Show help
-v, --version          # Show version
--json                 # Output as JSON

Security & Trust

How Credentials Are Handled:

Stored locally — mirocli uses system keyring (secure, local-only)
Not in skill — Credentials are entered interactively via mirocli context add
OAuth token — mirocli manages OAuth session tokens; they never leave your machine
Exports — Board exports are saved locally; no data sent to third parties beyond Miro API

What This Skill Does:

✅ Reads/lists boards, teams, org data via Miro API
✅ Exports boards as PDF/PNG/SVG
✅ Views activity/audit logs (enterprise)
❌ Never modifies boards/teams (read-only commands only)
❌ Never stores credentials in skill bundle
❌ Never sends data outside of Miro API calls

Third-party Trust:

This skill relies on: - mirocli (npm package) — External CLI tool that handles credential storage - Miro API — Direct calls to Miro's official API endpoints - System keyring — OS-level credential storage (macOS Keychain, Linux Secret Service, Windows Credential Manager)

Command Reference

See references/miro-cli-commands.md for detailed command documentation.

Help

mirocli --help
mirocli <command> --help

miro-mcp — MCP integration for Miro (AI coding tools)
miro-sdk — Web SDK reference for building plugins
miro-api — REST API reference for programmatic access

Setup Date: 2026-03-14
Last Updated: 2026-03-14
Status: Ready (OAuth login pending)