confluence

orbit CLI を使用した Confluence

orbit CLI を使用して、Confluence ページを管理し、Markdown ドキュメントを公開し、ページレイアウトを制御します。REST API を介して Confluence Cloud と Server／Data Center に対応し、複数プロファイルのサポートと 1Password によるシークレット解決機能を備えています。

前提条件

1. orbit CLI がインストールされていること — which orbit が失敗する場合は、次の方法でインストールします。
   • macOS/Linux（Homebrew）： brew install jorgemuza/tap/orbit
   • macOS/Linux（スクリプト）： curl -sSfL https://raw.githubusercontent.com/jorgemuza/orbit/main/install.sh | sh
   • Windows（Scoop）： scoop bucket add jorgemuza https://github.com/jorgemuza/scoop-bucket && scoop install orbit
2. ~/.config/orbit/config.yaml で confluence-cloud または confluence-server サービスが設定されたプロファイル
3. 有効な認証情報（Cloud の場合は API トークン、Server の場合は PAT）。1Password（op://）または Infisical（infisical://）の参照として保存できます。
4. Cloud の場合、認証タイプは basic とし、ユーザー名にメールアドレス、パスワードに API トークンを指定します。

クイックリファレンス

すべてのコマンドは次の形式に従います：orbit -p <profile> confluence <command> [flags]

コマンドとフラグの詳細については、references/commands.md を参照してください。 Confluence ストレージ形式（XHTML）の詳細については、references/storage-format.md を参照してください。

主なワークフロー

ページの表示

# View page details
orbit -p myprofile confluence page 473676972036

# View as JSON (includes body content)
orbit -p myprofile confluence page 473676972036 -o json

# List child pages
orbit -p myprofile confluence children 473676972036

# Show full page hierarchy (ancestors + descendants tree)
orbit -p myprofile confluence hierarchy 473676972036

# Deeper tree (default depth is 2)
orbit -p myprofile confluence hierarchy 473676972036 --depth 5

# JSON tree output
orbit -p myprofile confluence hierarchy 473676972036 -o json

ページのレビュー（コメント）

ページを開かずに、CLI から直接ページにレビューコメントを追加できます。公開済みドキュメントにフィードバックを残すときに便利です。

# List all comments on a page (footer + inline, including replies)
orbit -p myprofile confluence comment list 473676972036
orbit -p myprofile confluence comment list 473676972036 -o json

# Add a comment (body is Markdown by default)
orbit -p myprofile confluence comment add 473676972036 --body "LGTM, but the sandbox URL is stale."

# Add a multi-line/Markdown review from a file
orbit -p myprofile confluence comment add 473676972036 --from-file review.md

# Reply to an existing comment (thread)
orbit -p myprofile confluence comment add 473676972036 --body "Fixed in v0.60.2" --reply-to 67890

# Anchor an inline comment to specific page text (Confluence Cloud; best-effort)
orbit -p myprofile confluence comment add 473676972036 \
  --body "This line is inaccurate — deploys are on-demand, not nightly." \
  --inline-text "deploys run nightly"

# Delete a comment (prompts in a terminal; use --yes in scripts/CI)
orbit -p myprofile confluence comment delete 67890 --yes

インラインアンカーはベストエフォートで、Cloud のみ対応です。 --inline-text はページのテキストと完全に一致する必要があり、一致しない場合はサーバーに拒否されます。確実でない場合は省略して、コメント本文に該当行を引用してください。フッターコメントなら Server と Cloud のどちらでも 100% 確実です。

ページの検索

# Search by space
orbit -p myprofile confluence search --space FO

# Search by title (fuzzy match)
orbit -p myprofile confluence search --space FO --title "Architecture"

# Search by label
orbit -p myprofile confluence search --space FO --label design

# Full-text search
orbit -p myprofile confluence search --space FO --text "deployment pipeline"

# Raw CQL query
orbit -p myprofile confluence search --cql 'space=FO AND label=design AND type=page'

# Increase result limit (default 25)
orbit -p myprofile confluence search --space ISMS --limit 100

