Shopify CLIの使い方｜ローカル開発環境とテーマ運用の実務手順

「shopify cli」で調べる人の多くは、単にインストールコマンドを知りたいわけではありません。

ローカルでテーマを触りたい。theme devでプレビューしたい。管理画面で編集した内容をローカルへ戻したい。制作会社とストア運営者で同じテーマを扱いたい。GitHub連携を使いたい。けれど、公開テーマに誤ってpushしないか、別ストアへ反映しないか、誰かの管理画面編集を上書きしないかが不安。実務ではそこが問題になります。

Shopify公式のShopify CLIでは、CLIはShopifyアプリ、テーマ、カスタムストアフロントを生成・操作し、開発タスクを自動化するためのコマンドラインツールとして説明されています。テーマ開発に絞ったShopify CLI for themesでは、development theme、プレビュー、共有、push、publish、environments、Theme Checkなどが扱われます。

この記事では、Shopifyテーマ開発の実務設計で扱ったLiquid、sections、メタフィールドの設計とは重複させません。主役は、Shopify CLIそのものの導入、認証、ストア指定、コマンド運用、GitHub連携、誤反映防止です。

Shopify CLIの運用品質は、コマンドを覚えているかではなく、対象ストア・対象テーマ・反映経路を毎回確認できる仕組みがあるかで決まります。

先に結論：CLIは「反映ルート」を分けて使う

Shopify CLIは便利ですが、どの作業もCLIに寄せればよいわけではありません。管理画面、CLI、GitHub連携はそれぞれ役割が違います。

作業場所	向いていること	避けたいこと	運用上の注意
Shopify管理画面	テーマエディタでの設定変更、画像差し替え、セクションの並び替え、EC担当者の軽微な調整	コードエディタで公開テーマを直接修正し続ける	GitHub連携中は管理画面編集もコミット化されるため、誰が触るかを決める
Shopify CLI	ローカル編集、development themeでの確認、テーマのpull/push/share/publish、Theme Check	対象ストアやテーマIDを曖昧にしたままpushする	--store、theme info、theme list、environmentで確認する
GitHub連携	レビュー、差分管理、ブランチ運用、公開テーマとの同期	管理画面編集とローカルpushを無秩序に混ぜる	Shopify側の自動コミット、競合、接続ブランチを理解する
CI/CD	決まったテーマへの定型push、Theme Check、公開前の機械確認	人の承認なしに公開テーマへpublishする	トークン、環境、対象テーマID、--allow-liveの扱いを厳しくする

最初に作るべきなのは、CLIの手順書ではなく、反映ルートの設計です。

変更の種類	第一候補	理由
トップページの文言や画像の差し替え	管理画面のテーマエディタ	EC担当者が編集しやすく、コード変更にしなくてよい
sectionやsnippetのLiquid修正	CLI + Git	差分レビューとロールバックが必要
CSS/JSの調整	CLI + development theme	実データでプレビューしながら確認する
キャンペーン用の一時テーマ	CLIのtheme shareまたは未公開テーマ	公開テーマを触らず関係者確認できる
本番テーマの継続管理	GitHub連携 + ブランチ運用	管理画面編集とコード差分を追跡しやすい
外部システム連携やAPI開発	Shopify app側のCLI、Admin API	テーマCLIではなくアプリ開発の領域

前提環境：Node.jsとGitをそろえる

Shopify CLI本体の公式ドキュメントでは、Node.js 22.12以上、npm/Yarn/pnpmなどのNode.jsパッケージマネージャー、Git 2.28.0以上が要件として示されています。インストールはnpm、Yarn、pnpm、macOSならHomebrewでも可能です。

ただし実務では、インストールできたかより、チーム内で実行環境をそろえることの方が重要です。

前提	確認すること	運用ルール
Node.js	バージョンがShopify CLI要件を満たすか	node -vを手順書に残し、古い端末を混ぜない
パッケージマネージャー	npm、Yarn、pnpmのどれで管理するか	チーム内で実行例を統一する
Git	バージョン、ユーザー名、メール、署名方針	Shopify GitHub連携やレビュー運用と合わせる
Shopify CLI	shopify versionで確認できるか	自動アップグレードの有無を把握する
テーマディレクトリ	assets、config、layout、locales、sections、snippets、templatesなどがあるか	CLIコマンドを実行する場所を固定する
権限	Themes権限、Manage themes権限、Theme Accessなど	担当者ごとに公開可能範囲を分ける

