officecli-xlsx

OfficeCLI XLSX スキル

セットアップ

officecli が見つからない場合:

• macOS / Linux: curl -fsSL https://d.officecli.ai/install.sh | bash
• Windows (PowerShell): irm https://d.officecli.ai/install.ps1 | iex

officecli --version で確認してください（PATH が反映されない場合は新しいターミナルを開いてください）。インストールに失敗した場合は、https://github.com/iOfficeAI/OfficeCLI/releases からバイナリをダウンロードしてください。

⚠️ ヘルプ優先ルール

このスキルは、すべてのコマンドフラグを説明するものではなく、良質な xlsx がどのようなものかを示すものです。プロパティ名、列挙値、エイリアスが不確かな場合は、推測する前にヘルプを参照してください。

officecli help xlsx                         # List all xlsx elements
officecli help xlsx <element>               # Full element schema (e.g. pivottable, chart, cf)
officecli help xlsx <verb> <element>        # Verb-scoped (e.g. add chart, set cell)
officecli help xlsx <element> --json        # Machine-readable schema

ヘルプはインストールされている CLI のバージョンを反映します。このスキルとヘルプの内容が食い違う場合は、ヘルプが正です。

シェルと実行の規律

シェルのクォート（zsh / bash）。 Excel のパスには [] が含まれ、数値書式には $ が含まれます。どちらもシェルのメタ文字です。ルール:

• 要素パスは必ず引用符で囲んでください: "/Sheet1/row[1]"（/Sheet1/row[1] ではなく）。
• $ を含むプロパティ値には シングルクォート を使用してください: numFmt='$#,##0'。
• シート間の ! 参照を含む数式には、<<'EOF' ヒアドキュメントを使った batch を使用してください（既知の問題を参照）。
• プロパティ値内の \n と \t は CLI によって解釈されます。\n はセル内の実際の改行（--prop wrapText=true と組み合わせます）、\t はタブです。xlsx / docx / pptx で一貫しています。リテラルの backslash-n が必要な場合（ほとんど必要ありません）は \\n と二重にしてください。（$ は上記のシェル層の問題なので、シングルクォートで囲んでください。）

段階的な実行。 コマンドは一度に 1 つずつ実行し、それぞれの終了コードを確認してください。officecli は呼び出すたびにファイルを変更します。コマンド 3 で失敗する 50 行のスクリプトは、静かに連鎖的な失敗を起こします。1 コマンド → 出力を確認 → 続行、の順で進めてください。

成果物の要件

コマンドに手を伸ばす前に、良質な xlsx がどのようなものかを把握してください。以下は、すべてのブックが必ず満たすべき成果物の基準です。

すべての Excel ファイル

数式エラーはゼロ。 納品するすべてのブックには、#REF!、#DIV/0!、#VALUE!、#NAME?、#N/A が 一切 あってはなりません。例外はありません。分母は IFERROR または IF(x=0,...) で保護してください。

ハードコードされた値ではなく数式を使用。 数値が他のセルから計算できるなら、それは数式にすべきです。=SUM(B2:B9) にすべき箇所に 5000 をハードコードすると、入力が変わったときにブックが動的であり続けるという前提が崩れます。これはこのスキルで最も重要なルールです。

適切なフォント。 ブック全体で一貫した、プロフェッショナルなフォント（Arial / Calibri / Times New Roman）を 1 つ使用してください。1 つのシートが CSV から来たからといって、4 種類のフォントを混在させないでください。

明示的な列幅。 自動調整機能はありません。ユーザーが読む列には必ず width を設定してください。デフォルトの 8.43 文字では、すべてが切り詰められてしまいます。目安としては、ラベルは 20〜25、数値は 12〜15、日付は 12、短いコードは 8〜10 です。

既存のテンプレートを維持。 見た目が既に決まっているファイルを編集する場合は、それに合わせてください。既存の規則は、これらのガイドラインより優先されます。

視覚的な納品基準（すべてのブックに適用）

完了を宣言する前に officecli view "$FILE" html を実行し、返された HTML パスを読み込んで、以下がすべて満たされていることを確認してください。

• どのセルにも ### が表示されていないこと。 ### は、列の幅が最も長い値に対して狭すぎることを意味します。ユーザーが読むすべての列には明示的な width を設定してください。納品されたファイルに ### があるのは未完成の作業であり、「ちょっとした見た目の問題」ではありません。
• タイトルが切れていないこと。 シートのタイトル、セクション見出し、長いラベルがすべて収まっている必要があります。列を広げるか、セルに wrapText=true を適用してください。
• プレースホルダーのトークンがデータとして表示されていないこと。 $fy$24、{var}、<TODO>、xxxx などが、セル、グラフのタイトル、系列名、凡例に表示されてはいけません。これらはビルド時のトークンで、置換されずに残ったものです。
• 円グラフ／ドーナツグラフの扇形に異なる塗りつぶし色があること。 扇形が同じ色で描画される場合は、bar / column に切り替えるか、colors=... を明示的に指定してください。
• 空の末尾ページや空のグラフのアンカーがないこと。 元データのセルが空の状態で anchor=D2:J18 を指定すると、グラフが壊れているように見えます。

上記のいずれかが満たされない場合は、作業を止めて修正してから完了を宣言してください。

