@c-time/frelio-cli

Frelio CMS のプロジェクトセットアップと管理を行う CLI ツール。

対話式のプロンプトに従うだけで、GitHub リポジトリの作成からコンテンツ構造の初期化、Cloudflare のセットアップまで、すべてを自動化する。CLI オプションで全パラメータを指定すれば、非対話モードでも実行可能（AI エージェントや CI 向け）。

前提条件

1. Node.js のインストール

Node.js 20 以上が必要。

Windows:

Node.js 公式サイト から LTS 版をダウンロードしてインストール。

または winget:

winget install OpenJS.NodeJS.LTS

macOS:

brew install node@20

Linux (Ubuntu/Debian):

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

インストール確認:

node --version   # v20.x.x 以上
npm --version    # 10.x.x 以上

2. Git のインストール

Windows:

winget install Git.Git

macOS:

# Xcode Command Line Tools に含まれる
xcode-select --install

Linux:

sudo apt-get install git

3. GitHub CLI (gh) のインストール

GitHub リポジトリの作成、ブランチ管理、デフォルトブランチ設定などに使用する。

Windows:

winget install GitHub.cli

macOS:

brew install gh

Linux:

# https://github.com/cli/cli/blob/trunk/docs/install_linux.md を参照

インストール後、GitHub にログイン:

gh auth login

プロンプトに従い、ブラウザで認証を完了する。

4. Wrangler CLI のインストール

Cloudflare の R2 バケット作成、Worker のデプロイ、シークレット設定に使用する。

npm install -g wrangler

Cloudflare にログイン:

wrangler login

ブラウザが開くので、Cloudflare アカウントで認証する。

インストール

npx @c-time/frelio-cli init

npm でグローバルインストールする場合:

npm install -g @c-time/frelio-cli
frelio init

コマンド

frelio init — プロジェクトの新規作成

対話式プロンプトで必要な情報を入力し、プロジェクトをセットアップする。

frelio init

やること

1. 前提チェック — gh, wrangler, git がインストールされ、ログイン済みか確認
2. 対話式プロンプト — リポジトリ名、サイトタイトル、R2 設定などを入力
3. GitHub OAuth App の案内 — OAuth App の作成手順を表示し、Client ID / Secret を入力
4. GitHub リポジトリ作成 — gh repo create でプライベートリポジトリを作成・クローン
5. コンテンツリポジトリのスキャフォールド — GitHub から c-time/frelio-content-template をダウンロードし、設定値を埋め込んで展開（frelio-data/、scripts/、.github/workflows/、vite.config.ts 等）
6. CMS Admin バンドルの展開 — 最新リリースから admin/（SPA）、admin-worker/、workers/ を配置
7. 設定ファイル生成 — admin/config.json、wrangler.content.toml、wrangler.admin.toml
8. Cloudflare セットアップ — R2 バケット作成、admin Worker のシークレット設定（Worker は wrangler deploy 時に自動作成）
9. ブランチ構造の作成 — main、develop、staging ブランチを作成・プッシュ、デフォルトブランチを develop に設定

プロンプトで聞かれること

| 項目 | CLI オプション | 説明 | 例 | |------|---------------|------|----| | リポジトリ名 | --content-repo | owner/repo 形式 | my-org/my-site | | サイトタイトル | --site-title | 管理画面に表示される名前 | My Website | | 本番 URL | --production-url | 公開サイトの URL（任意） | https://example.com | | ステージングドメイン | --staging-domain | ステージング確認用ドメイン（任意） | staging-abc123.example.com | | R2 バケット名 | --r2-bucket-name | ファイルストレージ用バケット | my-site-files | | R2 公開 URL | --r2-public-url | アップロードファイル（R2）の配信元 URL（任意）。R2 のカスタムドメイン推奨、pub-xxxx.r2.dev も可。空欄なら後から設定可 | https://files.example.com | | 管理者 GitHub ユーザー名 | --owner-username | 最初の管理者ユーザー | your-username | | OAuth Client ID | --client-id | GitHub OAuth App の Client ID | Ov23li... | | OAuth Client Secret | --client-secret | GitHub OAuth App の Client Secret | ******** |