Markdown からのページ作成

Markdown ファイルからページを作成すると、CLI は自動的に Confluence ストレージ形式（XHTML）に変換します。変換機能は、見出し、リスト、表、コードブロック、引用、インライン書式、画像に対応しています。

# Create page from markdown file
orbit -p myprofile confluence create --space FO --parent 473677299713 \
  --title "My New Page" --file docs/overview.md

# Create page with inline body (storage format XHTML)
orbit -p myprofile confluence create --space FO --parent 473677299713 \
  --title "Quick Page" --body "<p>Hello world</p>"

ページは自動的にワイド幅（全幅レイアウト）で作成されます。

既存ページの更新

--file を指定すると、update コマンドはフロントマターからタイトルを自動的に読み取り、confluence_labels のラベルを同期し、confluence_properties のページプロパティを先頭に追加して、全幅レイアウトに設定します。これは publish コマンドと同じ動作です。フロントマターのタイトルを上書きするには、--title を使用します。

# Update page from markdown (title, labels, properties auto-synced)
orbit -p myprofile confluence update 473676972036 --file docs/overview.md

# Override title explicitly
orbit -p myprofile confluence update 473676972036 \
  --title "Custom Title" --file docs/overview.md

# Update with inline storage format
orbit -p myprofile confluence update 473676972036 --body "<p>New content</p>"

Markdown ファイルのディレクトリを公開

publish コマンドは、Markdown ファイルのディレクトリ全体を再帰的に Confluence ページに変換し、フォルダー階層を保持します。

• INDEX.md ファイルは、そのディレクトリの親ページになります。
• その他の .md ファイルは、ディレクトリの親ページの子ページになります。
• サブディレクトリは再帰的に処理されます。
• ページタイトルは、フロントマターの title:、最初の # heading、またはファイル名から取得されます。
• confluence_ignore: true が設定されたファイルはスキップされます。以前に公開済みの場合、対応する Confluence ページは削除されます。INDEX.md が無視されると、そのサブディレクトリ全体がスキップされます。
• アップサート動作： フロントマターに confluence_page_id がないページは、まずタイトルで検索されます。タイトルの競合（タイトルに & などの特殊文字が含まれている場合など）で作成に失敗すると、親ページの子ページを一覧表示し、一致するページを更新します。成功すると、以降の実行に備えて confluence_page_id がフロントマターに書き込まれます。
• すべてのページは、作成時および更新時に全幅レイアウトに設定されます。

# Publish entire docs directory
orbit -p myprofile confluence publish ./docs --space FO --parent 473677299713

# Preview what would be created (no API calls)
orbit -p myprofile confluence publish ./docs --space FO --parent 473677299713 --dry-run

ダイアグラムのレンダリング

ダイアグラム言語を指定したフェンス付きコードブロックは、Kroki を介して自動的に画像としてレンダリングされます。Confluence プラグインは不要です。別のインスタンスを設定しない限り、公開されている https://kroki.io がレンダリングに使用されます（下記のレンダリングに使用する Kroki の選択を参照）。対応言語：mermaid、plantuml、graphviz、dot、d2、ditaa、erd、nomnoml、svgbob、vega、vegalite、wavedrom、pikchr、structurizr、excalidraw、c4plantuml。

```mermaid
graph LR
    A-->B
    A-->C
```

これは、クリックするとフル解像度の画像を開くPNG画像として表示されます（幅は最大600px、高さは最大800pxで、自動的に拡大縮小されます）。通常のコードブロック（python、go、bashなど）には影響しません。Krokiが図を拒否した場合（構文エラー）、構文強調表示付きのコードブロックにフォールバックします。

図のレンダリング方法の選択。 --diagramsは実行全体に適用する3つの方式から選択します。ファイルのフロントマターにあるconfluence_diagramsはそのファイルに適用する方式を、Confluenceサービスのoptions.diagramsはインスタンスに適用する方式を選択します。選択肢は1つだけで、最も具体的な指定が優先されます。優先順位は、実行時、ファイル、インスタンス、デフォルトの順です。