印刷レイアウト。 ユーザーが印刷する、または役員向け資料として送付する可能性のあるシートには、ページ設定が必要です。既定の縦向きで、ページに収めない設定のままだと、広い表やグラフがページの途中で分割されてしまいます。シートの形状に応じて、以下のフィットモードを選択してください。

# Summary / chart / dashboard sheet (small, ≤ ~40 rows): fit to a single page.
officecli set "$FILE" "/Summary" --prop orientation=landscape --prop fitToPage=true
# Tall data table (dozens+ rows): fit WIDTH only, let height paginate naturally.
# fitToPage=true here crushes every row onto one page → unreadable (### dates, 5px rows).
officecli set "$FILE" "/Data" --prop orientation=landscape --prop fitToPage=1x0

fitToPage=true は 1x1 と同じで、縦横both軸を1ページに収めます。これが正しいのは、シートがすでに短い場合だけです。1x0 は横幅を1ページに収め、縦方向のページ数は無制限にします。次の場合に使用します。シートにグラフがある、列が8つを超える、またはユーザーの依頼に印刷、役員、投資家といった言葉が含まれる場合です。

財務モデルのみ — テンプレート、トラッカー、CSV インポート、または業務用シートを作成する場合はこのセクションを省略してください

対象範囲：予算、予測、3表モデル、バリュエーション、その他 $ を多用する分析用ブックです。顧客サポートのトラッカーやオンボーディングのテンプレートには、このセクションは不要です。

色分けの業界標準。 装飾ではなく言語として使う、5つの基本色です。レビューする人が、数式を読む前に色だけでそのセルが何であるかを判断できるべきです。

色	役割	例
青文字 0000FF	ハードコードされた入力値、シナリオ変数	font.color=0000FF
黒文字 000000	すべての数式と計算	既定
緑文字 008000	このブック内のシート間リンク	font.color=008000
赤文字 FF0000	外部ファイル／外部ブックへのリンク	font.color=FF0000
黄色の塗りつぶし FFFF00	確認が必要な主要な前提条件	fill=FFFF00

レビューする人が、数式を読む前に色だけでセルの種類を判断できる必要があります。これは見た目の好みではなく、情報を伝えるための取り決めです。

数値の書式設定 — 好みではなく標準です。

• 年は数値ではなく文字列として扱います。2,026 ではなく 2026 と表示してください。numFmt="@" を使うか、type=string を設定します。
• 通貨の単位はすべてのセルではなく、見出し（Revenue ($mm) など）に記載します。
• ゼロは 0 ではなく - と表示します。$#,##0;($#,##0);"-" を使用してください。
• パーセンテージは既定で小数点以下1桁にします：0.0%。
• 負の数は括弧で囲みます：-1,234 ではなく (1,234)。
• バリュエーション倍率には 0.0x 形式を使用します（EV/EBITDA、P/E など）。

前提条件は数式の中ではなく、セルに置きます。 =B5*(1+$B$6) は正しく、=B5*1.05 はバグです。ハードコードされた青文字の入力値には、隣接するセルか、セルコメントに出典メモを記載してください。

Source: Company 10-K, FY2024, Page 45, Revenue Note
Source: Bloomberg, 2026-05-02, AAPL US Equity
Source: Management guidance, Q2 2026 earnings call

出典のないハードコードされた数値は、文書化されていない前提条件です。レビューする人が監査することはできません。

共通ワークフロー

6つのステップです。すべての非自明なビルドはこの形に従います。

1. 開く/保存のライフサイクル。 開始時には officecli open <file>、終了時には officecli save <file> を使用して、ディスクへ書き出します。save は書き込みのみを行い、後続の編集のためにレジデントをウォーム状態のまま保ちます。officecli close <file> は、一度きりの引き渡しでレジデントを解放する場合にのみ使用してください。どちらも常に安全です（エラーになったり作業を失ったりすることはありません）。多数のセルを扱う場合は batch を使用してください。ブロックあたり 50 操作以下を推奨します。純粋な値設定のペイロードでは、ブロックあたり 80 操作以上でも失敗なしで動作することを確認しています。ただし、クロスシート数式のバッチは例外であり、非レジデントで単一のヒアドキュメントとして実行してください（既知の問題を参照）。 フラッシュは officecli の外側の境界でのみ行ってください。 officecli 自身の読み取りでは常に編集内容が反映されます。save/close は、officecli 以外のプログラム（openpyxl/pandas、Excel、レンダラー、納品）がファイルを読み取る直前にのみ実行してください。
2. 作成または読み込み。 新規の場合は officecli create "$FILE"、既存の場合は officecli view "$FILE" outline を実行し、まず全体像を把握してください。
3. 段階的に構築する。 コマンドを 1 つ実行し、出力を読み取ってから次に進みます。構造的な操作（新しいシート、グラフ、名前付き範囲、ピボット）の後は、その上にさらに積み重ねる前に get を実行して形状を確認してください。
4. 書式設定。 列幅、数値形式、ウィンドウ枠の固定、タブの色、ヘッダーの塗りつぶしなどを設定します。書式設定は仕上げの任意作業ではなく、「成果物の要件」に従って納品物の一部です。
5. 保存してキャッシュを確認する。 officecli save <file> でディスクに書き込みます。新しく追加された数式にはキャッシュ値が含まれていません。人間がスプレッドシートアプリでファイルを開くと、アプリが再計算して値を格納します。しかし、下流の INDEX/MATCH、SUMPRODUCT、または上流の数式を参照する数式は、書き込み時点で上流がキャッシュした値（多くの場合 0 や古い値）をそのままキャッシュしてしまい、そのキャッシュされた誤った値は再計算しないリーダーにも残ります。 配列数式（SUMPRODUCT、動的条件の SUMIFS）やクロスシートの連鎖を含む複数の数式を構築した後は、すべての下流セルを再タッチしてください（同じ数式で set を再実行します）。これにより、エンジンが新しくキャッシュされた上流の値から自身のキャッシュを再計算します。⚠️ レジデント経由でのクロスシート連鎖の再タッチは信頼性が低いです（バッチ/レジデントの注意事項を参照）。再タッチには非レジデントの set を使うことを推奨します。その後、下流のセルをいくつか officecli get で確認し、cachedValue= が妥当な値であるかを目視で確認してください。validate はレジデントが開いている状態でも安全で、保留中の編集をディスクにフラッシュします（docx / pptx と同様）。
6. QA — 問題があると想定してください。 QA セクションを参照してください。最後のコマンドが終了コード 0 で完了したからといって作業完了ではありません。修正と検証のサイクルを 1 回行い、新たな問題が 0 件になった時点で完了です。

