CLI リファレンス

Guren には 2 つの CLI が付属します。

• 既存プロジェクト内でコントローラー/モデル/ビュー生成やユーティリティを実行する bunx guren
• 新規アプリをスキャフォールドする bunx create-guren-app

基本的な使い方

# グローバルインストール不要。プロジェクトルートでそのまま実行
bunx guren --help

コマンドは bunx guren make:controller UserController のようなサブコマンド形式です。

高レベルスキャフォールド

低レベルな make:* ではなく、標準構成をまとめて導入したい場合は bunx guren add ... を使います。

bunx guren add auth
bunx guren add admin
bunx guren add resource posts --fields "title:string,body:text"
bunx guren add queue
bunx guren add mail
bunx guren add events
bunx guren add cache
bunx guren add notifications
bunx guren add storage
bunx guren add broadcasting
bunx guren add schedule

Golden path: まず bunx guren add auth と bunx guren add resource から始め、アプリの成長に応じて他の機能を追加してください。

bunx guren plugin @acme/guren-plugin-audit

plugin（add plugin としても利用可能）は、依存が未インストールの場合に bun add でインストールし（--no-install でスキップ可能）、プラグインが宣言するGurenバージョン互換性を検証した上で（--ignore-compatibility で無視可能）、Providerを src/app.ts に自動登録します。プラグインが gurenPlugin マニフェストで宣言した設定スタブや環境変数キーも適用されます。--force は公開済みファイルの上書きに使います。

これらのコマンドは src/app.ts を更新し、対応する provider/runtime ファイルを生成します。

bunx guren add admin は次を生成します:

• app/Http/Controllers/Admin/AdminDashboardController.ts
• resources/js/pages/admin/Dashboard.tsx
• routes/admin.ts（routes/web.ts がある場合は自動配線）

主要コマンド

コマンド	説明	例
key:generate	新しい APP_KEY 値を生成。--write で .env に保存	bunx guren key:generate --write
deploy	Docker/Fly.io/Railway/Vercel 向けデプロイ設定ファイルを生成	bunx guren deploy --target all --app my-app --port 3333
make:controller <Name>	app/Http/Controllers にコントローラーを生成	bunx guren make:controller PostController
make:model <Name>	最小のモデルクラスと型定義を app/Models に生成（db/schema から camelCase(Name)s を import）	bunx guren make:model Post
make:view <path>	resources/js/pages に React コンポーネントを生成	bunx guren make:view posts/Index
make:auth	ログイン/ログアウト・新規登録・パスワードリセットのコントローラー、プロバイダー、ビュー、マイグレーション、シーダー、ルートをスキャフォールド（--minimal で登録・パスワードリセットを省略、--verify でメール確認も追加、--oauth <providers> でカンマ区切りのプロバイダー向け OAuth ログインボタンも追加）	bunx guren make:auth --oauth github,google
make:middleware <Name>	app/Http/Middleware にミドルウェアを生成	bunx guren make:middleware Auth
make:seeder <Name>	データベースシーダーファイルを生成	bunx guren make:seeder UserSeeder
make:job <Name>	キュー可能なジョブクラスを生成	bunx guren make:job SendEmail
make:event <Name>	イベントクラスを生成	bunx guren make:event UserRegistered
make:listener <Name>	イベントリスナークラスを生成	bunx guren make:listener SendWelcomeEmail
make:notification <Name>	通知クラスを生成	bunx guren make:notification InvoicePaid
make:mail <Name>	メールクラスを生成	bunx guren make:mail WelcomeEmail
make:policy <Name>	所有者ベースのデフォルトを備えた認可ポリシーを app/Policies に生成	bunx guren make:policy Post

Note: make:* は既存ファイルを上書きしません。必要なら --force を付けてください。

検査・監査コマンド

リリース前のアプリ検証に使えるコマンドです。AIコーディングエージェント向けにも設計されています(--json で機械可読な出力になります)。