方式	動作
kroki	すべての図をKrokiインスタンスからPNGとしてレンダリングします。デフォルトです。
markdown-macro	mermaidをConfluenceのmarkdownマクロで囲みます。このマクロはアプリが閲覧者のブラウザーでレンダリングするため、図はConfluence上でライブのまま、ベクター形式で編集可能です。Krokiには一切接続しません。Krokiの場所にかかわらず、ほかの図の言語はコードブロックのままにし、外部には送信しません。ライブインスタンスでは.language-mermaidだけがアプリのmermaid.initを受け、ほかの図をレンダラーに送信するとこの方式を選ぶ理由が失われるためです。レンダリングしたい場合は、ファイルごと、または実行ごとにkrokiを指定してください。
code-block	すべての図を整形済み（ASCII）テキストのままにし、何も呼び出しません。

markdown-macroがデフォルトになることはありません。このマクロは、すべてのConfluenceにインストールされているわけではないアプリが提供するもので、インスタンスにないマクロを含むページでは、図が表示されるはずの場所にエラーが表示されます。インスタンスでそのマクロが使える場合は、サービスにoptions.diagrams: markdown-macroを設定してください。これは個々の公開ではなく、Confluenceの属性だからです。この方式では図のソースはそのまま渡されます。以下のサニタイズが適用されるのはKroki経由の場合のみです。

--no-krokiとconfluence_disable_kroki: trueは引き続き使用でき、どちらもcode-blockを意味します。同じ場所で指定したオプション名どうしの設定が食い違う場合（--no-krokiと--diagramsの組み合わせ、またはconfluence_disable_krokiとconfluence_diagramsの組み合わせ）は、どちらかが黙って優先されるのではなくエラーになります。認識されない方式名も同様です。ある階層の設定が別の階層の設定を上書きしても競合ではありません。それが階層を設けている理由です。これらは<details>ブロック内の図にもすべて適用されます。

レンダリングに使用するKrokiの選択。 実行時に別のインスタンスが指定されない限り、図はhttps://kroki.ioに送信されます。優先順位は、最も具体的な設定から順に次のとおりです。

1. publish、create、updateで指定する--kroki-url <url> — 実行ごとに指定する通常のURLです。
2. Confluenceサービスで指定するoptions.kroki_service: <name> — 同じプロファイル内のtype: kroki接続を指定します。認証、プロキシ、またはこのマシンが信頼しない証明書（tls_skip_verify）が必要なインスタンス向けです。http_timeoutは図ごとの制限時間（デフォルトは30秒）、options.concurrencyは同時にレンダリングする数（デフォルトは4）です。
3. Confluenceサービスで指定するoptions.kroki_url: <url> — 認証不要で、有効な証明書を持つ通常のURLです。
4. https://kroki.io

1つのサービスでkroki_serviceとkroki_urlの両方を指定すると、優先順位の問題ではなくエラーになります。これらは同じ設定を表す2つの名前だからです。インスタンス用のフロントマターキーはありません。どのレンダラーに接続できるかは、ドキュメントではなく環境の属性です。orbit service ping <name>を実行すると、ほかのサービスと同様にkroki接続を確認できます。詳細なリファレンス：docs/confluence.md。

Mermaid図はレンダリング前に自動でサニタイズされ、よくあるKrokiとの互換性の問題が修正されます。

• <br/>タグを削除します（. に置き換えます）
• 参加者エイリアスの括弧付き接尾辞を変換します：Worker (queue) → Worker - queue
• 参加者名の末尾にある()を削除します
• コロンの後に続くポート番号を削除します：API:8000 → API
• 逆向きの矢印を反転します：Client<<--API: msg → API-->>Client: msg Confluence に公開する Mermaid 図を作成する際は、以下を避けてください：
• 参加者名や注記内の HTML タグ（<br/>）
• 参加者のエイリアステキスト内のコロン（例：API:8000）
• 参加者のエイリアス内の丸括弧（例：Worker(queue)）
• エイリアス内の関数呼び出し構文（例：dispatch()）
• 逆向きの矢印（<<--）— Mermaid がサポートするのは左から右への矢印のみです
• ASCII の罫線文字 — 代わりに Mermaid の正しい構文を使用してください
• エッジラベル |...| 内の引用符で囲まれていない [ ] ( ) — Mermaid のパーサーはこれらを図形の開始文字として解釈し、Expecting 'SQE' / 'PE' エラーで失敗します。ラベル全体を二重引用符で囲んでください：A -->|"secrets[].valueFrom"| B および A -->|"on_end (already shaped)"| B。自動サニタイザーでは修正されません。

