CLI リファレンス
miseru は npm で配布される依存ゼロの CLI です(Node.js 20 以上)。インストール不要で npx miseru から使えます。
miseru push <file> --name <name> --context <type>:<key> [--tag <name> ...] [--project <name>] [--repo <owner/repo>] [--sha <sha>] [--viewport WxH]miseru comment --pr <n> [--repo <owner/repo>] # PR 集約コメントの markdownmiseru close --context <type>:<key> [--reason merged|closed|manual]miseru expire <image_id> # 画像を1枚だけ失効miseru mcp # MCP サーバー(stdio)として起動引数なし・--help・-h・help でヘルプを表示します。
配信コンテキスト
Section titled “配信コンテキスト”画像は配信コンテキストという単位にまとめられ、その単位で失効します。--context <type>:<key> で指定します(最初の : だけで 2 分割するので、キーに : を含めても構いません)。
| 型 | キー | 用途 |
|---|---|---|
github_pr |
owner/repo#<PR番号> |
GitHub の PR にスクショを見せる |
manual |
任意のラベル | PR に紐づかない共有(メッセージアプリへ貼る等) |
--pr <n> は --context github_pr:<owner/repo>#<n> のシュガーです。repo は --repo → MISERU_REPO → GITHUB_REPOSITORY → git remote get-url origin の順で解決します。--pr と --context を同時に指定するとエラーになります。
| 変数 | 必須 | デフォルト | 説明 |
|---|---|---|---|
MISERU_TOKEN |
✅ | — | Upload Token(ダッシュボードの「トークン」から発行) |
MISERU_API |
— | https://api.miseru.dev |
API のベース URL(セルフテスト・開発用) |
MISERU_REPO |
— | — | --pr と組み合わせる GitHub リポジトリ(owner/repo)。GITHUB_REPOSITORY より優先 |
MISERU_TOKEN 未設定の場合は MISERU_TOKEN が未設定です(ダッシュボードの「トークン」から発行できます) エラーで終了します。
miseru push
Section titled “miseru push”画像をアップロードし、貼り付け用の markdown を標準出力に返します。
npx miseru push ./shot.png --name home --pr 482 --viewport 1280x800npx miseru push ./shot.png --name home --context manual:design-reviewnpx miseru push ./shot.png --name home --pr 482 --tag review --tag desktop --project website| フラグ | 必須 | 説明 |
|---|---|---|
<file>(位置引数) |
✅ | 画像パス。1ファイルのみ。拡張子は .png / .jpg / .jpeg / .webp |
--name <name> |
✅ | スクリーンショットの論理名(例: home, login, checkout@mobile)。同じコンテキストで name と viewport が同じ画像は、古い画像を失効させて置き換えます |
--context <type>:<key> |
✅※ | 配信コンテキスト。--pr と排他 |
--pr <n> |
✅※ | --context github_pr:<owner/repo>#<n> のシュガー。--context と排他 |
--repo <owner/repo> |
— | --pr と組み合わせるリポジトリ。環境変数や git remote の自動解決より優先 |
--sha <sha> |
— | コミット SHA。省略時はカレントリポジトリの git rev-parse HEAD を自動検出。検出できなくても失敗しません |
--viewport <WxH> |
— | ビューポート(例: 1280x800) |
--tag <name> |
— | タグ。繰り返し指定可。存在しなければワークスペース内に作成 |
--project <name> |
— | プロジェクト名。存在しなければ作成し、新しいコンテキストを紐づける。省略時はトークンの既定 |
--compare |
— | ベースラインと比べる（Kurabe）。アップロードの後、結果を最大 30 秒待って stderr に表示します。待ち時間は変えられません。PNG の画像だけです。PNG 以外に付けるとアップロードごと失敗します |
--max-diff-ratio <ratio> |
— | 「変化なし」とみなす差分率の上限。0〜1 の比率（例: 0.001 = 0.1%）。比較の設定が無ければ既定は 0。値の検査は API が行います。承認の権限の無いトークンで 0 より大きい値を送ると 403。省くと比較の設定が使われます |
--mask <x,y,w,h> |
— | 比較から外す矩形。画像の画素の座標（CSS の px ではありません）。繰り返し可・最大 20 個。例: --mask 0,0,200,40 --mask 1000,0,280,40。値の検査は API が行います。承認の権限の無いトークンで指定すると 403。付けずに push し、ノイズは撮る側で止めてください。省くと比較の設定が使われます |
※ --context か --pr のどちらか一方が必須です。
push --compare を --pr（github_pr）で実行すると、その PR のベースラインがあればそれと、無ければ共有のベースラインと比べます。どちらも無ければ PR のベースラインを登録します。manual は今までどおり共有のベースラインを使います。共有へ反映するには、マージ後に miseru close --pr <n> --reason merged を実行するか、GitHub Action の close を設定してください。close を伝えずに放置した PR のベースラインは残ります。
出力は stdout = データ / stderr = 進捗 に分離されています。パイプで markdown だけを取り出せます。
- 標準出力(stdout): PR に貼る markdown(
) - 標準エラー(stderr):
✓ アップロード完了 (id: <id>) --compareのとき、stderr に比較: <結果>の 1 行を足します（ベースラインとして登録 / 変化あり・差分率 / 変化なし / 失敗 / 計算中）。「変化あり」でも終了コードは 0 です。差分率が 0 より大きくても許容幅以内なら、「変化なし」の文言に差分率と許容幅を表示します
# markdown だけをファイルに書き出すnpx miseru push ./shot.png --name home --pr 482 > comment.mdクライアント側バリデーション
Section titled “クライアント側バリデーション”アップロード前に CLI 側で次を検査します(サーバー側の検証は HTTP API リファレンスを参照)。
| 条件 | エラーメッセージ |
|---|---|
| 対応外の拡張子 | 対応していない拡張子です(png/jpg/webp): <file> |
| 5MB 以上 | 画像が 5MB を超えています(GitHub Camo の制限) |
--context の形式不正 |
--context は <type>:<key> の形式で指定してください(例: manual:design-review) |
--pr と --context の併用 |
--pr と --context は同時に指定できません |
--pr 使用時に repo を解決できない |
リポジトリを特定できません: --repo owner/repo か MISERU_REPO / GITHUB_REPOSITORY を指定してください |
| API エラー | アップロード失敗 (<status>): <エラー内容> |
miseru comment
Section titled “miseru comment”PR の全スクリーンショットを集約した markdown を標準出力へ返します。
npx miseru comment --pr 482 --repo elchika-inc/miseru--pr <n> は必須です。--repo <owner/repo> を省略した場合の解決順は push と同じです。
miseru close
Section titled “miseru close”配信コンテキストを閉じ、その失効ポリシーを適用します。冪等なので何度実行しても安全です。
npx miseru close --pr 482 --reason mergednpx miseru close --context manual:design-review| フラグ | 必須 | 説明 |
|---|---|---|
--context <type>:<key> |
✅※ | 配信コンテキスト。--pr と排他 |
--pr <n> |
✅※ | --context github_pr:<owner/repo>#<n> のシュガー |
--repo <owner/repo> |
— | --pr と組み合わせるリポジトリ。解決順は push と同じ |
--reason <r> |
— | merged / closed / manual。merged なら PR のベースラインを共有のベースラインへ上げ、closed・manual(既定)なら捨てる |
成功時は stderr に ✓ <type>:<key> を閉じました(policy: …, marked: …, expired: …) を出力します。policy を必ず併記するのは、retain_days / forever では画像が消えないため「なぜ消えなかったか」が呼び手に見える必要があるからです。
miseru expire
Section titled “miseru expire”画像を1件、即座に失効させます(オリジンから削除され、配信 URL は 404 になります)。
npx miseru expire <image_id><image_id>はmiseru pushが返した画像 ID です- 成功時は stderr に
✓ 失効しました: <image_id>を出力します - 失敗時は
失効失敗 (<status>): <エラー内容>で終了します
miseru diff
Section titled “miseru diff”比較（Kurabe）の結果を表示します。
npx miseru diff <image_id>npx miseru diff <image_id> --out ./diff- 標準出力(stdout): 比較の状態の JSON（HTTP API の
GET /v1/images/:id/diffの応答そのもの） - 標準エラー(stderr): 人が読む一文と、次の操作の案内
--out <dir>を付けると、比較済みのとき<image_id>-baseline.png/<image_id>-candidate.png/<image_id>-diff.pngをそのディレクトリに保存します。ベースラインが比較の後に置き換えられている場合など、取れない画像は飛ばして理由を stderr に出します
miseru approve
Section titled “miseru approve”差分を承認し、比べたベースラインをその画像に置き換えます。取り消せません。PR の push なら、その PR のベースラインだけを置き換え（無ければ作り）、PR を merged で閉じると共有のベースラインへ反映されます。同じ差分をもう一度承認しても成功します。
npx miseru approve <diff_id><diff_id>はmiseru push --compare/miseru diffが表示した差分 ID です- ベースラインの権限が無いと
承認失敗 (403): this token cannot approve diffs; ask someone whose token can manage baselines to run: miseru approve <diff_id>になります。message のとおり、権限を持つ人に承認を頼んでください - PR の承認では stderr に
✓ 承認しました: <diff_id>。この PR のベースラインを更新しました。PR を merged で閉じると、共有のベースラインに反映されますと表示します - 閉じた PR の未承認の差分は、
staleが false でも 409context is closedになります - 比較した後にベースラインが更新された差分は承認できません（
承認失敗 (409): …）。比較つきで push し直してください
miseru baselines
Section titled “miseru baselines”Kurabe のベースライン（比べる基準の画像）の一覧を、標準出力に JSON で出します。全ページを取得します。標準エラーには件数と合計サイズを出します。PR ごとのベースラインも混ざり、context_id がその PR のコンテキストの id です。共有のベースラインは context_id: null です。
npx miseru baselines [--project <id|none>]--projectはプロジェクトの id（noneならプロジェクトに属さないものだけ）。名前ではありません
miseru baselines delete
Section titled “miseru baselines delete”ベースラインを 1 件削除します。取り消せません。次に同じ名前を --compare で push すると、PR のベースラインがあればそれと、無ければ共有のベースラインと比べ、どちらも無ければその画像が新しいベースライン（PR の push なら PR のベースライン）になります。共有・PR ごとのどちらの層も削除できます。
npx miseru baselines delete <baseline_id>- ベースラインの権限が無いと
削除失敗 (403): this token cannot delete baselines; ask someone whose token can manage baselines to run: miseru baselines delete <baseline_id>になります。message のとおり、権限を持つ人に削除を頼んでください - ストレージ上限で 413 が出たときに、使わなくなった名前のベースラインを消すのに使います
- たくさん消すときは、
miseru baselinesの JSON から id を取り出して繰り返してください
miseru check
Section titled “miseru check”PR・コンテキストの比較結果で CI を止めます。この機能を含む CLI の版から使えます（CLI の版上げは別の PR）。
miseru check --pr <n> [--repo <owner/repo>] [--wait <秒>]miseru check --context <type>:<key> [--wait <秒>]--pr と --context は排他で、解釈は miseru close と同じです。--wait は 0〜600 の整数（秒）、既定 60。計算中は 5 秒ごとに取得し直し、0 なら 1 回だけ取得します。比較の対象の画像ごとの行と、最後に全体の判定を標準出力へ出します。
✓ home (1280x800): 変化なし✗ login: 変化あり(差分率 3.20%)・未承認。miseru diff <image_id> で画像を確認し、意図した変化なら miseru approve <diff_id>Kurabe: 要確認 1 件(比較 2 枚)| 終了コード | 意味 |
|---|---|
| 0 | pass。未承認の変化が無い（比較の対象が 0 枚でも通る） |
| 1 | fail、または待ち時間内に計算が終わらない pending |
| 2 | 引数・認証・通信などのエラー。404（コンテキスト無し）・422（200 枚超過）も含む |
閉じたコンテキスト、未承認の変化、古い差分、比較失敗、ベースラインのある画像の比較忘れは止まります。承認した後は CI の job を再実行してください。承認の権限の無いトークンをアップロードに使うことで、自分で承認して通すことを防げます。
miseru compare-settings
Section titled “miseru compare-settings”許容幅とマスクを論理名ごとの比較の設定として置きます。この機能を含む CLI の版から使えます（CLI の版上げは別の PR）。
miseru compare-settingsmiseru compare-settings set --name home --viewport 1280x800 --project web --max-diff-ratio 0.001 --mask 0,0,1280,40miseru compare-settings delete <id>一覧は権限の無いトークンでも取得できます。set と delete は承認の権限がある Upload Token が必要です。--project を省くとトークンの既定プロジェクト、--no-project はワークスペース直下です。両方は同時に指定できません。--viewport を省くと viewport のない画像が対象になります。
set は置き換えです。--max-diff-ratio だけなら以前のマスクが消え、--mask だけなら以前の許容幅が消えます。--mask は繰り返して指定できます。許容幅は0〜1、マスクの各値は0〜99999の整数で幅と高さは1以上、最大20個です。範囲は API が検証し、エラーの message を表示します。
push で値を省くと、同じプロジェクト・論理名・viewport の設定が使われます。権限の無いトークンで動くエージェントも、人が決めた設定を使えます。push の指定は設定を変えません。マスクを省いても設定のマスクを使うため、マスクを外すには設定を置き換えるか削除してください。
設定を変えても、すでにアップロードした画像の値は変わりません。変化ありのまま残った画像は、比較つきで push し直してください。
一覧の stdout は { "settings": [ … ] } の1行 JSON、set の stdout は保存した1件の JSON です。成功の件数や id は stderr に表示します。delete は stderr に削除した id を表示します。API の403などの失敗時は stderr に message を出し、終了コード1になります。項目の詳細は 比較の設定の API を参照してください。
miseru mcp
Section titled “miseru mcp”MCP サーバーとして stdio で起動します。ツールの仕様は MCP サーバーリファレンスを参照してください。
| コード | 意味 |
|---|---|
| 0 | 成功（--compare の「変化あり」「計算中」を含む） |
| 1 | check は判定の失敗・待ち切れない計算中。それ以外はエラー(バリデーション失敗・API エラー・不明なコマンド/オプション) |
| 2 | check のエラー（引数の誤り・認証・404・422・通信失敗など） |
未知のコマンドは error: 不明なコマンド: <cmd>、未知の -- オプションは 不明なオプション: --xxx として失敗します。終了コードは通常 1。check だけは、判定の失敗・待ち切れない計算中が 1、引数・認証・通信などのエラー全般が 2 です。
PR への自動コメントについて
Section titled “PR への自動コメントについて”miseru push は markdown を返すだけで、PR へのコメント投稿は行いません。PR コメントの自動投稿・更新は GitHub Action が担当します。手動運用の場合は、標準出力の markdown を PR コメントに貼ってください。