meticulous-cli について
meticulous-cliは、ユーザーセッションを記録して再生し、ビジュアル回帰を検出するコマンドラインツールです。テスト担当者やエージェントのワークフロー向けに、認証、デバッグ、ダウンロード、差分分析、再生のコマンドを提供し、エージェント用コマンドはホスト型MCPサーバーからも利用できます。
主な機能
- 01ユーザーセッションの記録と再生
- 02テスト実行とビジュアル差分の分析
- 03セッション、再生、テスト実行のダウンロード
- 04コード変更に関連するセッションの検索
- 05コマンドスキーマのJSON出力
活用シーン
- 01記録済みセッションのローカル再生
- 02テスト実行のビジュアル差分確認
- 03APIトークンによるCI認証
- 04エージェントワークフローからのテスト実行
MCP 対応
https://app.meticulous.ai/api/mcp のホスト型MCPサーバーは、エージェント用コマンドをMCPクライアントに公開します。エンドポイントURLで接続し、MCPツールでは推測されないgitコンテキストを明示的に渡します。
インストール
コマンドをコピーしてターミナルで実行します。
npx skills add https:/インストール後、Claude Code で/meticulous-cliを入力して読み込まれたか確認します。
同梱ファイル
SKILL.md と一緒にインストールされる参考資料やスクリプト。
references/agent.mdauth.mddebug.mddownload.mdlocal.mdproject.mdschema.mdsimulate.md詳細
Meticulous CLI
meticulous CLI はユーザーセッションを記録して再生し、視覚的なリグレッションを検出します。@alwaysmeticulous/cli の一部としてインストールされます。
開始する前に、Meticulous CLI とスキルが最新の状態であることを確認するため、
meticulous-cli-updateスキルを実行してください。ただし、この会話の前の段階ですでに実行されている場合は、スキップしてください。
呼び出し
meticulous <command> [options]
スキルは meticulous が PATH にあることを前提としています。meticulous-cli-update スキルは、見つからない場合に npm install --global @alwaysmeticulous/cli@latest を使ってグローバルにインストールします。プロジェクトごとにローカルでインストールした場合は、npx @alwaysmeticulous/cli として呼び出すこともできます。
コマンドグループ
| コマンド | 目的 |
|---|---|
agent | テスト実行の確認、分析、開始 — エージェント向けのコマンドで、MCP サーバーでも公開されています |
auth | Meticulous で認証します（ログイン、whoami、ログアウト、プロジェクトの選択） |
debug | リプレイの差分とリプレイを調査するための、AI 対応デバッグワークスペースをセットアップします |
download | セッション、リプレイ、テスト実行をローカルにダウンロードします |
local | 現在のブランチのコード変更に関連するセッションを検索します |
project | 認証中のプロジェクトを確認します |
simulate / replay | 記録したセッションを URL に対して再生します |
schema | CLI コマンドのスキーマを JSON として出力します（エージェント／プログラムからの利用向け） |
各グループのオプションの詳細は、リファレンスを参照してください。
- references/agent.md
- references/auth.md
- references/debug.md
- references/download.md
- references/local.md
- references/project.md
- references/simulate.md
- references/schema.md
グローバルオプション
以下のオプションは、すべてのコマンドで使用できます。
| オプション | 型 | デフォルト | 説明 |
|---|---|---|---|
--logLevel | string | info | ログの詳細度：trace、debug、info、warn、error、silent |
--dataDir | string | ~/.meticulous | セッション、リプレイ、その他のデータを保存するディレクトリ |
--jsonArgs | string | — | すべてのオプションを JSON 文字列として渡します（プログラム／エージェントからの呼び出しに便利です） |
--rawJson は、非推奨の別名である --jsonArgs です。--dryRun はグローバルオプションではありません。アクションを実行するコマンド（例：ci／agent の実行開始・アップロードコマンド、simulate）でのみ使用できます。各コマンドのリファレンス、または meticulous schema <command> を確認してください。
認証
コマンドは OAuth で認証します。ログイントークンはディスクに保存され、セッションをまたいで再利用されます。インタラクティブなターミナルでは、認証が必要なコマンドを実行するとブラウザーでのサインインが自動的に開始されます。TTY がない場合（通常のエージェントでの実行時）は失敗し、meticulous auth login を実行するよう通知されます。現在の状態を確認するには、meticulous auth whoami を実行します。プロジェクトスコープのコマンドにはデフォルトのプロジェクトも必要です。これはログイン時、または meticulous auth set-project で設定します。references/auth.md を参照してください。
API トークン（--apiToken または METICULOUS_API_TOKEN 環境変数を使用。特定の組織／プロジェクトにスコープを設定）もサポートされており、CI などの非インタラクティブな環境での認証に使用できます。一部のエージェントプラットフォームでは、app.meticulous.ai への送信リクエストにベアラー認証情報を付与しますが、これも利用できます。その場合、auth whoami には credentials injected at request time と表示されます。
MCP サーバー
agent コマンドは、https://app.meticulous.ai/api/mcp でホストされている MCP サーバーのツールとしても公開されています。そのため、MCP 対応クライアント（Claude Code、Cursor、Codex）から、CLI をシェル経由で実行する代わりに直接呼び出せます。大半の読み取り／分析コマンドは get_<command> ツールに対応しており、CLI コマンドの --json 出力と同じデータを返します。たとえば、agent test-run-diffs ⇄ get_test_run_diffs、agent dom-diff ⇄ get_dom_diff、download session ⇄ get_session_data です。変更を伴う 2 つのコマンド（upload-build、trigger-test-run）にも MCP ツールがありますが、1 対 1 の対応ではありません。この重要な違いを含む完全な対応表については、references/agent.md を参照してください。エンドポイント URL だけで接続できます（初回使用時にブラウザーで OAuth 認証を行います）。スキルは CLI を前提に記述されています。MCP サーバーに接続している場合は、記載されている箇所で対応するツールに置き換えてください。ただし、MCP ツールは CLI と異なり、Git のコンテキスト（commitSha／baseSha／diff）を自動推定しません。そのため、MCP を使用する場合は常に明示的に指定してください。
例
# Print schema for all commands (agent use)
meticulous schema
# Run a single replay locally
meticulous simulate --sessionId=<id> --appUrl=http://localhost:3000