Shopify CLIはグローバルインストールで使うことが多いですが、アプリ開発ではプロジェクトローカル依存としてCLIバージョンをそろえる選択肢もあります。テーマだけを扱う場合でも、制作会社と社内担当でCLIバージョンが大きく違うと、表示やフラグの挙動で混乱します。

認証：誰の権限で、どのストアを触るか

Shopify CLI for themesでは、テーマ作業の認証方法として、Shopifyアカウントでログインする方法、Theme Access passwordを使う方法、custom app access tokenを使う方法が説明されています。Shopifyアカウントの場合は、ストアオーナー、Themes権限のあるstaff account、Manage themes権限のあるcollaborator accountなどが候補です。

実務では、認証方法を次のように分けます。

認証方法	向いている場面	注意点
Shopifyアカウントログイン	社内担当、正式なcollaboratorがテーマを触る	個人アカウントの権限で公開テーマまで触れる可能性がある
Theme Access password	制作会社や外部開発者にテーマ作業だけを渡す	コマンドごとに--passwordまたは環境変数の扱いを決める
custom app access token	CI/CDや機械実行でテーマを操作する	read_themes、write_themesなど必要スコープを限定する
GitHub連携	ブランチを通じてテーマを同期する	Shopify管理画面の編集もGitHubへ自動コミットされる

個人のShopifyログインに頼る運用は、最初は楽です。しかし、退職、権限変更、複数ストア、外部制作会社の出入りがあると危険です。誰が何の権限でCLIを実行してよいかを、ストア単位で決めます。

--storeとtheme infoを毎回確認する

Shopify CLIでは、ストアアクセスが必要なコマンドを最初に実行するとき、--storeで対象ストアを指定します。公式ドキュメントでは、指定したストアは次回以降のコマンドでも使われ、変更したい場合は再度--storeを渡すと説明されています。現在の設定はshopify theme infoで確認できます。

ここは誤反映防止の最重要ポイントです。

確認タイミング	実行例	見ること
作業開始時	shopify theme info	Storeが想定の.myshopify.comか
初回接続時	shopify theme dev --store example-store	ブラウザログイン先が正しいか
push前	shopify theme list --store example-store	対象テーマID、role、nameが合っているか
pull前	shopify theme list --store example-store	live、unpublished、developmentのどれからpullするか
publish前	shopify theme infoと管理画面	公開対象が未公開テーマで、承認済みか

my-storeのような短いprefixで指定できるのは便利ですが、複数ストアを扱う制作会社では危険です。手順書には、できるだけ完全なmyshopify.comドメイン、テーマID、テーマ名を残します。

Shopify CLIで最も怖い事故は、コマンドの失敗ではなく、成功したコマンドが別ストアや別テーマに向いていたことです。

theme devとdevelopment themeの扱い

shopify theme devは、現在のローカルテーマをストアに接続し、development themeとしてプレビューするためのコマンドです。公式のtheme devコマンドリファレンスでは、ローカル変更をホットリロードできる127.0.0.1:9292のリンク、Shopify管理画面のテーマエディタリンク、共有用プレビューリンクが返ると説明されています。

development themeは、一時的で非公開のテーマです。公式ドキュメントでは、development themeはテーマ上限に数えられず、7日間操作がないと削除され、shopify auth logoutでも削除されると説明されています。ログアウト後も使えるプレビューを残したい場合は、未公開テーマへpushする必要があります。

項目	development themeの特徴	実務での扱い
公開状態	hiddenで一時的	本番公開先として扱わない
データ	接続ストアのデータを使える	実商品・実設定で表示確認できる
URL	ローカルURL、テーマエディタ、共有プレビューが出る	関係者レビューに使う
寿命	7日間非アクティブで削除、logoutでも削除	長期レビューは未公開テーマへpushする
編集	テーマエディタで操作できる	設定変更をローカルへ残す手順を決める
事故防止	live themeではない	ただし接続ストアは本物なのでストア指定を確認する

theme devは、公開テーマを直接変更するコマンドではありません。ただし「安全だから何でもよい」ではありません。development theme上でテーマエディタを触った設定をローカルへ戻すのか、単なる確認として捨てるのかを決めないと、レビュー時の見た目とGit上の実装がズレます。

主要コマンドの使いどころ

Shopify CLIのtheme commandsには、theme dev、theme pull、theme push、theme share、theme publish、theme list、theme info、theme checkなどがあります。覚えるべきなのはコマンド名より、いつ使い、何を上書きする可能性があるかです。

