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

1. Install dependencies → npm install -g mirocli (+ jq/column if needed)
2. Add context → mirocli context add (enter Org ID, Client ID, Client Secret interactively)
3. Authenticate → mirocli auth login (browser opens for OAuth, one-time)
4. Verify → mirocli auth whoami (confirm authentication works)
5. 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

Related Skills

• 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)