オプション

# スキップオプション
frelio init --skip-github       # GitHub 操作をスキップ（手動でリポジトリを用意する場合）
frelio init --skip-cloudflare   # Cloudflare 操作をスキップ（後から設定する場合）

# パラメータ指定（非対話モード用）
frelio init \
  --content-repo <owner/repo>   # リポジトリ名（必須）
  --site-title <title>          # サイトタイトル
  --production-url <url>        # 本番 URL
  --staging-domain <domain>     # ステージングドメイン
  --r2-bucket-name <name>       # R2 バケット名
  --r2-public-url <url>         # R2 公開 URL
  --owner-username <user>       # 管理者 GitHub ユーザー名
  --client-id <id>              # OAuth Client ID（必須）
  --client-secret <secret>      # OAuth Client Secret（必須）

非対話モード（AI エージェント / CI 向け）

--content-repo、--client-id、--client-secret の3つを指定すると、プロンプトなしで実行される。他のパラメータは省略するとデフォルト値が自動算出される。

# 最小構成
frelio init \
  --content-repo my-org/my-site \
  --client-id Ov23liXXX \
  --client-secret ghp_XXX

# 全パラメータ指定
frelio init \
  --content-repo my-org/my-site \
  --site-title "My Site" \
  --production-url https://example.com \
  --staging-domain staging-abc123.example.com \
  --r2-bucket-name my-site-files \
  --r2-public-url https://storage.example.com \
  --owner-username my-username \
  --client-id Ov23liXXX \
  --client-secret ghp_XXX \
  --skip-cloudflare

生成されるリポジトリ構造

my-site/
├── admin/                        # CMS 管理画面（ビルド済み、frelio update で更新）
│   ├── index.html
│   ├── config.json               # 実行時設定
│   └── assets/
├── public/                       # 公開サイトルート（SSG 出力先・[assets] で配信）
├── worker/                       # コンテンツ配信 Worker（/storage/* の R2 配信・siteMode）
├── admin-worker/                 # 管理画面 Worker（/api ルーター・バンドル済み）
├── wrangler.content.toml         # コンテンツ配信 Worker 設定
├── wrangler.admin.toml           # 管理画面 Worker 設定
├── workers/                      # Worker ソース（admin Worker が参照）
│   └── file-upload/
├── frelio-data/                  # コンテンツデータ
│   ├── site/
│   │   ├── content_types/        # スキーマ定義
│   │   ├── contents/
│   │   │   ├── published/        # 公開済み
│   │   │   └── private/          # 下書き
│   │   ├── templates/            # HTML テンプレート + アセットソース
│   │   │   ├── _parts/           # 共通パーツ (head.htm, header.htm, footer.htm)
│   │   │   ├── common/           # 全ページ共通 (scripts/ + styles/)
│   │   │   ├── about/            # ページ別 (index.html + scripts/ + styles/)
│   │   │   ├── contact/
│   │   │   └── news/
│   │   └── data/data-json/       # SSG 中間データ
│   └── admin/
│       ├── content_types/        # UI/Views 設定
│       ├── metadata/             # content_types.json, _dashboard.json
│       ├── recipes/              # ビルドレシピ
│       └── structure/            # users.json, stages.json
├── scripts/                      # SSG ビルドスクリプト (tsx)
├── .github/workflows/            # GitHub Actions（4ワークフロー）
├── vite.config.ts                # テンプレートアセットビルド（SCSS/TS）
├── package.json                  # vite + sass + typescript
├── tsconfig.json
├── tsconfig.node.json
├── AGENTS.md                     # AI アシスタント用プロジェクト説明（正本・ツール非依存）
├── CLAUDE.md                     # → AGENTS.md を参照（Claude Code 用）
├── .github/copilot-instructions.md  # → AGENTS.md を参照（GitHub Copilot 用）
└── version.json                  # バージョン管理

frelio add-staging — ステージング環境の追加

