@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 バケット作成、Pages プロジェクト作成、シークレット設定に使用する。

npm install -g wrangler

Cloudflare にログイン:

wrangler login

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

インストール

npx @frelio/cli init

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

npm install -g @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. コンテンツ初期構造の作成 — frelio-data/ ディレクトリとメタデータファイルを生成
6. GitHub Actions ワークフロー配置 — ステージングビルド、本番プロモート、直接デプロイの3つ
7. CMS Admin バンドルの展開 — 最新リリースから admin/、functions/、workers/ を配置
8. 設定ファイル生成 — admin/config.json、wrangler.toml、_redirects、_routes.json
9. Cloudflare セットアップ — R2 バケット作成、本番用 Pages プロジェクト作成、ステージング用 Pages プロジェクト作成、OAuth シークレット設定
10. ブランチ構造の作成 — 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 | ファイル配信の URL | https://storage.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 管理画面（ビルド済み）
│   ├── index.html
│   ├── config.json               # 実行時設定
│   └── assets/
├── public/                       # 公開サイトルート（SSG 出力先）
│   └── _routes.json              # ファイル配信ルーティング（/storage/*）
├── functions/                    # Cloudflare Pages Functions
│   ├── api/
│   │   ├── auth/                 # OAuth 認証エンドポイント
│   │   └── storage/              # CMS ファイルアップロード API
│   └── storage/[[path]].ts       # R2 ファイル配信（/storage/*）
├── workers/                      # Pages Functions が参照する Worker ソース
│   └── file-upload/
├── frelio-data/                  # コンテンツデータ
│   ├── site/
│   │   ├── content_types/        # スキーマ定義
│   │   ├── contents/
│   │   │   ├── published/        # 公開済み
│   │   │   └── private/          # 下書き
│   │   ├── templates/            # HTML テンプレート
│   │   │   └── assets/
│   │   │       ├── scss/         # スタイルソース
│   │   │       └── ts/           # スクリプトソース
│   │   └── data/data-json/       # SSG 中間データ
│   └── admin/
│       ├── metadata/             # メタデータ
│       ├── recipes/              # ビルドレシピ
│       └── users/                # ユーザー管理
├── .github/workflows/            # GitHub Actions
├── vite.config.ts                # テンプレートアセットビルド（SCSS/TS）
├── package.json                  # vite + sass + typescript
├── tsconfig.json
├── wrangler.toml                 # Cloudflare 設定（R2 バインディング）
├── _redirects                    # /admin/* → SPA, /* → /public/:splat
├── _routes.json                  # /api/*, /storage/* → Functions
├── CLAUDE.md                     # AI アシスタント用プロジェクト説明
└── version.json                  # バージョン管理

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

カスタムステージング環境（プレビュー用ブランチ + Cloudflare Pages プロジェクト）を追加する。プロジェクトのルートディレクトリで実行する。

cd my-site
frelio add-staging

やること

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

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

| 項目 | CLI オプション | 説明 | 例 | |------|---------------|------|----| | ステージング名 | --name | ブランチ名に使われる識別子 | design, alice | | Pages プロジェクト名 | --pages-project | Cloudflare Pages プロジェクト名 | my-site-staging-design | | カスタムドメイン | --domain | 任意。空欄なら <project>.pages.dev | staging-design.example.com |

オプション

frelio add-staging --name design              # 名前を事前指定
frelio add-staging --skip-cloudflare          # Pages プロジェクト作成をスキップ
frelio add-staging --pages-project <name>     # Pages プロジェクト名を指定
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 Pages でリポジトリを接続 | ○ | | カスタムドメインの設定 | - | | Cloudflare Access でアクセス制限 | 推奨 | | CMS 管理画面の /staging ページでブランチを登録 | ○ |

frelio update — CMS Admin の更新

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

cd my-site
frelio update

やること

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

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

オプション

frelio update                     # 最新バージョンに更新
frelio update --version v1.2.0    # 特定バージョンに更新

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

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

1. 本番 Pages: GitHub リポジトリの接続

CLI が作成した Pages プロジェクトに GitHub リポジトリを接続する。

1. Cloudflare Dashboard → Pages → 本番プロジェクト（例: my-site）を選択
2. Settings → Builds & deployments → Connect to Git
3. GitHub リポジトリを選択
4. ビルド設定:
   • Production branch: main
   • Build command: （空欄）
   • Build output directory: /

2. ステージング Pages: GitHub リポジトリの接続

CLI が作成したステージング用 Pages プロジェクトに同じリポジトリを接続する。

1. Cloudflare Dashboard → Pages → ステージングプロジェクト（例: my-site-staging）を選択
2. Settings → Builds & deployments → Connect to Git
3. 同じ GitHub リポジトリを選択
4. ビルド設定:
   • Production branch: staging
   • Build command: （空欄）
   • Build output directory: public/

3. ステージング: カスタムドメインの設定（任意）

デフォルトでは <project-name>.pages.dev でアクセスできるが、独自ドメインを使う場合:

1. ステージング Pages プロジェクト → Custom domains → Set up a custom domain
2. ドメインを入力（例: staging.example.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 my-site-staging.pages.dev） | | Policy name | allowed-users | | Action | Allow | | Include rule | Emails — アクセスを許可するメールアドレスを列挙 |

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

方法 B: Cloudflare Pages のアクセス制限

Pages プロジェクトの設定でプレビューデプロイメントのアクセスを制限できる（簡易的）。

1. ステージング Pages プロジェクト → Settings → General → Access Policy
2. アクセスポリシーを有効化

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

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

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

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

| # | 作業 | 必須 | |---|------|:----:| | 1 | 本番 Pages ↔ GitHub 接続 | ○ | | 2 | ステージング Pages ↔ GitHub 接続 | ○ | | 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://<pages-project>.pages.dev
   • Authorization callback URL: https://<pages-project>.pages.dev/api/auth/callback
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 は Pages Functions が処理する）

公開配信 URL（R2_PUBLIC_URL）は 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://<project>.pages.dev/api/auth/callback
• 誤: https://<project>.pages.dev/auth/callback（/api が抜けている）

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

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

Pages プロジェクト作成で "already exists"

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

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

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

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

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