コマンド	使いどころ	危険ポイント	実務ルール
shopify theme info	現在のストア・環境確認	確認せず作業すると別ストア事故になる	作業開始、push前、publish前に実行する
shopify theme list	テーマID、名前、role確認	live/unpublished/developmentを取り違える	IDとroleを台帳へ残す
shopify theme dev	ローカル変更をdevelopment themeで確認	接続ストアを間違える	必ず--storeまたはenvironmentで対象を明示する
shopify theme pull	Shopify上のテーマファイルをローカルへ取得	ローカル差分を上書きする可能性	pull前にGit statusを見て、対象テーマIDを指定する
shopify theme push	ローカルテーマをShopifyへアップロード	remote themeを上書きする	原則、未公開テーマかdevelopment themeに限定する
shopify theme share	新しい未公開テーマを作りプレビュー共有	ランダム名でテーマが増える	レビュー用の一時テーマとして期限を決める
shopify theme publish	未公開テーマをliveにする	公開切替が発生する	承認、テーマID、戻し先を確認してから実行する
shopify theme check	Theme Checkを実行	実行だけで品質は保証されない	publish前の最低確認に入れる

theme pushは、ローカルテーマをShopifyへアップロードし、対象のremote themeを上書きします。テーマを指定しない場合は選択プロンプトが出ますが、CIや手順化ではプロンプトに頼らず、--store、--theme、--environmentを使って対象を明示します。

theme publishは、未公開テーマを公開テーマにします。ローカルテーマを公開したい場合は先にtheme pushが必要です。公開確認を省略できるフラグもありますが、チーム運用では安易に使わない方がよいです。

environmentでストアとテーマを分ける

Shopify CLI for themesでは、storeやthemeなどコマンド設定を毎回フラグで渡す代わりに、environmentsとして名前付きで参照できると説明されています。複数の開発ストア、Theme Access password、development/staging/productionのテーマを切り替える場合に有効です。

environment	指す対象	使う場面	禁止事項
dev	開発ストア、development theme	日常のローカル確認	本番ストアのlive themeを指さない
staging	本番ストア内の未公開テーマ	関係者レビュー、公開前確認	直接publishしない
production	本番ストアの公開候補テーマ	承認後の最終反映	自動pushや無承認publishをしない
client-a	クライアントAのストア	制作会社の複数顧客対応	他社ストアと設定を共用しない

environmentは便利ですが、名前だけで安心してはいけません。productionという名前が、実際にはどのストア、どのテーマIDを指すのかを定期的に確認します。運用台帳には、environment名、store domain、theme ID、theme role、用途、実行可能なコマンドを書いておきます。

.shopifyignoreでアップロード対象を制御する

テーマリポジトリには、README、設計メモ、ビルド前ファイル、スクリーンショット、検証用JSON、ローカル設定など、Shopifyへアップロードしたくないファイルが混ざることがあります。Shopify CLI for themesでは、テーマルートの.shopifyignoreでCLIが扱わないファイルを指定でき、--ignoreフラグでもpush/pull時に除外できると説明されています。