クイックスタート

最小限の有効な xlsx：3 か月分の売上、合計の数式、列幅、通貨形式。そのままコピー＆ペーストするのではなく、ご自身のファイルとデータに合わせて調整してください。

officecli create "$FILE"
officecli open "$FILE"
officecli set "$FILE" /Sheet1/A1 --prop value=Month --prop bold=true
officecli set "$FILE" /Sheet1/B1 --prop value=Revenue --prop bold=true
officecli set "$FILE" /Sheet1/A2 --prop value=Jan
officecli set "$FILE" /Sheet1/A3 --prop value=Feb
officecli set "$FILE" /Sheet1/A4 --prop value=Mar
officecli set "$FILE" /Sheet1/B2 --prop value=42000 --prop numFmt='$#,##0'
officecli set "$FILE" /Sheet1/B3 --prop value=45000 --prop numFmt='$#,##0'
officecli set "$FILE" /Sheet1/B4 --prop value=48000 --prop numFmt='$#,##0'
officecli set "$FILE" /Sheet1/A5 --prop value=Total --prop bold=true
officecli set "$FILE" /Sheet1/B5 --prop formula="SUM(B2:B4)" --prop bold=true --prop numFmt='$#,##0'
officecli set "$FILE" "/Sheet1/col[A]" --prop width=12
officecli set "$FILE" "/Sheet1/col[B]" --prop width=15
officecli close "$FILE"
officecli validate "$FILE"

検証済み：validate は no errors found を返し、B5 は 135000 に解決されます。これはすべてのビルドの基本形です：開く → セル/数式を設定 → 書式設定 → 閉じる → 検証。

CSV / 一括インポート

ネイティブの import コマンド（CSV/TSV に推奨）。 最も高速な方法で、1 回の呼び出しで CSV をシートに読み込みます。--header は 1 行目にオートフィルタとウィンドウ枠の固定を設定します。列幅と numFmt は後続の作業で設定する必要があります（ダッシュボードスキルの D-12 を参照）。

officecli import "$FILE" /Sheet1 --file data.csv --header
officecli import "$FILE" /Sheet1 --file data.tsv --format tsv --header
officecli import "$FILE" /Sheet1 --stdin --start-cell B2 < data.csv

Python + バッチによる代替方法 — 独自の型変換、数式インジェクションが必要な場合、または CSV が別のデータパイプライン内にある場合に使用します。600〜6000 以上のセル向けのレシピです：

# gen_batch.py — produces batch chunks of 80 value-set ops each
import csv, json
ops = []
with open("data.csv") as f:
    reader = csv.reader(f)
    for r, row in enumerate(reader, start=1):
        for c, val in enumerate(row):
            col = chr(ord('A') + c)
            ops.append({"command":"set","path":f"/Data/{col}{r}",
                        "props":{"value": val}})
for i in range(0, len(ops), 80):
    print(json.dumps(ops[i:i+80]))

python gen_batch.py | while IFS= read -r chunk; do
  printf '%s\n' "$chunk" | officecli batch "$FILE"
done

結果：648 行の小売 CSV（6490 セル）が約 30 秒で読み込まれ、失敗はゼロでした。調整方法：80 操作/チャンクから開始し、チャンクが失敗する場合は 40 に減らしてください。数値の型推論と数式は、後から対象を絞った set で行います。このレシピのバッチは純粋な値の注入です。

Reading & Analysis

まず全体を把握してから絞り込みます。outline で最初にシートの一覧とデータの位置を確認し、位置がわかってから view / get / query を使用してください。

レンダリングされたワークブックを開いて、自分の作業結果を確認します。

• officecli view $FILE html — 返された HTML を読み取り、レンダリング結果を監査します。各シートはアドレス指定が可能で、グラフはインラインで表示されます。###、プレースホルダーの残留、ピボットのレイアウト、行の高さによる表示切れを検出できます。
• officecli watch $FILE は、人間のユーザー向けにライブプレビューを起動したままにします。ユーザーは任意のタイミングでそれを開きます。ユーザーが作業を一緒に確認したい場合に使用します。エージェント自身のセルフチェックには、上記の view html を使用します。 一連の編集を行った後の最初の視覚的確認として view html を使用し、問題は発生源で修正してください。最終的な視覚的検証は、ユーザーが .xlsx を Excel / WPS / Numbers のビューアーで開いて行います。

