go-blueprintは、Goのプロジェクト構成をコマンド一本で用意するCLIツールです。フレームワークとデータベースドライバを選ぶと、cmd/internalに分かれたディレクトリと、ビルド用のMakefile、テスト、必要ならDocker Composeの定義までまとめて書き出されます。ただしネット上の解説には、実在しないサブコマンドやオプションを載せたものが少なくありません。この記事は2026年8月19日にv0.10.11を導入し、コマンドを実行して得た出力と生成物だけを根拠に、使えるコマンドと生成されるファイルを整理します。
まとめ
- サブコマンドは
create・version・completion・helpの4つだけです。initやnew、build、runといったサブコマンドは存在しません。 - 導入は
go install github.com/melkeydev/go-blueprint@latestです。リポジトリのURL表記は大文字のMelkeydevですが、モジュールパスは全部小文字で、大文字のまま指定するとインストールが失敗します。 createのフラグは--name・--framework・--driver・--advanced・--feature・--gitの6つ。フレームワークは7種、ドライバは7種、追加機能は6種から選びます。- 生成したプロジェクトのビルドと実行はMakefileが担当します。
make build・make run・make testなどが最初から入っています（ターゲット数は選んだドライバと追加機能で6〜10と変わります）。 - フラグを全部渡してもプロンプトが消えるだけで、
createは最後まで端末を必要とします。CIコンテナで実行するなら擬似端末の割り当てが必須です。
以下、それぞれの根拠と実行結果を順に見ていきます。
go-blueprintのインストールとバイナリの置き場所
go installでの導入とPATH設定
go-blueprint本体はGoで書かれており、配布はgo install経由が基本です。次のコマンドで最新版が入ります。
go install github.com/melkeydev/go-blueprint@latest導入できたかはversionサブコマンドで確認します。2026年8月19日時点の最新リリースはv0.10.11で、公開は日本時間2025年7月11日（GitHubのpublished_atは2025-07-10T19:44:34Z）です。出力は次の通りです。
$ go-blueprint version
Go Blueprint CLI version: v0.10.11ここでcommand not foundになる場合、原因はインストール失敗ではなくPATHです。go installはバイナリを$GOBIN、未設定なら$GOPATH/bin（既定は$HOME/go/bin）へ置くだけで、シェルのPATHには自動で追加されません。go env GOPATHで場所を確認し、シェルの起動ファイルに以下を追記します。
export PATH=$PATH:$(go env GOPATH)/bin大文字のMelkeydevを指定したときのインストール失敗
GitHubの表示名はMelkeydev/go-blueprintですが、リポジトリのgo.mod 1行目はmodule github.com/melkeydev/go-blueprintと全て小文字で宣言されています。Goのモジュールパスは大文字小文字を区別するため、表示名どおりに大文字で指定するとダウンロードは通ってもモジュールパス検証で弾かれます。
$ go install github.com/Melkeydev/go-blueprint@latest
go: github.com/Melkeydev/go-blueprint@latest: version constraints conflict:
github.com/Melkeydev/[email protected]: parsing go.mod:
module declares its path as: github.com/melkeydev/go-blueprint
but was required as: github.com/Melkeydev/go-blueprintエラー文面が「version constraints conflict」で始まるためバージョン指定の問題に見えますが、直すべきはURLの大文字です。公式READMEのインストール手順も小文字表記になっています。
v0.10.11のコマンド体系
createとversionを中心とした4サブコマンド
go-blueprint --helpが列挙するサブコマンドは4つです。
| サブコマンド | 役割 |
|---|---|
| create | Goプロジェクトの雛形を生成する |
| version | go-blueprint自身のバージョンを表示する |
| completion | シェル補完スクリプトを出力する |
| help | 各コマンドのヘルプを表示する |
実作業で使うのは事実上createだけです。プロジェクト生成後のビルドやテストを担うサブコマンドはgo-blueprint側に用意されておらず、その役割は生成物のMakefileへ移譲されています。ルートコマンドのフラグは-h, --helpと-t, --toggleの2つのみです。
createで指定できる6フラグと許可値
go-blueprint create --helpの出力そのままの一覧です。許可値はリポジトリのcmd/flags/配下で定義されている値と一致します。
| フラグ | 短縮形 | 許可値 |
|---|---|---|
--name |
-n |
任意のプロジェクト名 |
--framework |
-f |
chi・gin・fiber・gorilla/mux・httprouter・standard-library・echo |
--driver |
-d |
mysql・postgres・sqlite・mongo・redis・scylla・none |
--feature |
（なし） | react・htmx・githubaction・websocket・tailwind・docker |
--advanced |
-a |
真偽値（追加機能の選択プロンプトを出す） |
--git |
-g |
commit・stage・skip |
ヘルプ表示用の-h, --helpを除くと、指定に意味があるのはこの6つです。許可値以外を渡すとその場でエラーになり、有効な値の一覧が返ります。--featureだけは短縮形が無く、複数指定するときはフラグを繰り返します。ただし--featureは--advancedと併用しないと読み取られません。上流のcmd/create.goでは--featureの値を取り出す処理が--advancedが真のときだけ走るブロックに入っており、単独で渡すとエラーも警告も出ないまま無視されます。
フラグの組み合わせをGUIで選んでコマンド文字列を組み立てられる公式のWeb UI（Blueprint UI）と、公式ドキュメントサイトも用意されています。手元でcreate --helpを確認しつつ、選択肢の意味はドキュメント側で読む使い分けが実用的です。
Goプロジェクト作成の手順と端末要件
プロンプト消去と端末要件の切り分け
go-blueprint createをフラグ無しで叩くと、フレームワークやドライバを矢印キーで選ぶ対話画面が立ち上がります。次のようにフラグで全項目を埋めれば、この選択画面は出ません。EchoとPostgreSQLの組み合わせで、Gitの初期化はしない指定です。
go-blueprint create --name my-api --framework echo --driver postgres --git skipただし「プロンプトが出ない」と「端末が要らない」は別です。v0.10.11のcmd/create.goは、フラグが揃っているかどうかに関係なく生成中のスピナーをBubble Teaで起動します。このスピナーが/dev/ttyを直接開くため、端末が割り当てられていない環境では上のコマンドでも失敗します。
$ go-blueprint create --name my-api --framework echo --driver postgres --git skip < /dev/null
Error: open /dev/tty: device not configured失敗しても何も残らないわけではありません。プロジェクト名のディレクトリだけが空のまま作られるので、リトライ前に削除が要ります。CIジョブやDockerコンテナで生成するなら、擬似端末を割り当ててください。docker runなら-t、シェルスクリプトからならscriptコマンドで包む形です。
script -q /dev/null go-blueprint create --name my-api --framework echo --driver postgres --git skip成功するとcd my-apiを促すメッセージが出て、カレントディレクトリ直下にプロジェクトが展開されます。
生成されるディレクトリ構成とドライバによる差分
まず最小構成として--framework standard-library --driver noneで生成した場合のファイル一覧です。
minimal-api/
├── .air.toml
├── .env
├── .gitignore
├── Makefile
├── README.md
├── cmd/
│ └── api/
│ └── main.go
├── go.mod
├── go.sum
└── internal/
└── server/
├── routes.go
├── routes_test.go
└── server.goエントリポイントはcmd/api/main.goの1本だけで、HTTPサーバの組み立てとルーティングはinternal/server/に分離されます。テストの雛形（routes_test.go）とホットリロード用の.air.tomlが最初から入っている点が、手書きの雛形との差になります。ドライバ無しでも.envは作られますが、中身はPORT=8080とAPP_ENV=localの2行だけです。
ここにドライバを付けると差分が出ます。--driver postgresを指定した先ほどのmy-apiでは、上の構成に加えて次の3ファイルが増えました。
internal/database/database.go：接続と疎通確認の実装internal/database/database_test.go：testcontainers-goで実DBを立てる統合テストdocker-compose.yml：postgres:latestイメージの定義
依存も連動して増え、Echo＋PostgreSQLのgo.modにはgithub.com/labstack/echo/v4 v4.15.4、github.com/jackc/pgx/v5 v5.10.0、github.com/joho/godotenv v1.5.1、github.com/testcontainers/testcontainers-go v0.44.0が並びます。ドライバはpgxのような低レベルドライバが直接入る構成で、ORMは含まれません。クエリを構造体にマッピングしたい場合は、生成後にGORMジェネリクスAPIを活用した基本的な実装パターンのようなORM層を自分で足すことになります。
なお生成されたgo.modのgoディレクティブには、実行したマシンのGoバージョンがそのまま書き込まれます。検証環境のgo1.26.5ではgo 1.26.5となりました。チームで版を揃えたい場合は生成直後に書き換えてください。各版の変更点はGo 1.27の新機能・変更点まとめ｜最新バージョンの確認方法と移行ガイドで確認できます。
生成後のビルド・実行・テストを担うMakefile
Makefileのターゲットと選択による増減
go-blueprintにbuildやrunのサブコマンドが無いのは、その役割を生成物のMakefileへ渡しているからです。ターゲットの本数は固定ではなく、選んだドライバと追加機能で変わります。下表は--driver postgresを指定したときの9ターゲットです。
| ターゲット | 実行内容 |
|---|---|
all |
buildとtestを連続実行 |
build |
go build -o main cmd/api/main.go |
run |
go run cmd/api/main.go |
test |
go test ./... -v |
itest |
go test ./internal/database -v（統合テスト） |
docker-run |
docker compose up --build |
docker-down |
docker compose down |
clean |
ビルド成果物のmainを削除 |
watch |
airによるホットリロード起動 |
追加機能を付けずにドライバをnoneにするとdocker-run・docker-down・itestが消えて6ターゲットになります。ただしdocker-runとdocker-downの有無を決めるのはドライバだけではありません。--driver noneでも--feature dockerを付ければこの2つは残り、欠けるのはitestだけの8ターゲットになります。逆にtailwindとhtmxを足すとtempl-installとtailwind-installが加わり、buildがこの2つに依存する形へ書き換わります。表の内容をそのまま前提にせず、生成後のMakefileを一度開いてください。
最小構成のプロジェクトでmake buildを実行すると9,250,192バイト（約9.2MB）のmainが出力され、make testでは雛形のTestHandlerがPASSします。生成直後に一度回しておくと、環境側の不備を先に潰せます。
細かい配慮も入っています。docker-runとdocker-downはdocker composeを先に試し、失敗したらdocker-composeへフォールバックする二段構え。watchはairが未導入なら「インストールするか」を対話で尋ね、承諾するとgo install github.com/air-verse/air@latestを走らせます。この対話も端末を要求するため、CIでmake watchは使えません。
.envのBLUEPRINT_DB_接頭辞とdocker-composeの連動
ドライバを指定すると.envに接続情報が書き出されます。PostgreSQLの場合は次の内容です。
PORT=8080
APP_ENV=local
BLUEPRINT_DB_HOST=localhost
BLUEPRINT_DB_PORT=5432
BLUEPRINT_DB_DATABASE=blueprint
BLUEPRINT_DB_USERNAME=melkey
BLUEPRINT_DB_PASSWORD=password1234
BLUEPRINT_DB_SCHEMA=public環境変数名がプロジェクト名ではなくBLUEPRINT_接頭辞で固定される点は、既存の設定管理と衝突しやすいので最初に確認してください。ユーザー名やパスワードは作者由来の既定値がそのまま入るため、公開リポジトリへ上げる前に必ず差し替えます。internal/database/database.goはこの変数名を直接参照しているので、名前を変えるなら両方の修正が必要です。
この.envはdocker-compose.ymlからも読まれ、make docker-runで立ち上がるコンテナの初期ユーザーとデータベース名になります。Compose側の記法を整理したい場合はdocker-composeとは？複数コンテナをymlで定義し一括管理する仕組みを解説が参考になります。
advancedモードで追加できる6機能と生成物の差分
featureフラグによる非対話での機能指定
--advancedを付けると追加機能の選択に進みます。選択画面を出さずに回すなら--featureで明示します。指定できるのはreact・htmx・githubaction・websocket・tailwind・dockerの6つです。前述のとおり--featureは--advancedとセットでなければ無視されるので、両方渡してください。
script -q /dev/null go-blueprint create --name adv-api --framework chi --driver sqlite --advanced \
--feature docker --feature githubaction --feature tailwind --feature htmx --git skip生成される追加ファイルとCIでの落とし穴
この4機能を有効にすると、基本構成に対して次のファイル群が上乗せされました。
Dockerfile：--feature dockerが置くコンテナイメージの定義.github/workflows/go-test.yml・.github/workflows/release.yml・.goreleaser.yml：この3つはいずれも--feature githubaction由来（上流のcmd/template/advanced/gitHubAction.goが3テンプレートを埋め込んでいます）cmd/web/：base.templ・hello.templ・efs.goなど、Templによるサーバサイドレンダリング一式tailwind.config.jsとcmd/web/styles/input.css、それに空ファイルのcmd/web/assets/css/output.css（中身はmake build時に生成されます）cmd/web/assets/js/htmx.min.js：HTMX本体を同梱（CDN参照ではない）
ビルド系に足される2ターゲットには落とし穴があります。tailwind-installはダウンロードURLにtailwindcss-macos-x64を決め打ちしており、Linux上のCIでmake buildを回すとmacOS用バイナリを取得して実行に失敗します。templ-installのほうはtempl未導入時にread -pでインストールの可否を尋ねる作りで、こちらも端末が無ければ停止。tailwindやhtmxを有効にしたプロジェクトをCIへ載せるなら、Makefileのこの2ターゲットを先に書き換えるのが前提になります。
htmxとtailwindはTemplを前提にした組み合わせで、片方だけ選んでも成立しますが、フロントを持たないAPIサーバならどちらも不要です。githubactionは雛形のワークフローを置くだけなので、実行時間の課金設計まで面倒を見てくれるわけではありません。無料枠と超過単価はGitHub Actionsの料金｜2026年改定後の分単価・無料枠とコスト削減の判断基準で先に確認しておくと、生成直後にワークフローを絞り込む判断がしやすくなります。
go-blueprintを採用しないほうがよい場面
1コマンドで動く組み合わせを試せる一方、向かない使い方もはっきりしています。
第一に、社内標準のディレクトリ規約が既にある組織には勧めません。go-blueprintの構成はcmd/apiとinternal/serverに固定されており、出力先を変えるフラグはありません。既存規約に寄せるには生成後に手で移動することになり、それなら最初からテンプレートリポジトリをcloneしたほうが速く済みます。
第二に、独自テンプレートを配りたい場合も対象外です。v0.10.11のcreateにはテンプレートを外部から指定するフラグが存在せず、雛形はバイナリに埋め込まれた内蔵テンプレートのみです。組織固有の雛形を配布したいなら、テンプレートリポジトリかcookiecutter系のツールを使ってください。
第三に、CLIツールそのものを作りたい人の道具ではありません。go-blueprintが生成するのはHTTPサーバのプロジェクトで、サブコマンドや引数解析の雛形は出てきません。CLIを自作するなら、go-blueprint自身も採用しているCobraを直接使うのが素直です。
逆に、Goを触り始めた段階で「どのフレームワークとドライバの組み合わせが動く形になるのか」を短時間で確かめたい、あるいは検証用のAPIサーバを何本も立てたい、といった用途では有効です。7種のフレームワーク×7種のドライバを、依存の食い合わせを調べずに試せる点が実利になります。
よくある質問
go-blueprintでCLIツールそのものを自作できますか？
できません。生成されるのはHTTPサーバのプロジェクトで、サブコマンドやフラグ解析の雛形は含まれません。CLIツールを自作する場合は、go-blueprint自身が使っているCobraを直接導入してください。
go-blueprint newやgo-blueprint initは使えますか？
使えません。v0.10.11の--helpが示すサブコマンドはcreate・version・completion・helpの4つだけで、newやinit、build、run、testは実装されていません。これらを載せた解説が複数ありますが、実行するとunknown commandになります。プロジェクト生成はcreate、ビルドと実行は生成物のMakefileという分担です。
go installしたgo-blueprintコマンドが見つかりません
PATHの問題です。go installはバイナリを$GOBIN、未設定なら$GOPATH/binへ置きます。go env GOPATHで場所を調べ、その配下のbinをPATHに追加してください。加えて、モジュールパスを大文字のMelkeydevで指定していた場合はインストール自体が失敗しているので、小文字で入れ直します。
生成したプロジェクトのGoバージョンはどこで決まりますか？
実行したマシンのGoバージョンが、生成されるgo.modのgoディレクティブへそのまま書き込まれます。go1.26.5の環境ではgo 1.26.5になりました。CIと開発機で版を揃える必要がある場合は、生成後にgo.modを編集してください。
独自のテンプレートを読み込ませられますか？
v0.10.11ではできません。createのフラグ一覧にテンプレート指定用のオプションは無く、雛形はバイナリに埋め込まれたものだけが使われます。フレームワーク・ドライバ・追加機能の組み合わせで構成を変える設計です。