Kroki のレンダリングに失敗した場合は、推測する前に問題のブロックを特定してください。 orbit CLI は、どの図が原因かを示さずに Kroki failed to render mermaid diagram と表示します。原因を特定するには、各ブロックを Kroki に直接 POST し、実際の解析エラーを確認してください。エラーメッセージ内の行番号は、Markdown ファイル内ではなく、図の本文内の行を示します。公開に使用するインスタンスに POST してください（以下の URL は公開インスタンスのものです。プロファイルで別のインスタンスが指定されている場合は、インスタンス間でレンダラーのバージョンが異なるため、その URL に置き換えてください）：

python3 - <<'PY'
import re, json, subprocess
text = open("path/to/doc.md").read()
for m in re.finditer(r"```mermaid\n(.*?)```", text, re.DOTALL):
    ln = text[:m.start()].count("\n") + 1
    payload = json.dumps({"diagram_source": m.group(1), "diagram_type": "mermaid", "output_format": "svg"})
    r = subprocess.run(["curl","-sS","-w","\n%{http_code}","-H","Content-Type: application/json",
                        "--data-binary", payload, "https://kroki.io/"],
                       capture_output=True, text=True, timeout=30)
    body, code = r.stdout.rsplit("\n", 1)
    print(f"L{ln}: {'OK' if code=='200' else 'FAIL '+code+' '+body[:300]}")
PY

注：公開 kroki.io に対して Python の urllib を使用しないでください。Cloudflare がデフォルトの UA を error code: 1010 でブロックします。curl（上記のとおり）を使用するか、ブラウザーの User-Agent ヘッダーを設定してください。セルフホストのインスタンスでは通常、このような制限はありません。

ページのエクスポート

# Export page as markdown (default)
orbit -p myprofile confluence export 12345

# Export to a directory
orbit -p myprofile confluence export 12345 --format markdown --output docs/

# Export raw storage format
orbit -p myprofile confluence export 12345 --format storage --output backup/

ページの移動／親ページの変更

リポジトリの構成変更に伴って Markdown ファイルを新しいディレクトリに移動しても、公開済みの Confluence ページは親ページを変更するまで元の親ページの下に残ります。ページ本文やタイトルを変更せずに親ページを更新するには、move を使用してください。

# Move page 895422142 under a new parent
orbit -p myprofile confluence move 895422142 --parent 878970411

新しい親ページは同じスペース内にある必要があります。Confluence は、スペースをまたぐ移動や循環する移動（ページをその子孫の下に移動すること）を拒否します。

ページ幅の設定

# Set single page to wide
orbit -p myprofile confluence set-width 473676972036

# Set page and all children to wide
orbit -p myprofile confluence set-width 473676972036 --recursive

# Set to fixed width
orbit -p myprofile confluence set-width 473676972036 --width fixed

Markdown フロントマターによる追跡

Confluence 向けに Markdown ファイルを公開または変換する際は、YAML フロントマターを使用してローカルファイルと Confluence ページの対応関係を追跡してください。ページの作成または更新後、ソース Markdown ファイルのフロントマターを以下のように更新します：

---
title: "My Page Title"
confluence_ignore: false
confluence_page_id: "473676972036"
confluence_url: "https://mysite.atlassian.net/wiki/spaces/FO/pages/473676972036/My+Page+Title"
---

これにより、以下が可能になります：

• ページ ID を調べずに更新を再実行する
• 公開済みのファイルを追跡する
• ローカルの変更を Confluence に同期するスクリプトを作成する
• confluence_ignore: true を指定してファイルを Confluence から除外する（公開済みのページを削除します）