全体把握。 シート、寸法、数式の数を確認します。

officecli view "$FILE" outline

抽出。 コンテンツの QA や LLM のコンテキスト用にプレーンテキストを出力します。大きなファイルでは --start / --end / --cols で範囲を絞り込みます。

officecli view "$FILE" text --start 1 --end 50 --cols A,B,C

知っておくと便利なその他の view モード: annotated（セルの値、型・数式、警告）、stats（数値の要約）、issues（壊れた数式、空のシート、参照の欠落）。

ラウンドトリップ・ダンプ。 officecli dump "$FILE" [path] は、ワークブック全体、または1つのワークシート（/Sheet1、/sheet[N]）を、再実行可能なバッチ JSON にシリアライズします。officecli batch new.xlsx --input dump.json でそれを再実行します。既存のワークブックの構造を学んだり、テンプレートを複製・調整したりする場合に、生の OOXML を読む代わりに使用してください。対象範囲は dump --help で確認できます。サブツリーのダンプにはワークブックレベルのリソース（設定、名前付き範囲）は含まれないため、再実行先でそれらがすでに定義されている必要があります。

officecli dump "$FILE" -o blueprint.json            # whole workbook
officecli dump "$FILE" /Sheet1 -o sheet.json        # one worksheet
officecli batch new.xlsx --input blueprint.json

1つの要素を確認。 XPath 形式のパスを使用します。シェルが [N] をグロブとして解釈するため、必ず引用符で囲んでください。

officecli get "$FILE" "/Sheet1/A1"            # one cell
officecli get "$FILE" "/Sheet1/A1:D10"        # range
officecli get "$FILE" "/Sheet1/chart[1]"      # chart
officecli get "$FILE" "/Sheet1/table[1]"      # ListObject
officecli get "$FILE" "/namedrange[1]"        # workbook-level named range

子要素を展開するには --depth N を追加し、機械可読な出力には --json を追加します。要素の一覧は officecli help xlsx で確認できます。

ワークブック全体を横断してクエリ。 CSS 風のセレクターを使用します。数式のカバレッジ、エラーセル、空のヘッダーなどの体系的なチェックに使い、手作業で走査しないでください。

officecli query "$FILE" 'cell:has(formula)'       # every formula cell
officecli query "$FILE" 'cell:contains("#REF!")'  # broken references
officecli query "$FILE" 'cell[type=Number]'       # typed filter
officecli query "$FILE" 'Sheet1!B[value!=0]'      # sheet-scoped

演算子: =、!=、~=（含む）、>=、<=、[attr]（存在）。

セル結合のショートカット。 officecli query $FILE merge または mergedrange は、どちらも mergeCell のエイリアスです。<mergeCell> のエントリを手作業で走査することなく、ワークブック内のすべての結合範囲を返します。

データが大きく、行単位の走査が役に立たない場合は、Excel 独自の分析用要素を使用してください。

• officecli add（--type pivottable）でピボットテーブルを作成し、20 個の SUMIF を書くことなくグループ化・集計します。スライサー（--type slicer）を付けると、閲覧者がフィルター用の UI を利用できます。
• 行内にスパークライン（--type sparkline）を配置すると、行ごとの傾向を表示できます。行ごとに折れ線グラフを作成するより安価で、インラインで印刷もされます。type は厳密な列挙型で、line | column | stacked のいずれかを指定します（エイリアスとして winloss / win-loss → stacked があります）。無効な type= の値は、暗黙的に line にフォールバックせず、エラーで失敗します。
• 正確なプロパティ名は officecli help xlsx pivottable、officecli help xlsx slicer、officecli help xlsx sparkline で確認してください。

Creating & Editing

ビルドの9割は、セル、数式、書式設定、そして1〜2個のグラフで構成されます。操作は add（新しい要素の追加）、set（プロパティの変更）、remove、move、swap、batch です。

Cells and formulas

1回の呼び出しで値とその書式を設定します。数式の先頭に = を書かないでください。CLI が自動的に削除します。

officecli set "$FILE" /Sheet1/B5 --prop formula="SUM(B2:B4)" --prop numFmt='$#,##0'
officecli set "$FILE" /Sheet1/C5 --prop formula="B5/A5" --prop numFmt="0.0%"

構造的なプロパティ（幅、高さ、ウィンドウ枠の固定、tabColor）は、row / col / sheet ノードに設定します。

officecli set "$FILE" "/Sheet1/col[A]" --prop width=20
officecli set "$FILE" "/Sheet1/row[1]" --prop height=22
officecli set "$FILE" "/Sheet1" --prop freeze=A2 --prop tabColor=1F4E79

名前付き範囲

数式では $B$6 よりも名前付き範囲を優先してください。名前付き範囲は自己文書化されます（GrowthRate の方が $B$6 よりも分かりやすい）。また、数式を壊さずに前提値のセルを移動できます。ref の値には ! と $ の両方が含まれるため、バッチ用のヒアドキュメントで追加してください:

cat <<'EOF' | officecli batch "$FILE"
[
  {"command":"add","parent":"/","type":"namedrange","props":{"name":"GrowthRate","ref":"Sheet1!$B$6"}}
]
EOF

完全なスキーマについては officecli help xlsx namedrange を参照してください。

バッチ JSON ではシェルのエイリアスは使用できません。 バッチの props 内では、必ず完全なドット区切りの名前を使用してください。例: "font.color": "FF0000"、"font.size": 14。"color": "FF0000" は不可です（テキストか塗りつぶしか曖昧なため）。単独のセルでも、シェル形式は拒否されます。--prop color=1F4E79 は ambiguous in cell context — use 'font.color' (text) or 'fill' (bg) というエラーになります。ルール: バッチ JSON やセルのプロパティでは、必ず font.color / fill を明示的に記述してください。parent はブック全体の要素では "/"、シート単位の要素では "/SheetName" にしてください。空文字列は同等ではありません。

グラフ

グラフの種類は officecli help xlsx chart 以下にあります。列挙値は非常に多い（20種類以上）です。伝えたい内容に合ったものを選んでください。カテゴリ比較には縦棒、時系列には折れ線、円グラフは各スライスが明らかに比率を表す場合のみ、相関には散布図を使います。特定の問いに答えるのでない限り、特殊なグラフの種類は避けてください。

グラフにデータを与える方法は3通りあります。グラフごとにいずれか1つを選んでください。追加時に混在させるのはよくある落とし穴です。

形式	形状	使用する場面
(a) インライン data	--prop data="Sales:100,200,300" --prop categories="Jan,Feb,Mar"	小さなデモ用グラフ、編集しない数値。データの正本はセルではなくグラフの XML 内にあります。
(b) 2次元 dataRange	--prop dataRange="Sheet1!A1:B4"（1列目 = カテゴリ、1行目 = ヘッダー / 系列名）	通常のケースです。必ず2次元である必要があります。単一列は「Chart requires data」で失敗します。
(c) 系列ごとのドット記法	--prop series1.name=Sales --prop series1.values="Sheet1!B2:B4" --prop series1.categories="Sheet1!A2:A4"	各系列が不連続な範囲を指す複数系列グラフ、または系列名を明示したい場合。series1.values のみ（categories なし）の場合、x 軸が 1,2,3 のグラフになります。

単一列の落とし穴。 dataRange="Sheet1!B2:B13" は「値の列」に見えますが、エンジンは Chart requires data でこれを拒否します。範囲をカテゴリ列を含むように広げる（A2:B13）か、明示的な series1.categories を指定した形式 (c) に切り替えてください。

作成後にグラフを移動・サイズ変更: set chart[N] --prop anchor="F5:N25"（--prop x= --prop y= --prop width= --prop height= も可）。系列は依然として変更不可です — 系列を追加・変更するには、officecli remove でグラフを削除し、完全な系列リストを指定して officecli add してください。remove chart[1] を実行すると chart[2] → chart[1] とシフトし、再追加は末尾に追加されます。グラフの順序を保つには、すべて削除してから順番に作り直してください。

アンカーのサイズ。 自動調整はありません。カテゴリ5〜6個と系列2本の縦棒グラフは、すべてのラベルを切れずに表示するには、おおよそ A5:L22（12列 × 18行）が必要です。これより狭いと X 軸ラベルが切れ、広すぎると印刷・エクスポート時にグラフがページをまたぐことがあります。迷ったら狭めに始め、view html でプレビューし（返された HTML パスを読み込む）、少しずつ広げてください。下記のページレイアウトが、修正のもう半分になります。

グラフの dataRange — 必ずシート名を前置してください。 グラフが同じシート上にある場合でも、A17:C22 ではなく dataRange="Summary!A17:C22" と記述してください。シート名のない形式は動作が一定しませんが、前置した形式は100%確実です。

officecli には、従来の Excel オブジェクトモデルにはない拡張グラフ種類があります: boxWhisker、waterfall、funnel、histogram、treemap、sunburst、pareto。データがそれを必要とする場合に使用してください。

グラフのタイトル / 系列名 / 凡例 / 軸タイトルに、置換されていないテンプレートトークンを残さないでください。 $fy$24、{var}、<TODO>、$VAR、{{placeholder}} は凡例にそのまま表示されます。検証は通りますが、本来 "FY2024" と表示されるべき箇所に CFO が $fy$24 を目にすることになります。必ず最終的な文字列またはセル参照に紐付けてください（title="FY2024 Revenue" または series1.name="Sheet1!A1"）。

条件付き書式

よく使われる 3 種類があり、それぞれ固有のプロパティ形式を持ちます(詳細は officecli help xlsx cf を参照してください)。

• カラースケール: 値に応じてグラデーションでセルに色を付けます — type=colorscale と minColor / midColor / maxColor を使います。
• データバー: セル内に大きさを示すバーを表示します — type=databar。列全体で統一したスケールにするには明示的に min / max を設定します。省略した場合はデフォルト値が有効です。
• 数式ルール(formulacf 要素): 条件が真のときに行を強調表示します — type=formula と formula="$C2>1000"、および塗りつぶしやフォントを指定します。

ルール: 条件付き書式は控えめに使ってください。すべてのセルに色が付いたブックは、読み手に何も伝えません。