カスタムステージング環境（プレビュー用ブランチ）を追加する。プロジェクトのルートディレクトリで実行する。コンテンツ配信 Worker のプレビューエイリアスとして公開されるため、別プロジェクトの作成は不要。

cd my-site
frelio add-staging

やること

1. 前提チェック — git, wrangler がインストール済みか確認
2. 対話式プロンプト — ステージング名、Worker 名、カスタムドメインを入力
3. Git ブランチ作成 — develop から staging-{name} ブランチを作成・プッシュ
4. ワークフロー確認 — build-staging.yml のブランチリスト（staging-*）に対応済みか確認、未対応なら案内を表示

プロンプトで聞かれること

| 項目 | CLI オプション | 説明 | 例 | |------|---------------|------|----| | ステージング名 | --name | ブランチ名に使われる識別子 | design, alice | | Worker 名 | --pages-project | コンテンツ配信 Worker 名 | my-site | | カスタムドメイン | --domain | 任意。空欄ならプレビューエイリアス staging-{name}-<worker>.<subdomain>.workers.dev | staging-design.example.com |

オプション

frelio add-staging --name design              # 名前を事前指定
frelio add-staging --skip-cloudflare          # Cloudflare 関連の確認をスキップ
frelio add-staging --pages-project <name>     # コンテンツ配信 Worker 名を指定
frelio add-staging --domain <domain>          # カスタムドメインを指定

非対話モード（AI エージェント / CI 向け）

--name を指定するとプロンプトなしで実行される。--pages-project と --domain は省略するとデフォルト値が自動算出される。

# 最小構成（name のみ、他はデフォルト算出）
frelio add-staging --name preview1

# 全パラメータ指定
frelio add-staging \
  --name preview1 \
  --pages-project my-site-staging-preview1 \
  --domain preview1-abc123.example.com

完了後の手動作業

| 作業 | 必須 | |------|:----:| | カスタムドメインの設定 | - | | Cloudflare Access でアクセス制限 | 推奨 | | CMS 管理画面の /staging ページでブランチを登録 | ○ |

frelio update — CMS Admin の更新

CMS Admin バンドルを最新バージョン（または指定バージョン）に更新する。

cd my-site
frelio update

やること

1. admin/config.json をバックアップ
2. 指定バージョン（またはLatest）のリリースをダウンロード
3. admin/、admin-worker/、workers/ を新しいバンドルで置き換え
4. admin/config.json を復元

config.json は自動的に保護されるため、設定が上書きされることはない。

オプション

frelio update                     # バンドル＋テンプレートを最新化
frelio update --version v1.2.0    # 特定バージョンのバンドルに更新
frelio update --templates-only    # ワークフロー/worker/wrangler のみ再生成（バンドルは触らない）
frelio update --bundle-only       # CMS Admin バンドルのみ更新（テンプレートは触らない）
frelio update --force             # 保護設定ファイルも含め上書き（保護ファイルはバックアップ付き）

テンプレート再生成は、ファイルを2種類に分けて扱う:

• 保護設定ファイル（wrangler.content.toml / wrangler.admin.toml / workers/file-upload/wrangler.toml）: ユーザーが恒常的にカスタムを足す前提のため、config.json と同様に既定では上書きせず保持する。 差分を検出するとスキップして警告のみ表示する。更新するには --force を付ける（このとき *.frelio-bak にユーザー版を退避してから上書きする）。
• システム管理ファイル（.github/ ワークフロー / worker/site-mode.ts）: 差分があれば既定で *.frelio-bak にバックアップしてから上書きする（--force でバックアップなし上書き）。

admin/config.json / frelio-data/ / public/ / worker/index.ts / admin-worker/ は再生成対象外。

frelio doctor — 生成物の自己診断

生成物（特に .github/workflows/）をスキャンし、期限付きの破壊的変更（例: GitHub Actions の Node 20 廃止）や未適用のテンプレ更新を検出して、直し方を提示する。

cd my-site
frelio doctor          # 検出結果を表示（終了コードは常に 0）
frelio doctor --ci     # 対応が必要な指摘があれば非ゼロ終了（CI 用）

