miro-cli

name	miro-cli
description	Hand-authored Cobra CLI for the Miro REST API.
author	Olga Safonova
license	Apache-2.0
argument-hint	<command> [args]
allowed-tools	Read Bash
metadata	{"openclaw":{"requires":{"bins":["miro-cli"]}}}

Miro Developer Platform — miro-cli

Prerequisites: Install the CLI

This skill drives the miro-cli binary. You must verify the CLI is installed before invoking any command from this skill. If it is missing, install it first:

1. Install from source:

   go install github.com/olgasafonova/miro-cli/cmd/miro-cli@latest
   

2. Verify: miro-cli --help (and miro-cli --version to record the build; a source/go install build reports dev, a release reports its tag).
3. Ensure $GOPATH/bin (or $HOME/go/bin) is on $PATH.

Alternatively, install via Homebrew (brew install olgasafonova/tap/miro-cli) or download a pre-built binary from the latest release.

If --help reports "command not found" after install, the install step did not put the binary on $PATH. Do not proceed with skill commands until verification succeeds.

Miro Developer Platform concepts

• New to the Miro Developer Platform? Interested in learning more about platform concepts?? Read our introduction page and familiarize yourself with the Miro Developer Platform capabilities in a few minutes.

Getting started with the Miro REST API

• Quickstart (video): try the REST API in less than 3 minutes.
• Quickstart (article): get started and try the REST API in less than 3 minutes.

Miro REST API tutorials

Check out our how-to articles with step-by-step instructions and code examples so you can:

• Get started with OAuth 2.0 and Miro

Miro App Examples

Clone our Miro App Examples repository to get inspiration, customize, and explore apps built on top of Miro's Developer Platform 2.0.

Command Reference

miro-cli is organized into resource groups. Each group is a subcommand tree; run miro-cli <group> --help for the exact verbs and flags of that group, and miro-cli <group> <verb> --help for a single command. The groups are:

Group	What it covers
boards	Create, copy, get, update, delete boards; also boards diagram (render a sequence/flowchart from text)
items	Generic board items: get, list, update, delete, and bulk update/delete via --ids-file / --patches-file (pass - to read the JSON payload from stdin, e.g. ... | miro items bulk-delete --ids-file -)
stickies	Sticky notes
shapes	Shapes
texts	Text items
cards	Card items
appcards	App card items
frames	Frames
images	Image items
embeds	Embedded URLs
documents	Document items
connectors	Connectors (lines/arrows between items)
tags	Tags and tag assignment
groups	Item groups
mindmap	Mind-map nodes
codewidgets	Code widget items
members	Board members and sharing roles
boards share	Invite members to a board (gated by the share allowlist — see Security)
exports	Board export jobs
audit	Organization audit events (last 90 days; Enterprise)
sync	Mirror boards/items into a local SQLite store for offline use
query	Run read-only SQL / FTS5 search against the local store built by sync

The authoritative command list is the binary itself. When unsure whether a verb exists, run miro-cli <group> --help rather than guessing.

Finding the right command

• Reading/searching offline or repeatedly → miro-cli sync once, then miro-cli query "<SQL>" (FTS5 full-text search is available).
• One-off live read → the matching resource group's get/list verb.
• Mutating a board → the resource group's create/update/delete verb; destructive verbs require --yes (or --agent).

Auth Setup

miro-cli authenticates with a Miro access token, resolved in this order:

1. --token <value> flag
2. $MIRO_ACCESS_TOKEN environment variable

If neither is set, commands that hit the API exit with a config error (exit code 10). There is no interactive login.

Check the setup directly with miro-cli auth status:

miro-cli auth status --json           # {token_present, source, verified, status}, no network
miro-cli auth status --verify --json  # also confirms the token works right now

Exit codes: 0 token present (and valid, with --verify), 10 no token, 4 token rejected. Under --verify, status reports ok, invalid_or_expired, or insufficient_scope so you can tell a bad token from a scope problem. Prefer this over probing with a read command.

Agent Mode and agent-facing flags

These global flags are available on every command:

• --agent — agent mode. Expands to --json and --yes (forces JSON output and skips destructive-operation confirmations). Nothing else.
• --json — force JSON output (the default when stdout is piped).
• --dry-run — print the request the command would send, then exit without calling the API.
• --yes — skip confirmation prompts on destructive operations.
• --idempotent — treat already-exists as success on create, and already-gone as success on delete.
• --select <fields> — comma-separated list of top-level field names to keep in JSON output. It filters the top-level object; when the output is a JSON array, the same top-level filter is applied to each element. It does not descend into nested objects via dotted paths.
• --rate-limit, --concurrency, --cache-ttl, --no-cache, --store-path — tuning for throughput, the GET response cache, and the local store location.

Example:

miro-cli boards get --agent --select id,name

Output shape

Commands print the API result as JSON directly to stdout — there is no meta/ results envelope to unwrap; parse the value itself. When stdout is a terminal, a short human-readable summary may be written to stderr, so piped and --agent consumers receive clean JSON on stdout.

Security: board sharing is allowlist-gated

miro-cli boards share grants a third party access to a board, so it is gated by a fail-closed allowlist. With no allowlist configured, every share attempt is refused.

• MIRO_SHARE_ALLOWED_DOMAINS — comma-separated list of recipient email domains permitted to receive invitations.
• MIRO_SHARE_ALLOWED_EMAILS — comma-separated list of exact addresses. When set (even to an empty value), it is authoritative: only the listed addresses pass and the domain allowlist is ignored entirely. This is a strict tightening, not a widening — a permitted domain cannot rescue an unlisted address.

Exit codes

Code	Meaning
0	Success
2	Usage error
3	Not found (HTTP 404)
4	Auth error (HTTP 401 / 403)
5	Other API error
7	Rate limited (HTTP 429)
10	Config error (e.g. missing token)