ユーザーから Markdown ファイルの Confluence への公開または同期を依頼された場合：

1. orbit コマンドを実行してページを作成／更新する
2. 出力からページ ID と URL を取得する
3. Markdown ファイルのフロントマターを confluence_page_id と confluence_url で更新する
4. フロントマターが存在しない場合は、ファイルの先頭に追加する

ファイルを同期するワークフローの例：

# If confluence_page_id exists in frontmatter, update (title auto-read from frontmatter):
orbit -p myprofile confluence update 473676972036 --file docs/overview.md

# If no confluence_page_id, create new:
orbit -p myprofile confluence create --space FO --parent 473677299713 \
  --title "Overview" --file docs/overview.md
# Then update the frontmatter with the returned page ID and URL

ページプロパティとラベル

publish コマンドは、フロントマターを介して Confluence のページプロパティマクロとラベルに対応しており、動的なページプロパティレポート表（ISMS Policies ページのパターンなど）を利用できます。

ラベル（タグ）

ページにタグを付けるには、フロントマターに confluence_labels を追加します。ラベルは、publish の実行中にページを作成または更新するたびに適用されます。

---
title: "My Policy"
confluence_labels:
  - ai-process
  - foundation
---

ページプロパティ（details マクロ）

フロントマターに confluence_properties を追加すると、ページの先頭に Confluence のページプロパティマクロを生成できます。これにより、他のページにあるページプロパティレポートマクロからクエリできる、構造化されたメタデータブロックが作成されます。

---
title: "Compounding Engineering & System Evolution"
confluence_properties:
  id: status
  fields:
    Owner: AI Tooling Guild
    Classification: Internal
    Status: "{status:Green|approved}"
    Reviewed on: 2026-03-06
    Approved on: 2026-03-06
---

• id -- マクロ ID を設定します（detailssummary レポートで、特定のプロパティブロックを対象にするために使用します）
• fields -- マクロ内の 2 列テーブルとして表示される、順序付きのキーと値のペアです
• {status:Color|Text} に一致する値はステータスバッジマクロに変換されます（:green_circle: Green のような絵文字ショートコードにも対応しています）
• YYYY-MM-DD に一致する値は、Confluence の <time> 日付マクロに変換されます
• その他の値はプレーンテキストとして表示されます

ページプロパティレポート（detailssummary マクロ）

Markdown にディレクティブを追加すると、ラベル付きページからページプロパティを取得する動的なテーブルを生成できます。次の 2 つの形式に対応しています。

HTML コメント形式（細かな制御が可能）：

省略形式：

{properties-report: label="ai-process", columns="Status, Classification, Reviewed on"}

パラメーター：

• cql -- ページを検索する CQL クエリ（例：label = "policy" and space = currentSpace()）
• label -- CQL の省略形式です。label = "value" and space = currentSpace() を生成します
• firstcolumn -- 最初の列の名前です（デフォルトは「タイトル」）
• columns / headings -- 列として表示するプロパティ名をカンマ区切りで指定します
• sortBy -- 並べ替えに使用する列を省略可能な形で指定します

完全な例

子ページ（例：overview.md）：

---
title: Overview & Philosophy
confluence_labels:
  - ai-process
confluence_properties:
  id: status
  fields:
    Owner: AI Tooling Guild
    Classification: Internal
    Status: "{status:Green|approved}"
    Reviewed on: 2026-03-06
---

インデックスページ（例：INDEX.md）：

---
title: AI Development Process
confluence_labels:
  - ai-process
---

# AI Development Process





| Document | Version | Summary |
|----------|---------|---------|
| [Overview & Philosophy](./overview.md) | v2.0 | Core principles, four layers |

Confluence では、プロパティレポートマクロのみが表示されます（静的なテーブルは無視されます）。Markdown ビューアー（GitHub、ローカル）では、静的なテーブルが HTML コメントのディレクティブ（表示されません）とともに表示されます。

Markdown から Confluence への変換

コンバーターは以下の変換に対応しています。