コマンド	説明	例
check	ルート・コントローラ・ページ・モデル間の整合性を検証。guren.arch.ts があればアーキテクチャ境界も検証	bunx guren check --json
audit	セキュリティ監査: 変更系ルートのバリデーション/認証の欠如、文字列補間付き生SQL、ハードコードされた認証情報、無効化されたセキュリティ既定値、mass assignment 設定、static hidden 未登録の機微カラムを検査	bunx guren audit --json
doctor	プロジェクトの健全性レポート(環境変数・設定・生成ファイル)と次のアクション	bunx guren doctor --next

check と audit はいずれも失敗(fail)を検出すると非ゼロの終了コードを返すため、CI に組み込めます。

bunx guren check
bunx guren audit

名前付きミドルウェアで保護されたルート(例: router.middleware('auth').group(...))は保護済みと認識されます。/login や /register などのゲストフローは認証チェックの対象外です。

誤検出は、対象行またはその直前の行に // guren-audit-ignore を置くことで抑制できます:

// guren-audit-ignore -- ドキュメント用のサンプル値
const apiKey = 'example-not-a-real-key'

ルートレベル・モデルレベルの findings(authz:*、validation:*、mass-assignment:*、hidden-columns:*)には、コメントを付けられる特定の行が存在しません。これらはルートレジストラを実行し、モデルを検査することで生成されるためです。代わりに config/audit.ts で finding の key(--json の出力からそのままコピーできます)と必須の reason を指定して無視します:

// config/audit.ts
export default {
  ignore: [
    { key: 'authz:POST /webhooks/stripe', reason: 'コントローラでHMAC署名を検証済み' },
  ],
}

無視された finding はレポートから削除されず、status: "ignored" と ignoreReason を伴って残ります — 何も黙って握りつぶされません。key や reason が欠落しているエントリ、どの finding にもマッチしなかったエントリは、それ自体が警告として報告されるため、形骸化したルールに気づかないまま放置されることはありません。

config/audit.ts が受け付けるのは、ソース行を持たない finding(上記のルート/モデルレベルのもの)のみです。行に紐づく finding(ハードコードされた認証情報、生SQL、無効化されたセキュリティ既定値)には既に // guren-audit-ignore という手段があるため、それらを対象にしたエントリは適用されず、インラインコメントを使うよう促す警告になります — 目立たない第二の抑制手段になってしまうことを避けるためです。

アーキテクチャ境界

プロジェクトルートに guren.arch.ts を置くだけで、フラグなしに guren check が境界を検証するようになります:

// guren.arch.ts
import { defineArchRules } from '@guren/cli/arch'

export default defineArchRules({
  layers: {
    domain: 'app/Domain/**',
    http: 'app/Http/**',
  },
  rules: [
    // ドメインロジックはHTTP層に依存してはいけない
    { from: 'domain', disallow: ['http'] },
    // コントローラはORMを直接使わずModel経由でクエリする
    { from: 'http', disallowPackages: ['drizzle-orm'] },
  ],
})

各ルールの from と disallow には、上で定義したレイヤー名か、インラインの glob を指定できます。既存コードベースに新しい境界を導入する際は severity: 'warn' から始め、違反がゼロになったら外す(デフォルトの 'fail' に戻す)運用が安全です。

AIコーディングエージェントや大規模アプリで実用的に使うための2つのフラグ:

bunx guren check --arch      # アーキテクチャチェックのみ実行 — 編集フック向けの高速パス
bunx guren check --changed   # main とのマージベースからの変更ファイルのみを検査対象にする

プロジェクト内のファイルに解決できないimportは、失敗ではなく警告として報告されます — 解決できないパスがビルドをブロックすることはありません。

アプリケーションモジュール

ルート数が数十を超えて増えてくると、guren make:module を使うことで、フラットな app/・routes/・db/schema.ts に全部を詰め込む代わりに、アプリの自己完結した一部分を切り出せます:

bunx guren make:module Billing

これにより modules/billing/{index.ts, routes.ts, db/schema.ts} が生成され、自動的に配線されます: db/schema.ts には export * from '../modules/billing/db/schema' が追加され、src/app.ts には billingModule の import と createApp({ modules: [...] }) への登録が追加されます。

