excelcli による Excel 自動化

前提条件

• Windows ホスト上に Microsoft Excel がインストールされている（2016 以上）
• COM interop を使用 — macOS または Linux では動作しません
• GitHub Copilot excel-cli プラグインは、初回使用時に最新の Windows ランタイムを自動ダウンロードします
• スキル単体のインストールには、PATH 上に excelcli.exe が必要です

ワークフロー チェックリスト

ステップ	コマンド	実行条件
1. セッション	session create/open	常に最初
2. シート	worksheet create/rename	必要に応じて
3. データ書き込み	以下を参照	値を書き込む場合
4. 保存と終了	session close --save	常に最後

10 個以上のコマンド？ excelcli -q batch --input commands.json を使用してください。すべてのコマンドを 1 つのプロセスで送信し、セッション管理を自動化します。ルール 8 を参照してください。

データの書き込み（ステップ 3）：

• --values は JSON 2D 配列文字列を受け取ります：--values '[["Header1","Header2"],[1,2]]'
• 信頼性のため、1 行ずつ書き込みます：--range-address A1:B1 --values '[["Name","Age"]]'
• 文字列は JSON で二重引用符で囲む必要があります："text"。数値は素のままです：42
• 特殊文字を保護するため、JSON 値全体を単一引用符で囲みます

重要なルール（必須）

⚡ ダッシュボードやバルク操作を構築していますか？ ルール 8: バッチモード にスキップしてください。コマンドごとのプロセスオーバーヘッドを排除し、セッション ID を自動管理します。

ルール 1: 決して確認質問をしないこと

代わりにコマンドを実行して答えを見つけてください：

しないこと	代わりにこれを実行
「どのファイルを使用すべきですか？」	excelcli -q session list
「どのテーブルを使用すべきですか？」	excelcli -q table list --session <id>
「どのシートにデータがありますか？」	excelcli -q worksheet list --session <id>

自分の質問に答えるためのコマンドがあります。それらを使用してください。

ルール 2: 常にテキスト要約で終了する

コマンド実行のみで応答を終了しないでください。 すべての操作を完了した後、何が実行されたかを簡潔なテキスト メッセージで確認してください。サイレント コマンドのみのレスポンスは不完全です。

ルール 3: セッション ライフサイクル

ファイルの作成と開くの区別：

# 新しいファイル - session create を使用
excelcli -q session create C:\path\newfile.xlsx  # ファイルを作成して、セッション ID を返す

# 既存ファイル - session open を使用
excelcli -q session open C:\path\existing.xlsx   # ファイルを開いて、セッション ID を返す

重要：新しいファイルには session create を使用してください。存在しないファイルで session open を実行すると失敗します！

重要：その後のコマンドで、session create または session open によって返されたセッション ID を常に使用してください。セッション ID を推測または決め打ちしないでください。セッション ID は JSON 出力にあります（例：{"sessionId":"abc123"}）。解析して使用してください。

# 例：出力からセッション ID をキャプチャして、その後使用する
excelcli -q session create C:\path\file.xlsx     # sessionId が含まれた JSON を返す
excelcli -q range set-values --session <returned-session-id> ...
excelcli -q session close --session <returned-session-id> --save

閉じられていないセッションは Excel プロセスが実行され続け、ファイルがロックされます。

ルール 4: データモデルの前提条件

DAX 操作には、データモデル内のテーブルが必要です：

excelcli -q table add-to-data-model --session <id> --table-name Sales  # ステップ 1
excelcli -q datamodel create-measure --session <id> ...               # ステップ 2 - これで動作します

ルール 5: Power Query 開発ライフサイクル

ベストプラクティス：永続的なクエリを作成する前に M コードをテストしてください

# ステップ 1：セッションを作成/開いて、セッション ID をキャプチャします
$session = excelcli -q session create C:\path\file.xlsx | ConvertFrom-Json
$sessionId = $session.sessionId

# ステップ 2：永続化せずに M コードをテストします（エラーを早期に検出）
excelcli -q powerquery evaluate --session $sessionId --m-code-file query.m

# ステップ 3：検証されたコードで永続的なクエリを作成します
excelcli -q powerquery create --session $sessionId --query-name Q1 --m-code-file query.m

# ステップ 4：データを宛先にロードします
excelcli -q powerquery refresh --session $sessionId --query-name Q1

# ステップ 5：セッションを閉じます
excelcli -q session close --session $sessionId --save

ルール 6: ファイル エラーを直ちに報告する