除外したいもの	理由	例
ローカルメモ	ストアへアップロードする意味がない	docs/、notes/
秘密情報に近い設定	誤ってテーマへ含めると危険	config/*_secret.json
生成元ファイル	ビルド後の成果物だけを反映したい	src/、*.map
検証用画像	テーマ容量や管理画面を汚す	screenshots/、*.psd
一時テンプレート	誤って本番へ入ると表示崩れの原因	templates/product.temp.json

.shopifyignoreは、事故を完全に防ぐものではありません。対象テーマやpush先を間違えれば、除外されていないファイルは反映されます。とはいえ、不要ファイルをShopify側へ持ち込まない最低限の柵として必ず整備します。

公開テーマへの誤pushを防ぐ

公開テーマへのpushは、基本的に日常作業から外します。Shopify CLIのtheme pushにはlive themeへのpushを許可するフラグがありますが、これは「可能」というだけで、通常運用で多用すべきという意味ではありません。

リスク	起きる状況	防止策
live themeへ直接push	テーマ指定なしで選択を誤る、--liveや許可フラグを使う	原則未公開テーマにpushし、publishで切り替える
別ストアへpush	前回の--store設定が残っている	theme infoと完全なstore domain確認を必須にする
管理画面編集を上書き	pullせず古いローカルからpushする	GitHub連携、自動コミット、pull方針を決める
不要ファイルを反映	.shopifyignore未整備	push対象ファイルを制限する
削除差分で壊す	ローカルにないremote fileが削除される	必要に応じて--nodeleteを使い、削除差分をレビューする
公開切替後に戻せない	旧テーマIDや戻し先を記録していない	publish前に旧live theme、公開候補、戻し方を台帳化する

安全な基本形は、ローカル編集、development themeで確認、未公開テーマへpush、プレビュー承認、publish、公開後確認、旧テーマ保持です。

段階	コマンド・場所	確認すること
作業開始	git status、shopify theme info	ローカル差分、対象ストア
ローカル確認	shopify theme dev --store ...	表示、テーマエディタ、スマホ
共有	theme devのpreview URL、またはtheme share	関係者が見られるURLか
反映準備	shopify theme push --theme <unpublished-theme-id>	未公開テーマに入っているか
公開判断	管理画面、チェックリスト	承認者、対象ページ、戻し方
公開	shopify theme publish --theme <id>	公開テーマIDが切り替わったか
公開後	管理画面、主要URL、カート	表示、購入導線、計測、アプリ表示

GitHub連携と管理画面編集の扱い

Shopify公式のGitHub integration for themesでは、Shopify GitHub appにより、GitHubリポジトリとShopifyテーマを同期し、複数開発者でテーマコードを扱えると説明されています。ブランチを未公開テーマや公開テーマに接続でき、接続ブランチへのコミットはShopify管理画面のテーマへ反映されます。

重要なのは、逆方向もあることです。公式ドキュメントでは、Shopify管理画面のテーマエディタ、コードエディタ、テーマアプリでの編集が、接続されたGitHubブランチへ自動コミットされると説明されています。この自動コミットは無効化できません。

変更元	GitHub連携時の挙動	実務で決めること
ローカルからGitHubへpush	接続テーマへ反映される	PRレビュー後に接続ブランチへマージする
テーマエディタで保存	設定ファイルなどがShopify botのコミットになる	EC担当者の編集時間帯とレビュー方法を決める
コードエディタで保存	GitHub側を上書きする可能性がある	原則禁止、緊急時だけ記録付きで許可する
テーマアプリの変更	関連変更が反映される場合がある	アプリ設定変更の担当と確認範囲を決める
競合	テーマエディタでは警告される場合があるが、コードエディタでは競合警告がない	管理画面編集とGit作業を同時にしない

管理画面編集を完全に禁止する必要はありません。EC担当者がテーマエディタでセクションを並べ替える運用は自然です。ただし、GitHub連携している場合、その編集は「コード差分」として残ります。誰が、いつ、なぜ変えたのかをコミットと台帳で追える状態にします。

app devとtheme devを混同しない

Shopify CLIにはテーマ用だけでなく、アプリ用のコマンドもあります。公式のShopify CLI for appsでは、アプリ生成、app extensions生成、Dev Dashboardのapp records作成、トンネルでのプレビュー、アプリ設定やextensionsのdeployなどが説明されています。

テーマCLIとアプリCLIは同じshopifyコマンド配下にありますが、責務は違います。

領域	主なコマンド	扱うもの	向いている要件
テーマ開発	shopify theme dev、theme pull、theme push、theme publish	Liquid、sections、assets、theme settings	商品ページ表示、CSS、テーマ構造、プレビュー
アプリ開発	shopify app init、app dev、app deploy	アプリ本体、extensions、Functions、設定	管理画面アプリ、外部連携、Functions、app blocks
API連携	アプリ側実装 + Admin API	商品、在庫、注文、顧客など管理データ	WMS、CRM、会計、PIM連携
ストアフロントAPI	Hydrogenや独自フロント	商品検索、カート、ヘッドレス購入体験	ヘッドレスECや外部サイト

たとえば、商品ページの文言配置を変えるならテーマCLIです。注文を会計へ送るなら、Shopify APIの種類と選び方で整理したように、Admin APIやWebhookを含むアプリ/連携設計です。GraphQLのquery/mutation設計はShopify GraphQL設計ガイドで別に扱っています。

よくあるエラーと復旧

Shopify CLIのトラブルは、コマンド単体の問題に見えても、実際は認証、権限、ストア指定、テーマID、GitHub連携、ローカル差分の問題であることが多いです。

症状	よくある原因	まず見る場所	復旧方針
ログインを求められ続ける	ブラウザの別アカウント、期限切れ、権限不足	Shopifyログイン中アカウント、shopify auth logout後の再ログイン	正しいアカウントでログインし直す
dev storeに接続できない	store ownerまたはstaff権限がない	ストアのユーザー権限	必要権限を付与する
テーマ一覧が想定と違う	--storeが別ストアを向いている	shopify theme info、theme list --store ...	store domainを明示して再実行
theme devで表示が古い	ローカル差分、キャッシュ、development themeの入れ替わり	ターミナル出力、ローカルURL、テーマエディタ	devを再起動し、対象environmentを確認
プレビューURLが使えない	development themeが削除、logout、非アクティブ	development themeの性質、ログイン状態	長期レビューは未公開テーマへpush
pullでローカル差分が消えそう	未コミット差分がある	git status、pull対象テーマ	先にコミットまたは退避し、対象テーマIDを指定
push先を迷う	テーマID/roleが不明	theme list、管理画面のテーマカード	未公開テーマへpushし、liveは直接触らない
GitHub連携で競合する	管理画面とGitHubで同時編集	GitHub commits、Shopify theme cardのログ	片方を止め、GitHubで差分を解決
管理画面編集が勝手にコミットされる	GitHub接続テーマを編集している	GitHubのShopify bot commit	仕様として受け入れ、編集ルールを決める
公開後に表示が崩れた	publish対象誤り、未確認ページ、アプリ表示崩れ	旧テーマID、公開候補ID、主要URL	旧テーマへ戻すか、直前コミットを戻す

復旧手順は、エラーが起きてから考えるものではありません。公開前チェックとセットで決めます。

公開前チェックリスト

CLIで作った変更は、コード差分だけでなく、ストア上の表示、テーマ設定、アプリ、計測、購入導線まで確認します。

チェック項目	見る内容
対象ストア	theme infoのStoreが正しいか
対象テーマ	theme ID、theme name、roleが承認済みのものか
反映方法	development theme、未公開テーマ、GitHub連携、publishのどれか
ローカル差分	Git上でレビュー可能な差分になっているか
.shopifyignore	不要ファイル、秘密情報、生成元ファイルが除外されているか
管理画面編集	テーマエディタで変更した設定がGitやローカルへ反映されているか
主要ページ	トップ、商品、コレクション、カート、固定ページ、検索
例外商品	在庫切れ、バリエーション多数、メタフィールド未入力、長文
アプリ表示	レビュー、チャット、診断、計測タグが消えていないか
戻し方	旧live theme、直前コミット、設定値の戻し先が分かるか

theme checkは有効ですが、公開判断の全部ではありません。Liquidやテーマの静的な問題を見つける助けにはなりますが、商品データ、アプリ、管理画面設定、購入導線、計測の確認は別に必要です。

チーム運用ルールの最小セット

Shopify CLIをチームで使うなら、最低限次のルールを決めます。

ルール	内容
作業開始ルール	git status、shopify theme info、対象チケットを確認してから作業する
ストア指定ルール	--storeまたはenvironmentで対象を明示し、短い通称だけに頼らない
テーマIDルール	live、staging、review、developmentのテーマIDを台帳化する
pullルール	管理画面編集がある場合、誰がいつどのテーマからpullするか決める
pushルール	原則、未公開テーマかdevelopment themeへpushする
publishルール	承認者、公開時刻、戻し方、旧テーマIDを記録する
GitHub連携ルール	接続ブランチ、管理画面編集の許可範囲、Shopify bot commitのレビュー方針を決める
外部制作会社ルール	Theme Access、権限、作業対象、納品物、レビュー手順を明示する
緊急対応ルール	管理画面コードエディタで触った場合の記録、後追いコミット、再発防止を決める

このルールがあると、担当者が変わっても「どのコマンドを打てばよいか」ではなく「どのテーマに、どの責任で反映するか」を判断できます。

まとめ

Shopify CLIは、テーマ開発をローカルで進めるための便利なツールです。theme devでdevelopment themeを作り、実ストアデータに近い状態でプレビューし、theme pull、theme push、theme share、theme publishを使って確認と反映を進められます。

しかし、CLI導入だけでは安全な運用にはなりません。Node.jsやGitの前提、認証、Theme Access、--store、theme info、environment、.shopifyignore、GitHub連携、管理画面編集、公開テーマへの誤push防止、エラー復旧まで含めて設計して初めて、チームで使える開発環境になります。

Bitlightでは、Shopify CLIを単なるテーマ編集コマンドとしてではなく、制作会社、EC担当者、外部開発者が同じ前提で扱えるテーマ運用として整理します。公開テーマを壊さず、プレビュー、承認、公開、復旧まで説明できる状態を作ることが、Shopify開発環境の本当の価値です。