Markdown	Confluence Storage Format
# Heading（最初のもの）	スキップされます。Confluence ではページタイトルが表示されます
## Heading から ###### Heading	<h2> から <h6>
**bold**	<strong>
`code`	<code>
~~strike~~	<del>
- bullet / * bullet	<ul><li>
1. numbered	<ol><li>
> blockquote	情報パネルマクロ
```lang コードブロック	言語指定付きコードマクロ
| table | rows |	<thead> を含む <table>
	<ac:image>
[text](url)	<a href>（相対 .md リンクは Confluence ページリンクに解決されます）
--- 水平線	<hr />
YAML フロントマター	削除されます
**Key**: Value メタデータ行	2 列のテーブル（ラベル列はグレー）
``	TOC セクションを Confluence の toc マクロに置き換えます
confluence_properties フロントマター	ページプロパティ（details）マクロ
``	ページプロパティレポート（detailssummary）マクロ
{properties-report: ...}	ページプロパティレポート（detailssummary）マクロ
``	マーカー間のコンテンツはスキップされます（Confluence に送信されません）

ユーザーに伝えるべき主な動作：

• Confluence ではページタイトルがすでに表示されるため、最初の # heading は常にスキップされます
• ディレクトリの公開時（publish コマンドを使用）、相対 Markdown リンク（.md、./）は Confluence の内部ページリンクに解決されます。リンクマップは相対パスをページタイトルに対応付け、<ac:link> マクロを生成します。リンクマップを使わずに単一ファイルを変換する場合、相対リンクはプレーンテキストになります
• / ディレクティブで囲まれた TOC セクションは、Confluence 組み込みの TOC マクロに置き換えられます。maxLevel、minLevel、style、outline、printable のパラメーターに対応しています（例：``）。Markdown の TOC ですでに番号付きリストを使用している場合に番号が重複しないよう、セクション番号付け（outline）の既定値は false です
• コードブロックとテーブルには全幅レイアウトが使用されます
• フロントマターの直後にあるドキュメントのメタデータ行（**Key**: Value）は、ラベルがグレーの、スタイル付き 2 列テーブルに変換されます
• 言語ヒント付きのコードブロックでは、コードマクロによる構文ハイライトが適用されます
• フロントマターの confluence_labels は、publish 中にページへラベル／タグを適用します
• フロントマターの confluence_properties は、ページコンテンツの先頭に追加されるページプロパティマクロを生成します
• プロパティレポートディレクティブは、ラベル付きページを検索する動的テーブルを生成します
• / ブロックは変換時に削除され、その中のコンテンツは完全にスキップされます。これは、Confluence の動的なプロパティレポートマクロと並べて、GitHub／ローカルでの表示用に静的な Markdown テーブルを必要とする INDEX ページに便利です。コードブロック内の Ignore ディレクティブは、処理されずリテラルテキストとして扱われます

重要な注意事項

• 既定で幅広レイアウト — orbit で作成されたすべてのページは、自動的に全幅レイアウトに設定されます。元に戻すには set-width --width fixed を使用してください。
• Cloud と Server の違い — Atlassian Cloud ではサービスタイプ confluence-cloud を使用してください（API パスに /wiki/ プレフィックスが必要ですが、自動的に処理されます）。Data Center では confluence-server を使用してください。
• Cloud の認証 — ユーザー名にはメールアドレスを使用し、パスワード欄にはパスワードではなく API トークンを指定する Basic 認証を使用します。
• シークレット参照 - 設定内の認証情報では、1Password（op://vault/item/field）または Infisical（infisical://<env>/<path>/<KEY>）の参照を使用でき、実行時に解決されます。orbit auth を一度実行すると、すべてのシークレットが解決され、キャッシュされます（1Password では生体認証のプロンプトが 1 回表示されます）。キャッシュを消去するには orbit auth clear を使用してください。シークレットを参照してください。
• 公開前にドライランを実行 — ディレクトリを公開する際は、API 呼び出しの前にページ階層をプレビューするため、必ず最初に --dry-run を使用してください。