「ファイルが見つかりません」または「パスが見つかりません」が表示される場合 — 停止してユーザーに報告してください。再試行しないでください。

ルール 7: バルク書き込みに計算モードを使用する

多くの値/数式（10 セル以上）を書き込む場合、自動再計算を無効にしてパフォーマンスを向上させます：

# 1. セッションを作成/開いて、セッション ID をキャプチャします
$session = excelcli -q session create C:\path\file.xlsx | ConvertFrom-Json
$sessionId = $session.sessionId

# 2. 手動モードに設定
excelcli -q calculationmode set-mode --session $sessionId --mode manual

# 3. 信頼性のため、データを 1 行ずつ書き込みます
excelcli -q range set-values --session $sessionId --sheet-name Sheet1 --range-address A1:B1 --values '[["Name","Amount"]]'
excelcli -q range set-values --session $sessionId --sheet-name Sheet1 --range-address A2:B2 --values '[["Salary",5000]]'

# 4. 最後に 1 回再計算します
excelcli -q calculationmode calculate --session $sessionId --scope workbook

# 5. 自動モードに戻す
excelcli -q calculationmode set-mode --session $sessionId --mode automatic

# 6. セッションを閉じます
excelcli -q session close --session $sessionId --save

ルール 8: バルク操作にはバッチモードを使用（10 個以上のコマンド）

同じファイルに対して 10 個以上のコマンドを実行する場合、excelcli batch を使用してすべてのコマンドを 1 つのプロセス起動で送信します。これにより、コマンドごとのプロセス起動オーバーヘッドとターミナル バッファ飽和を回避できます。

# すべてのコマンドを含む JSON ファイルを作成します
@'
[
  {"command": "session.open", "args": {"filePath": "C:\\path\\file.xlsx"}},
  {"command": "range.set-values", "args": {"sheetName": "Sheet1", "rangeAddress": "A1", "values": [["Hello"]]}},
  {"command": "range.set-values", "args": {"sheetName": "Sheet1", "rangeAddress": "A2", "values": [["World"]]}},
  {"command": "session.close", "args": {"save": true}}
]
'@ | Set-Content commands.json

# すべてのコマンドを一度に実行します
excelcli -q batch --input commands.json

主な機能：

• セッション自動キャプチャ：session.open/create の結果 sessionId が後続のコマンドに自動注入されます。セッション ID を解析して渡す必要はありません
• NDJSON 出力：1 行につき 1 つの JSON 結果：{"index": 0, "command": "...", "success": true, "result": {...}}
• --stop-on-error：最初の失敗で終了（デフォルト：すべてを続行）
• --session <id>：すべてのコマンドに対してセッション ID を事前設定（session.open をスキップ）

入力形式：

• ファイルからの JSON 配列：excelcli -q batch --input commands.json
• stdin からの NDJSON：Get-Content commands.ndjson | excelcli -q batch

CLI コマンド リファレンス

フル リファレンス： CLI コマンド リファレンスと一般的な落とし穴 を参照するか、インストールされたランタイムからライブ ヘルプを取得するには excelcli <command> --help を実行してください。

構文ルール： CLI コマンドは excelcli -q <command> <action> --session <id> --kebab-case-flags ... を使用します。range(action: ...) などの MCP 呼び出し構文、snake_case パラメータ、アンダースコア ツール名を使用しないでください。CLI コマンド名は MCP アンダースコアを削除します：calculation_mode は calculationmode に、range_format は rangeformat に、chart_config は chartconfig に、data_model は datamodel になります。

使用可能なコマンド グループ：

session, batch, service, calculationmode, chart, chartconfig, conditionalformat, connection, datamodel, datamodelrelationship, diag, namedrange, pivottable, pivottablecalc, pivottablefield, powerquery, range, rangeedit, rangeformat, rangelink, screenshot, sheet, worksheetstyle, slicer, table, tablecolumn, vba, window

一般的な落とし穴

CLI コマンド リファレンスと一般的な落とし穴 を参照してください。主な問題：

• --values-file は既存ファイルへのパスを期待します。インライン JSON には --values を使用してください。
• --timeout は正の整数である必要があります。デフォルト タイムアウトを使用するには省略してください。
• --values は 2D JSON 配列を受け取ります：'[["Name","Age"],["Alice",30]]'。
• --selected-items などのリスト パラメータには JSON 配列が必要です。
• Power Query 操作には 30 秒以上かかることがあります。十分なタイムアウトを使用してください。

リファレンス ドキュメント

• CLI コマンド リファレンスと一般的な落とし穴