ほとんどの make:* コマンドは --module <name> を受け付け、プロジェクトルートの代わりにモジュール内にスキャフォールドできます:

bunx guren make:controller Invoice --module billing   # modules/billing/app/Http/Controllers/InvoiceController.ts
bunx guren make:model Invoice --module billing        # modules/billing/app/Models/Invoice.ts

guren check・guren audit・guren context・model:list・doctor はすべて modules/*/ を自動的にスキャンします — 追加設定は不要です。例外は2つ: make:auth(認証はモジュール単位ではなくアプリ全体の関心事)と make:migration(drizzle-kit 駆動で、drizzle.config.ts が指すスキーマパスからマイグレーションを生成するため、モジュールの有無を問いません)。

モジュールの公開APIは、defineModule() の記述をexportする index.ts と、モジュール間で共有されるテーブル定義用の db/schema.ts です。modules/ ディレクトリが存在すれば、guren.arch.ts なしでも guren check がこれを自動的に強制します: あるモジュールが別モジュールの内部(index.ts と db/schema.ts 以外)に踏み込んでimportすると失敗になり、トップレベルのアプリコードが同じことをしても同様に失敗します。

// modules/billing/index.ts
import { defineModule } from '@guren/core'
import { registerBillingRoutes } from './routes'

export const billingModule = defineModule({
  name: 'billing',
  prefix: '/billing',            // レジストラが宣言する全ルートに付与する任意のURLプレフィックス
  routes: registerBillingRoutes,
  providers: [BillingServiceProvider],  // 任意 — アプリのプロバイダ一覧に追加される
})

Inertiaのページは modules/<name>/ 配下にコロケーションされません — トップレベルの resources/js/pages/ にそのまま置かれ、代わりにモジュール名で名前空間分けされます(resources/js/pages/billing/Invoices/Index.tsx)。make:feature Invoice --module billing はこの規約に自動的に従います。

AIエージェントハーネス

create-guren-app で作成したアプリには、AIエージェント向けのハーネスが最初から組み込まれます。内容は、プロジェクトガイドの CLAUDE.md、.claude/ 配下の検証済みAPIルール・スキル・サブエージェント、開発サーバーの MCP エンドポイントを指す .mcp.json、そしてフィードバックループを構成する hooks です。セッション開始時に guren context のプロジェクトマップが読み込まれ、ルート・コントローラ・モデル・スキーマ・ページの編集後には guren check が自動で再実行され、失敗があればその場でコーディングエージェントに報告されます。

コマンド	説明	例
agent:init	既存アプリにエージェントハーネスを導入(既存ファイルはスキップ、--force で上書き)	bunx guren agent:init
agent:sync	フレームワーク管理ファイル(.claude/ の rules・skills・agents・hooks)を最新版に更新	bunx guren agent:sync

agent:sync はユーザー所有のファイル(CLAUDE.md・.mcp.json・.claude/settings.json)には触れないため、カスタマイズはフレームワークの更新後も維持されます。

デプロイレシピ生成

CLI からデプロイ設定ファイルを直接生成できます。

# Dockerfile のみ
bunx guren deploy

# Fly.io（Dockerfile + fly.toml）
bunx guren deploy --target fly --app my-app

# Railway（Dockerfile + railway.json）
bunx guren deploy --target railway

# Vercel（vercel.json）
bunx guren deploy --target vercel

# すべてのレシピを一括生成（カスタムポート）
bunx guren deploy --target all --app my-app --port 4000

--target は docker / fly / railway / vercel / all をサポートします。

Vercel と Bun Vercel は Bun を用いたデプロイをサポートしています。Bun プロジェクトでは主に次の二択が現実的です。

• vercel.json に Bun 用の install/build コマンドを記載してデプロイする（シンプルなアプリ向け推奨）。

  {
    "installCommand": "bun install",
    "buildCommand": "NODE_ENV=production bun run build",
    "devCommand": "bun run dev"
  }
  

• Docker イメージを使ってデプロイし、実行環境や Bun のバージョンを固定する（ネイティブ依存や長時間実行がある場合に推奨）。

推奨: Bun の特定バージョンに依存する、あるいは長時間実行プロセスが必要な場合は Docker デプロイを選ぶと再現性が高くなります。生成される vercel.json は出発点です。プロジェクト構成に合わせてコマンドやルーティングを調整してください。

OpenAPI コマンド

コマンド	説明	例
openapi:generate	ルート定義から OpenAPI 3.1 ドキュメントを生成	bunx guren openapi:generate

オプションの @guren/openapi パッケージが必要です（bun add @guren/openapi）。

openapi:generate オプション

# デフォルトで生成（routes/web.ts を読み取り、.guren/openapi.gen.json に書き出し）
bunx guren openapi:generate

# タイトル、バージョン、説明を指定
bunx guren openapi:generate --title "Blog API" --version "1.0.0" --description "My blog"

# ルートファイルと出力パスを変更
bunx guren openapi:generate --routes routes/api.ts --out docs/openapi.json

# サーバー URL を含める
bunx guren openapi:generate --server "https://api.example.com"

# 既存ファイルを上書き
bunx guren openapi:generate --force

フラグ	デフォルト	説明
--routes	routes/web.ts	ルート登録ファイルのパス
--out	.guren/openapi.gen.json	生成ドキュメントの出力パス
--title	package.json の name または "Guren API"	OpenAPI ドキュメントタイトル
--version	package.json の version または "1.0.0"	OpenAPI ドキュメントバージョン
--description	package.json の description	OpenAPI ドキュメント説明
--server	—	含めるサーバー URL
--app	カレントディレクトリ	アプリケーションルートディレクトリ
--force	false	既存ファイルを上書き

コマンドはルートコントラクトから Zod スキーマと OpenAPI メタデータ（summary、description、tags、operationId、deprecated）を抽出し、OpenAPI 3.1 JSON ドキュメントを生成します。ルートへのアノテーション方法はルーティング — OpenAPIを参照してください。

ルートコマンド

コマンド	説明	例
route:list	登録済み全ルートを一覧表示	bunx guren route:list

route:list オプション

フィルタリングとソート機能付きで全アプリケーションルートを表示します。

# 全ルートを一覧表示
bunx guren route:list

# HTTPメソッドでフィルタリング
bunx guren route:list --method GET

# パスパターンでフィルタリング
bunx guren route:list --path users

# ルート名でフィルタリング
bunx guren route:list --name admin

# ルートをソート
bunx guren route:list --sort path
bunx guren route:list --sort method
bunx guren route:list --sort name

# ソート順を逆にする
bunx guren route:list --sort path --reverse

# 出力フォーマット
bunx guren route:list --format table   # デフォルトのテーブル形式
bunx guren route:list --format json    # JSON出力
bunx guren route:list --format compact # コンパクトな1行形式

設定コマンド

コマンド	説明	例
config:cache	全設定ファイルをキャッシュ	bunx guren config:cache
config:clear	設定キャッシュをクリア	bunx guren config:clear
config:show	設定キャッシュ情報を表示	bunx guren config:show

設定キャッシュ

本番環境でのパフォーマンス向上のために設定ファイルをキャッシュします。

# 全設定をキャッシュ
bunx guren config:cache

# キャッシュをクリア
bunx guren config:clear

# キャッシュ情報を表示
bunx guren config:show

キャッシュは bootstrap/cache/config.json に保存されます。設定ファイルは config/ ディレクトリ（サブディレクトリ含む）から読み込まれます。

Note: 設定ファイルを変更した後は、config:cache を再実行してキャッシュを更新してください。

データベースコマンド

コマンド	説明	例
db:migrate	保留中のマイグレーションを実行	bunx guren db:migrate
db:rollback	最後のマイグレーションバッチをロールバック	bunx guren db:rollback
db:reset	全テーブルを削除してマイグレーションを再実行	bunx guren db:reset
db:seed	データベースシーダーを実行	bunx guren db:seed

db:migrate オプション

# マイグレーションを実行
bunx guren db:migrate

# 本番環境でマイグレーションを強制実行
bunx guren db:migrate --force

# マイグレーションパスを指定
bunx guren db:migrate --path db/migrations

db:rollback オプション

# 最後のバッチをロールバック
bunx guren db:rollback

# 指定ステップ数ロールバック
bunx guren db:rollback --step 3

# 全マイグレーションをロールバック
bunx guren db:rollback --all

db:seed オプション

# 全シーダーを実行
bunx guren db:seed

# 特定のシーダーを実行
bunx guren db:seed --class UserSeeder

# 本番環境でシーディングを強制実行
bunx guren db:seed --force

キューコマンド

コマンド	説明	例
queue:work	キューに入ったジョブの処理を開始	bunx guren queue:work

queue:work オプション

# デフォルトキューからジョブを処理
bunx guren queue:work

# 特定のキューを処理
bunx guren queue:work --queue emails

# ジョブ数を制限
bunx guren queue:work --max-jobs 100

# キューが空になったら停止
bunx guren queue:work --stop-when-empty

共通オプション

以下のオプションはすべての make:* / add コマンドで共通の挙動をします。

• --force / -f: 既存ファイルを上書き
• --dry-run: 生成内容を表示するだけで書き込まない（予定）
• --cwd <path>: 指定パスのワークスペースでコマンドを実行（既定はカレントディレクトリ）

テンプレートの特徴

生成物はフレームワークの Laravel 風の設計方針に沿っています。

• コントローラーは Controller を継承し、this.inertia() などのヘルパーを使用。
• モデルは Model<TRecord> を継承し、static table を事前に設定。手早い CRUD にはヘルパーを、複雑なクエリは Drizzle RQB へ直接。Model.query(db) でモデル起点の RQB も書けます。
• ビューは React + TypeScript + Tailwind CSS の関数コンポーネント。

生成後はルート配線と Drizzle スキーマへの static table 接続を忘れずに。高度なクエリが必要ならモデルを介さず Drizzle の DB（getDatabase()）や Model.query() を使うと型安全のまま柔軟に書けます。

新規アプリのスキャフォールド

ゼロから始めるときは専用ブートストラッパーを使います。

bunx create-guren-app my-app --mode ssr

CLI はデフォルトテンプレートをコピーし、メタデータを更新します。--mode ssr（既定）で SSR が有効に、--mode spa で無効になります。空でないディレクトリに生成する場合は --force を付けます。

トラブルシューティング

• command not found: bunx: Bun が古い可能性があります。1.1 以降にアップグレードしてください。
• Error: Port already in use: 開発サーバー（既定 3333）が埋まっています。.env の PORT を変更して再起動してください。
• Database connection failed: デフォルトは SQLite（./data/guren.db）です。PostgreSQL を使う場合は .env の DATABASE_URL を確認してください。

対話 REPL

フレームワーク対応のコンソールを起動します。

bunx guren console

アプリケーションをブート（src/main.ts と登録済みプロバイダーを尊重）し、app、auth、発見済みモデル、DB ヘルパー、@guren/testing のユーティリティなどを事前ロードしたプロンプトに入ります。:help でショートカット、:editor で複数行入力を使えます。

典型的な流れ

1. 起動 — プロジェクトルートで bunx guren console。
2. コード実行 — src/main.ts などのブートストラップ済みスコープを共有するため、await Post.all() のようなステートメントをそのまま実行できます。
3. 状態リセット — Ctrl+D（または .exit）で終了し、必要に応じて再起動。

Tips

• Ctrl+D または .exit で REPL を抜ける。
• reloadModels() で、コンソール起動中に追加したモデルを再検出。
• :load path/to/script.ts でファイル内容を現在のセッションに読み込む。
• 素の Bun REPL が必要なら bun repl（または bun repl --inspect）を使う。

これらのパターンで、専用の guren repl を待たずとも反復開発の体験を得られます。