データの入力規則

トラッカーやテンプレートの入力セルには、必ずデータの入力規則を設定してください。設定の手間は小さく、下流で発生する多くの種類のバグを防げます。許可される値がどこにあるかに応じて、リストソースの 3 つのパターンから選んでください。

(a) インラインリスト — 許可される値が短く、ルール内で固定されている場合。

officecli add "$FILE" /Sheet1 --type validation \
  --prop sqref="C2:C100" --prop type=list \
  --prop formula1="Yes,No,Maybe" \
  --prop showError=true --prop errorTitle="Invalid" --prop error="Select from list"

(b) 名前付き範囲(別シートの参照で推奨) — 許可される値が別のシートにあり、増える可能性がある場合。先に名前付き範囲を定義してから参照します。ref に ! と $ が含まれるため、バッチのヒアドキュメントを使用してください。

cat <<'EOF' | officecli batch "$FILE"
[
  {"command":"add","parent":"/","type":"namedrange","props":{"name":"StatusList","ref":"Lookups!$A$2:$A$4"}},
  {"command":"add","parent":"/Sheet1","type":"validation","props":{"sqref":"B2:B100","type":"list","formula1":"=StatusList"}}
]
EOF

(c) 別シートの範囲を直接指定 — 名前付き範囲を使わず、formula1 内に Lookups!$A$2:$A$4 をそのまま記述します。! と $ を正しく保つために、やはりバッチのヒアドキュメントが必要です。

cat <<'EOF' | officecli batch "$FILE"
[
  {"command":"add","parent":"/Sheet1","type":"validation","props":{"sqref":"C2:C100","type":"list","formula1":"Lookups!$A$2:$A$4"}}
]
EOF

別シートを参照するバリアントを、シェル上で --prop formula1=... として書くと、! がシェルによって \! にエスケープされ、ドロップダウンリストが何も表示されないまま静かに失敗します。officecli get "$FILE" /Sheet1/validation[N] で確認してください。formula1= にはバックスラッシュのない通常の ! が表示されている必要があります。

その他によく使われる type の値: decimal、whole、date、textLength、custom。演算子と全プロパティの一覧は officecli help xlsx validation を参照してください。

その他の要素(簡単な説明)

• テーブル(ListObjects) — 範囲を指定して add --type table を実行します。オートフィルターと構造化参照が使えるようになります。officecli help xlsx table。
• コメント — add --type comment を使います。ハードコードされた前提条件を記録するのに役立ちます。officecli help xlsx comment。
• シートの並べ替え — swap ではなく officecli move を使います。swap は行・セルのパスでのみ動作します。
• 隣接する行・列の書式を引き継いで新しい行・列を追加 — add "$FILE" /Sheet1 --from "/Sheet1/row[5]" --index 5 を実行すると、塗りつぶし、フォント、数式がコピーされます(参照は自動的にずれます)。add --type row は書式なしの空行を挿入します。

役割によるチャート軸の指定

チャートを作り直すより、チャートの軸をその場で編集する方が手間がかかりません。軸はインデックスではなく役割(value = Y 軸、category = X 軸)で指定してください。XML 内の順序は安定していないためです。

officecli get "$FILE" "/Sheet1/chart[1]/axis[@role=value]"
officecli set "$FILE" "/Sheet1/chart[1]/axis[@role=value]" --prop min=0 --prop max=100000
officecli set "$FILE" "/Sheet1/chart[1]/axis[@role=category]" --prop title="Month"

安全に使えるプロパティ: title、min、max、majorGridlines、visible、labelRotation。

QA(必須)

問題があると想定してください。あなたの仕事はそれを見つけることです。

最初に作成したブックが正しいことはほとんどありません。QA は確認作業ではなく、バグを探す作業として扱ってください。初回の確認で問題が 1 件も見つからなかったとしたら、十分に注意深く見ていなかったということです。数式は、元となるセルと 2 つ照合するまでは正しく見えるものです。

「完了」とみなすまでの最小サイクル

1. officecli view "$FILE" issues — 空のシート、壊れた数式、欠落した参照を確認します。
2. officecli view "$FILE" annotated（サンプルの範囲を指定）— 値、型、警告を確認します。
3. Excel のエラーの種類ごとに、次のように照会します：

   officecli query "$FILE" 'cell:contains("#REF!")'
   officecli query "$FILE" 'cell:contains("#DIV/0!")'
   officecli query "$FILE" 'cell:contains("#VALUE!")'
   officecli query "$FILE" 'cell:contains("#NAME?")'
   officecli query "$FILE" 'cell:contains("#N/A")'
   