出力例:

  🔴 重大  GitHub Actions ワークフローを Node 24 対応へ更新 （期限 2026-06-16 — 残り 3 日）
     該当ファイル（1）:
       • .github/workflows/build-staging.yml
     直し方: `npx @c-time/frelio-cli update --templates-only` を実行して ...
     → 実行: npx @c-time/frelio-cli update --templates-only

指摘の修復はそのまま frelio update --templates-only で行う。

frelio set-mode <mode> — 本番ゲート（公開状態の制御）

コンテンツサイトの公開状態を切り替える。siteMode はコンテンツ配信 Worker にビルド時へ焼き込まれる （worker/site-mode.ts の SITE_MODE 定数 + wrangler.content.toml の run_worker_first）。

| mode | 挙動 | 用途 | |---|---|---| | live（既定） | 通常配信（静的ページは Worker を経由しない） | 公開運用 | | prelaunch | /storage/* 以外を 403（"公開準備中" ページ） | 公開前のプレ公開ブロック | | maintenance | /storage/* 以外を 503（"メンテナンス中" ページ） | 一時停止 | | closed | /storage/* 含め 全遮断（503） | サイト閉鎖キルスイッチ |

cd my-site
frelio set-mode prelaunch    # プレ公開ブロック
frelio set-mode live         # 公開（通常配信）
frelio set-mode closed       # 全遮断

set-mode は config.json の siteMode と worker/site-mode.ts / wrangler.content.toml を再生成する。 反映にはコンテンツの再デプロイが必要。

設計上の注意

• プレ公開・メンテナンスは /storage/* を除外して配信を継続する（R2 画像が CMS のサムネ・記事 プレビューに使われるため）。閉鎖（closed）は storage も遮断する。
• 非 live のときは run_worker_first = true となり、Worker が全リクエストで holding ページを返す。 live では静的ページに Worker が介在しない。
• 独自ドメインへの正規化は workers_dev = false（workers.dev 無効化）で行う。

生成物のメンテナンスと自走（self-healing）

frelio が生成するワークフローや設定は各リポジトリにコピーされるため、frelio 本体の テンプレート更新は自動では追従されない。これに対し、以下の3つの仕組みで「腐りにくく」する。

1. 依存の自動追従（Dependabot）

生成物には .github/dependabot.yml が同梱され、github-actions エコシステムを毎週監視する。

• frelio のワークフローはアクションを major タグ（例: actions/checkout@v6）で参照する。 patch/minor のセキュリティ修正は GitHub 側で自動的に流れる。
• major の更新は 各自のリポジトリに Dependabot が PR を立てる。内容を確認してマージする （マージは利用者の責任）。frelio 側から各リポジトリへ push して直すことはしない。

これにより、GitHub Actions ランタイムの廃止（例: Node 20 → 24）のような期限付きの破壊的変更も、 「次回以降」は自動 PR として各リポジトリに届く。

2. 自己診断（frelio doctor）

frelio doctor がテンプレートの期限付き廃止（例: ワークフローが Node 20 アクションのまま）を 検出し、直し方を提示する。コマンド詳細は後述の「コマンド」節を参照。

3. 最新版の取得（frelio update）

frelio update --templates-only でワークフロー・worker・wrangler.toml を最新テンプレートで再生成できる。 frelio doctor の指摘はこのコマンドで解消する。

4. 起動時バージョンチェック

CLI 実行時、npm の最新版を確認し、古ければ stderr にナッジを表示する（1日に1回・キャッシュ済み・ オフライン時は無言）。次の環境変数で無効化できる:

export FRELIO_NO_UPDATE_CHECK=1   # 起動時バージョンチェックを無効化（CI では自動的に無効）

メンテナー向け運用（ブロードキャスト）

匿名ユーザーには push で直せないため、install/実行経路で警告を届ける手段を運用で用意する。

期限付き破壊的変更の告知（npm deprecate）

期限付きの破壊的変更（例: Node 20 廃止）が出たら、影響する旧バージョン範囲を npm deprecate する。 これにより、該当バージョンを install したユーザーのターミナルへ警告が出る（数少ない強制告知手段）。

# 例: 1.4.x 以前を非推奨にし、移行先を案内する
npm deprecate '@c-time/frelio-cli@<=1.4.9' \
  'Node 20 廃止対応のため 1.5.0 以降へ更新し、各サイトで `frelio doctor` を実行してください'

CHANGELOG / Releases に「移行」節を設ける

各リリースの CHANGELOG / GitHub Releases に、対応する Migration.id（例: node20-to-node24）と 期限・手順を記した「## 移行（Migration）」節を必ず設ける。frelio doctor の出力と対応づける。

フリート在庫（frelio fleet）

管理（アクセス権のある）コンテンツリポジトリを横断スキャンし、各リポのバンドルバージョンと 未対応マイグレーション（期限付き廃止など）を集計する。期限付き廃止時の露出特定・優先順位付けに使う。 frelio doctor を 1 リポずつ流す代わりに、operator が手元から全顧客リポを一覧できる。

# org/user 配下を列挙（version.json を持つ frelio リポのみ対象）
frelio fleet --org my-org

# 明示指定 / ファイル指定（1 行 1 リポ、# でコメント可）
frelio fleet --repos owner/site-a,owner/site-b
frelio fleet --repo-list ./fleet-repos.txt

frelio fleet --org my-org --json   # 機械可読（CI / 集計用）
frelio fleet --org my-org --ci     # 未対応（critical/warning）があれば非ゼロ終了

出力例:

  ⚠ owner/site-b  —  v1.4.7
      🔴 node20-to-node24 （期限 2026-06-16 / 残り 3 日）— 該当 4 ファイル
  ✓ owner/site-a  —  v1.5.0

  サマリ: 2 スキャン / frelio 2 / 未対応あり 1
  未対応マイグレ: 🔴 1 / 🟡 0 / ℹ️ 0
  npm 直近1か月ダウンロード（匿名層の粗い母数）:
    @c-time/frelio-cli: 1529
    @c-time/frelio-cms: 1727

• 前提: gh CLI の認証（gh auth login）と対象リポへのアクセス権。検出には version.json と .github/workflows/* を GitHub API（gh api）で取得する（読み取りのみ）。
• 検出ルールは frelio doctor と同じマイグレ定義（Migration）を共有する。
• 匿名ユーザーは原則 push 不可のため、本コマンドは主に管理顧客の在庫把握に効く。匿名層は npm ダウンロード統計を粗い母数として併記する。

opt-in テレメトリ（phone-home）は follow-up。 生成サイトからの匿名化情報の送信は、収集エンドポイント・ 同意フロー・匿名化設計が前提（無断収集はしない）。本コマンドは GitHub アクセス権の範囲＋npm 統計で 完結し、新規インフラを必要としない。

セットアップ後の手動作業

CLI 完了後、Cloudflare Dashboard での設定が必要。

1. GitHub Actions シークレットの設定

ワークフローが wrangler deploy / versions upload を実行するため、content-repo の Settings → Secrets and variables → Actions に以下を設定する:

• CLOUDFLARE_API_TOKEN — Workers のデプロイ権限を持つ API トークン
• CLOUDFLARE_ACCOUNT_ID — Cloudflare アカウント ID

2. 初回デプロイ（workers.dev サブドメインの登録）

admin ブランチへ push すると deploy-admin.yml が管理画面 Worker をデプロイする。初回デプロイで アカウントの workers.dev サブドメインが登録され、以降 staging のプレビューエイリアス （<branch>-<worker>.<subdomain>.workers.dev）が有効になる。Worker は wrangler deploy 時に自動作成される。

3. カスタムドメインの設定（任意）

独自ドメインを使う場合、各 Worker（コンテンツ配信 / 管理画面）に設定する:

1. Cloudflare Dashboard → Workers & Pages → 対象 Worker → Settings → Domains & Routes
2. ドメインを入力（例: yourdomain.com / cms.yourdomain.com）
3. DNS レコードの自動追加を確認・承認

4. ステージング: アクセス制限の設定（推奨）

ステージングサイトは公開前のプレビュー用なので、アクセスを制限することを推奨する。

方法 A: Cloudflare Access（推奨）

メールアドレスベースのアクセス制限。ワンタイムコードまたは Google OAuth で認証する。

1. Cloudflare Dashboard → Zero Trust → Access → Applications → Add an application
2. Self-hosted を選択
3. 以下を設定:

| 設定項目 | 値 | |---------|-----| | Application name | staging | | Application domain | ステージングのドメイン（例: staging.example.com or プレビューエイリアスの workers.dev） | | Policy name | allowed-users | | Action | Allow | | Include rule | Emails — アクセスを許可するメールアドレスを列挙 |

Cloudflare Access は 50 ユーザーまで無料。

5. R2 カスタムドメインの設定（任意）

R2_PUBLIC_URL を設定した場合、R2 バケットにカスタムドメインを紐付ける:

1. Cloudflare Dashboard → R2 → バケットを選択 → Settings → Custom Domains
2. カスタムドメインを追加（例: storage.example.com）

まとめ: 手動作業チェックリスト

| # | 作業 | 必須 | |---|------|:----:| | 1 | GitHub Actions シークレット設定（CLOUDFLARE_API_TOKEN / CLOUDFLARE_ACCOUNT_ID） | ○ | | 2 | 管理画面 Worker シークレット投入（GITHUB_CLIENT_SECRET） | ○ | | 3 | ステージング アクセス制限 | 推奨 | | 4 | カスタムドメイン設定 | - | | 5 | R2 カスタムドメイン | - |

GitHub OAuth App の作成手順

frelio init 実行中に案内が表示されるが、事前に作成しておくこともできる。

1. GitHub Developer Settings にアクセス
2. OAuth Apps → New OAuth App
3. 以下を入力:
   • Application name: My Site CMS（任意）
   • Homepage URL: https://<管理画面 Worker>.<subdomain>.workers.dev（または独自ドメイン）
   • Authorization callback URL: https://<管理画面 Worker>.<subdomain>.workers.dev/api/auth/callback
   • Enable Device Flow: チェックしない（Disable のまま。Frelio は認可コードフローを使用するため不要）
4. Register application をクリック
5. Client ID をメモ
6. Generate a new client secret → Client Secret をメモ

ファイル配信の設定

アップロードした画像やファイルを公開配信するには、R2 バケットにカスタムドメインを設定する。

1. Cloudflare Dashboard → R2 → バケットを選択 → Settings → Custom Domains
2. カスタムドメインを追加（例: storage.example.com）
3. admin/config.json の fileUploadUrl は /api/storage のままでよい（API は管理画面 Worker が処理する）

公開配信 URL（R2_PUBLIC_URL）は各 Worker の wrangler.*.toml の [vars] で設定済み。

トラブルシューティング

gh: command not found

GitHub CLI がインストールされていない。前提条件 を参照。

wrangler: command not found

Wrangler CLI がインストールされていない。前提条件 を参照。

gh auth status でエラー

gh auth login を実行してログインする。

OAuth エラー: "redirect_uri mismatch"

GitHub OAuth App の Authorization callback URL を確認:

• 正: https://<worker>.<subdomain>.workers.dev/api/auth/callback
• 誤: https://<worker>.<subdomain>.workers.dev/auth/callback（/api が抜けている）

R2 バケット作成で "already exists"

同名のバケットが既に存在する。CLI は自動的にスキップするので問題ない。

config.json の読み込みに失敗する

admin/config.json が存在し、正しい JSON であることを確認。frelio update で config.json が消えた場合は、バックアップから復元するか手動で再作成する。

組織リポジトリへのアクセスで 403 エラー

GitHub OAuth App に対して組織のアクセス権が付与されていない可能性がある。GitHub → Settings → Applications → Authorized OAuth Apps から対象アプリの組織アクセスを許可（Grant）する。