4. officecli validate "$FILE" — 常駐の開いたセッションがあっても安全です。validate は保留中の編集を自動的にディスクへ書き出します。
5. 目視確認 — HTML プレビューで全シートを確認します。 officecli view "$FILE" html を実行し、返された HTML のパスを Read します。各シートはグラフをインラインで描画した状態で表示されます。###、切り詰められたタイトル、プレースホルダートークン（$fy$24、{var}、<TODO>）、途切れたグラフ、白いスライスの円グラフ、空のグラフのアンカーがないかを確認してください。問題があれば停止して修正してから完了を宣言してください。 「validate が通った」は納品ではありません。「プレビューが実際のワークブックらしく見える」ことが納品です。人間向けのプレビューには officecli watch "$FILE" を実行します（ユーザーが任意のタイミングでライブプレビューを開きます）。または、ユーザーに .xlsx を Excel / WPS / Numbers で直接開いてもらいます。
6. 印刷レイアウトの修正（幅の広い表・複数グラフのシート）。 シートにグラフや幅の広い表が含まれ、ユーザーがそれを印刷する場合は、シートごとにページレイアウトを設定してください。ただし、フィットモードはシートの高さに合わせてください：

   # Short summary / chart sheet → fit to one page.
   officecli set "$FILE" "/Summary" --prop orientation=landscape --prop fitToPage=true
   # Tall data table → fit width only (fitToPage=true would crush all rows onto one unreadable page).
   officecli set "$FILE" "/Data" --prop orientation=landscape --prop fitToPage=1x0
   

   結果：グラフや幅の広い表がグラフの途中で分割されずに印刷され、縦長の表は自然な改ページをまたいでも読みやすい状態が保たれます。グラフまたは 8 列を超える表を含むすべてのシートに適用してください。
7. 失敗した項目があれば修正してから、完全なサイクルを再実行します。ある修正が別の問題を引き起こすことはよくあります。

officecli view issues と view html は構造面の QA の組み合わせです。issues は壊れた数式と空のシートを検出し、view html（返された HTML のパスを Read）は ###、切り詰め、トークンの残留を検出します。グラフの塗りつぶし色やテーマのティントは、ビューアーによって異なる場合があります。色の再現性が重要な場合は、ユーザーの利用するビューアーで確認してください。

数式検証チェックリスト

• 数式をランダムに 2〜3 個選びます。それぞれに officecli get を実行します。数式の文字列が意図どおりであること、そして cachedValue= が期待どおりであることを、頭の中で計算して確認します。
• 集計セルのキャッシュ値の妥当性確認。 集計を行うセル（COUNTA / COUNTIF / SUMPRODUCT / INDEX&MATCH）は、もっともらしい cachedValue を持っている必要があります。空のテンプレートで進捗トラッカーが 199 / 199 / 100% と表示されている場合、キャッシュは誤っています。set で数式を再設定して再計算を強制するか、正しいキャッシュ値を手動で設定してください。「validate は通るが数値が架空」という状態のまま出荷しないでください。
• 数値列ごとに 1 セルを抽出して確認。 % 列がすべて整数の 0.0% になっている場合、分母が誤っているか、分子のキャッシュが古くなっています。1 セルを調べて、パターンを修正してください。
• 範囲がすべての行を含んでいることを確認します。データが B13 まである場合に SUM(B2:B12) とするような off-by-one エラーが最もよくあるバグです。
• シートをまたぐ数式（Sheet1!A1）に \! が含まれていないことを確認します。officecli get で Sheet1\!A1 と表示される場合は、シェルによって ! が破損しています。削除し、バッチまたはヒアドキュメントで入力し直してください。
• 名前付き範囲（officecli get "$FILE" "/namedrange[1]"）が、その名前が示す対象を指していることを確認します。
• すべての / の分母は保護されていること（IFERROR(x/y, 0) または IF(y=0, 0, x/y)）を確認します。
• グラフのデータとソースセルの照合：インラインデータを持つすべてのグラフについて、データポイントを元のセルの officecli get の結果と照合して確認します。
• グラフのタイトル、系列名、凡例に、置換されていないトークン（$...$、{var}、<TODO>）が含まれていないことを確認します。officecli get /Sheet1/chart[N] でグラフを検索してください。

テンプレートの QA

テンプレートを編集する場合は、残ったプレースホルダーを確認してください。プレースホルダーは内容のように見えるため、validate をすり抜けることがあります：

officecli query "$FILE" 'cell:contains("{{")'
officecli query "$FILE" 'cell:contains("xxxx")'
officecli query "$FILE" 'cell:contains("TBD")'

第三者の目で確認

ワークブックが完成したら、新たな目で開き直してください。新しいレビュアーになったつもりで、view text や HTML プレビューを先頭から末尾まで読み、数式、おかしく見える数値、書式の不統一、欠落したデータがないかを確認します。

検証の限界

validate が検出するのはスキーマのエラーであり、設計上のエラーは検出できません。すべての数値が誤っていても、ワークブックは validate を通過することがあります。上記のチェックリスト、特に数式を元のセルと照合する確認が、検証では捕捉できない問題を見つける方法です。

既知の問題と注意点

クロスシートの ! の落とし穴（要点）

シェル（bash の履歴展開、zsh の分割）や CLI の引数解析は、Sheet1!A1 の ! を \! に変えてしまいます。\! を含む数式は黙って壊れ、リテラルのテキストとして表示され、どのセルも参照しません。

修正方法。 区切り文字を単一引用符で囲んだバッチ用ヒアドキュメント（<<'EOF'）を使用してください。これによりシェルによる展開がすべて無効になります:

cat <<'EOF' | officecli batch "$FILE"
[{"command":"set","path":"/Summary/B2","props":{"formula":"Revenue!B13"}}]
EOF

検証。 書き込み後、セルに対して officecli get を実行し、formula= にバックスラッシュのない通常の ! が表示されることを確認してください。

CLI のバグと未対応事項（要点）

回避すべき CLI の制約と不足機能であり、出力ファイルの欠陥ではありません。

• グラフのシリーズは作成後に変更できません — シリーズを追加・変更するには、シリーズの完全なリストを指定して remove と add を実行します。（位置は変更可能です: set chart[N] --prop anchor= または x/y/width/height。）remove chart[N] の後、後続のインデックスは詰められ、再追加した要素は末尾に追加されます。
• シート間の数式バッチは常駐プロセスで正常に動作します — 以前の「3〜5 件の操作でもデッドロックする」という注意はもう再現しません。値の設定のみのバッチは 50〜80 件以上でも安定して動作します。万一ハングした場合は、非常駐プロセスで一括のバッチを実行するか、個別に set を実行してください。同じファイルやマシン上で複数の常駐プロセスが競合する可能性は依然としてあります — 別のエージェントやセッションが同じファイルで常駐プロセスを保持している場合、非決定的なハングが発生することがあります。
• 条件付き書式の名称の非対称性 — --type で指定する要素名は conditionalformatting ですが、パスの接尾辞は /cf[N] です。スキーマについては officecli help xlsx conditionalformatting を、パスには /cf[N] を使用してください。
• 追加時のシートの position プロパティ — ヘルプでは Add が position を処理するとありますが、このプロパティは無視されることがよくあります。シートを作成した後に officecli move --index / --after / --before で並べ替えてください。
• remove /sheet[N] のカスケードガード — 別のシートにある入力規則、条件付き書式、スパークライン、ハイパーリンク、または名前付き範囲から参照されているシートの削除・名前変更は拒否されます。先に依存する要素を削除してから、シートを削除してください。
• バッチ JSON はセルの color エイリアスを受け付けません — バッチの props 内で "color": "FF0000" と指定すると、ambiguous in cell context — use 'font.color' (text) or 'fill' (bg) というエラーになります。シェルレベルの CLI では、セル以外の要素に対して --prop color=... や --prop size=14 がエイリアスとして受け付けられますが、バッチ JSON でセルを指定する場合は、必ず "font.color"、"font.size"、"font.name" のように完全なドット区切りの名前を記述してください。

レンダラーの注意点（ビューア間の色の再現性）

officecli view html は構造的な QA（オーバーフロー、切り詰め、プレースホルダーの残留、レイアウト）に適したツールです。返された HTML のパスを Read してください。一部のグラフの描画の詳細は、エンドユーザーがファイルを開くビューアによって異なります。確認された相違点は次のとおりです:

• 円グラフ／ドーナツグラフの塗りつぶし色が、一部のビューアで単一のテーマ色に統一されることがあります（スライスがすべて白や同一色に見える）。ユーザーの対象ビューアでは問題ない場合があります。
• 折れ線グラフ／縦棒グラフのシリーズの色が、一部のビューアでブックのテーマから外れることがあります。
• フォームコントロールのチェックボックスが、一部のビューアで二重の枠で描画されることがあります。

色やグラフが「壊れている」と判断する前に、ユーザーが実際に使用する対象ビューアでファイルを開いてください。そこで正しく表示される場合、問題はデータではなくビューアの描画によるものですので、追いかける必要はありません。CLI の構造チェック（###、切り詰め、プレースホルダーのテキスト、レイアウト）が引き続き正式な判定基準です。

エスケープの階層（シェルのクォートは上記のとおり。以下は追加の階層）

$ はシェルのレイヤーです（上記のとおり単一引用符で囲んでください）。プロパティ値内の \n / \t は CLI によって実際の改行／タブとして解釈されます。さらに次の2つの階層があります:

• JSON レベル（バッチ）。 標準的な JSON エスケープ（"\n"、"\t"、"\""）を使用します。最終的な文字列に実際のバックスラッシュを含める場合は "\\\\" と記述します。
• Excel レベル。 セル内の \n は実際の改行になります。Excel で折り返しを表示させるには --prop wrapText=true と組み合わせてください。シェルで引用したプロパティには直接指定できます（--prop value='a\nb'）。バッチ JSON 内の "\n" でも同じ結果になります。不明な場合は、officecli get でセルを取得し、文字単位で比較してください。

その他のよくある落とし穴

落とし穴	対処法
--name "foo"	すべての属性は --prop で指定します: --prop name="foo"
プロパティ名の推測	officecli help xlsx <element> を使用してください。推測で入力しないでください
セルに対する --prop color=...	曖昧です。テキストには font.color、背景には fill を使用してください。バッチ JSON 内でも同様で、必ず完全なドット区切りの名前を使用し、シェルのエイリアスは使用しないでください
#FF0000 形式の16進数カラー	# を取り除いてください: FF0000
--index と [N]	--index は 0 始まり（配列）、[N] のパスは 1 始まり（XPath）です
zsh/bash で [N] をクォートしない	すべてのパスをクォートしてください: "/Sheet1/row[1]"
シート名にスペースがある	パス全体をクォートしてください: "/My Sheet/A1"
年が 2,026 と表示される	--prop type=string または numFmt="@" を指定してください
Excel で開いているファイルを変更する	先に Excel でファイルを閉じてください
swap でシートの順序が変わらない	swap は行やセル用です。シートには move --after / --before / --index を使用してください
書き込み後にキャッシュ値がない	新しい数式のキャッシュ値は、人がファイルを開いたときに生成されます。validate はどちらの場合も受け入れます