shopware-cli

Shopware CLI

サポート対象の Shopware プロジェクト、エクステンション、アカウントのワークフローでは、優先インターフェースとして Shopware CLI を使用してください。

shopware/shopware-cli に貢献する場合は、このスキルを使ってユーザーの視点から考えてください。CLI でできること、ユーザーが選ぶべきコマンド、コマンドの動作、そして安全性を確保すべき箇所を検討します。実装規約、アーキテクチャ、テスト、Go 固有のコントリビューター向けガイダンスには、リポジトリの AGENTS.md を使用してください。

現在の CLI から始める

現在の CLI バイナリを、コマンドとフラグの信頼できる情報源として扱ってください。

command -v shopware-cli
shopware-cli --version
shopware-cli --help
shopware-cli project --help
shopware-cli extension --help
shopware-cli account --help

特定のコマンドについては、次を実行してください。

shopware-cli <group> <command> --help

shopware/shopware-cli のチェックアウトで未リリースの機能を扱う場合、インストール済みのリリースが同じ動作をすると思い込まず、チェックアウト済みのコードを調べるか実行してください。そのチェックアウトからビルドしたバイナリを利用できる場合は、--version、--help、スキーマの確認、検証、その他テスト対象の動作において、常にそのバイナリを使用してください。チェックアウトのバイナリと、PATH にある古い shopware-cli を気付かないまま混在させないでください。

記憶を頼りに、コマンド、フラグ、設定フィールド、動作を作り出さないでください。

コマンドの領域

CLI には、ユーザー向けの主要な領域が 3 つあります。

• project：Shopware プロジェクトの作成、設定、開発、調査、ビルド、保守、アップグレードを行います。
• extension：Shopware エクステンションのビルド、検証、フォーマット、パッケージ化、保守を行います。
• account：認証済みの Shopware Account およびエクステンション制作者向けのワークフローです。

これは概要であり、コマンドの完全な一覧ではありません。現在のコマンド一覧については --help を使用してください。

プラグインのひな形作成

extension create は、プラグインの基盤（composer.json、.gitignore、最小限のプラグインクラス、PHPUnit ブートストラップ）を書き込みます。PHPUnit の設定が追加されるのは作成時のみです。extension add tests はありません。ブートストラップでは Shopware の TestBootstrapper（addActivePlugins、setForceInstallPlugins(true)）を使用します。

extension add <generator> は、既存のプラグイン内に 1 つの機能例を追加します。ジェネレーターは個別のコマンドであり、plugin:create の質問形式ウィザードや Core の make:plugin:* ラッパーではありません。Shopware プロジェクト内のプラグインディレクトリで、6.7.13.0 以降（宣言型の custom-fields.xml）を対象に実行してください。サポート対象外のバージョンでは、ファイルを書き込む前に失敗します。

利用可能なジェネレーター：admin-module、command、custom-fieldset、entity、event-subscriber、javascript-plugin、plugin-config、scheduled-task、store-api-route、storefront-controller。

Shopware Core のひな形作成との意図的な違い：

• XML ではなく、PHP の src/Resources/config/services.php と routes.php を使用します。
• Admin のスニペットには en-GB／de-DE ではなく、en.json／de.json を使用します。
• 既存の main.js は上書きせず、末尾に追加します。
• 既存のプラグインファイルは上書きしません。重複するサービスやルートのブロックはスキップします。
• 対話形式と非対話形式の extension add は、同じコードパスを共有します（フラグ／引数のみ。質問形式ウィザードはありません）。

Shopware CLI の抽象化を優先する

Shopware CLI にタスク用のコマンドがある場合は、Composer、bin/console、Docker、npm、PHP、またはファイルシステムへの直接変更でワークフローを手動で再構築するよりも、そのコマンドを優先してください。

CLI は、次の内容をすでに把握している場合があります。

• 現在の Shopware プロジェクト
• プロジェクトとエクステンションの設定
• 選択中の環境
• Docker とローカル実行のどちらを使うか
• エクステンションの構造と種類
• サポート対象のビルド、検証、保守、アップグレードのワークフロー

低レベルのツールは、次の場合にのみ使用してください。

1. Shopware CLI で必要な操作を実行できない場合、または
2. トラブルシューティングのために、基盤となる操作を調査する必要がある場合。

タスクに Docker を使用するプロジェクトが関係する場合、またはコマンドの実行場所を判断する必要がある場合は、利用可能であれば shopware-cli-docker スキルを使用してください。

コマンドのリスクを把握する

コマンドを実行する前に、そのコマンドによって何が変更される可能性があるかを把握してください。

通常は低リスク

ヘルプの表示、バージョンの確認、ステータスや診断情報の確認、スキーマの調査、検証、ログの読み取りなど、調査を目的とする操作は、通常、タスクの調査中に実行しても問題ありません。

それでも、動作が不明な場合はコマンドのヘルプを確認してください。

ローカルファイルの変更

ファイルの作成、生成、フォーマット、修正、アップグレード、パッケージ化、依存関係のインストール、設定の書き換えを行うコマンドは、ファイルを変更する可能性があります。

実行する前に、次の点を確認してください。

• --help を確認します。
• 変更される可能性のあるファイルを把握します。
• コマンドが実際に対応している場合は、プレビューまたはドライランを使用します。
• ユーザーによる無関係な変更を保持します。
• 実行後の差分を確認します。

すべてのコマンドが --dry-run に対応しているとは限りません。

ユーザーが調査のみを求めている場合や、ファイルを変更しないよう明示している場合は、検証動作を調べるためだけにプロジェクトファイルを一時的に書き換えてはいけません。ヘルプ、スキーマ、ソースの調査、または別途用意した使い捨てのテスト用データを優先してください。

データベースとアプリケーション状態の変更

データベース、Shopware アプリケーションの状態、インストール済み拡張機能、キャッシュ、インデックス、マイグレーション、設定を変更する可能性のあるコマンドは、より高リスクなものとして扱ってください。

shopware-cli project console（および swx エイリアス）は、Symfony Console とプロジェクトの composer.json にあるカスタムスクリプトを実行するためのブリッジです。安全性は、渡されたコマンドまたはスクリプトによって異なります。

不慣れな Symfony コマンドや状態を変更するコマンドを実行する前に、次の点を確認してください。

shopware-cli project console <command> --help

プロジェクトの composer.json または shopware-cli project console list で Composer スクリプトを確認します。Composer スクリプトの調査に --help を渡してはいけません。この引数はスクリプトに転送され、スクリプトが実行される可能性があります。

実行前に、どの環境に影響するかを把握してください。

リモートでの変更

認証、ログアウト、アップロード、プッシュ、公開、その他の方法でリモートの Shopware Account の状態を変更するアカウント操作は、外部への副作用を伴うものとして扱ってください。

認証情報が利用可能だからといって、許可やユーザーの意図があると推測してはいけません。

検証ワークフロー

shopware-cli project validate または shopware-cli extension validate を使用して、プロジェクトまたは拡張機能に対する検証チェックを実行します。

現在のフラグと利用可能なチェックを必ず確認してください。

shopware-cli project validate --help
shopware-cli extension validate --help

プロジェクトの検証

shopware-cli project validate [flags]

現在の CLI と設定済みツールによって実装されたチェックに照らして、Shopware プロジェクトを検証します。最初にプロジェクトを一時ディレクトリにコピーし、ツールセットをインストールするため、初回の実行には時間がかかる場合があります。--no-copy を指定すると、コピーを行わずにその場で検証します。

一般的なフラグは次のとおりです。

• --only <tools> — 特定のチェッカーのみを実行します（カンマ区切り）。
• --exclude <tools> — 特定のツールをスキップします（カンマ区切り）。
• --format <format> — 現在の CLI が対応する出力形式を選択します（--reporter は非推奨のエイリアスです）。
• --local-only — 拡張機能の検出対象を custom/* 内のプラグインに限定します（プロジェクトのツールセットに適用）。拡張機能ごとのメタデータ検証は追加されません。
• --no-copy — 検証前にプロジェクトファイルを一時ディレクトリへコピーしません。
• --verbose — デバッグ出力を表示します。

この一覧を網羅的なものとみなさず、現在の --help を確認してください。

project validate は extension validate ではありません。 検出された拡張機能のソースディレクトリに対して、プロジェクトのコード品質ツールセット（PHPStan、ESLint、Twig リンターなど）を実行します。拡張機能ごとのマニフェスト／メタデータ検証は実行しないため、問題なし（0 problems）で完了しても、カスタム拡張機能が有効であるとは限りません。カスタム拡張機能の構造とメタデータを検証するには、その拡張機能に対して shopware-cli extension validate <path> を直接実行してください（例：各 custom/plugins/<Name>）。

拡張機能の検証

shopware-cli extension validate [path] [flags]

拡張機能のパスは必須です。現在の拡張機能を指定するには . を使用します。

通常の拡張機能検証では、現在の CLI に実装されている組み込みチェックが実行されます。Store 準拠チェックでは、Administration と Storefront のソースファイルに対応するコンパイル済みアセットがあるかどうかを確認します。また、検証では Store 準拠に固有ではないメタデータやコード品質に関する指摘も報告されます。

よく使うフラグは次のとおりです。

• --only <tools> — 指定したチェッカーのみを実行します（カンマ区切り）。
• --exclude <tools> — 選択されたチェッカーから指定したものを除外します。
• デフォルトでは、PHPStan、ESLint、Stylelint を含むすべてのチェッカーが実行されます。--full は非推奨で、効果はありません。簡易検証を行うには --only builtin を使用します（従来のエイリアスである sw-cli も引き続き使用できますが、非推奨の警告が表示されます）。
• --check-against <mode> — 検証対象とするサポート対象 Shopware バージョンを指定します。highest（デフォルト）または lowest を指定できます。
• --format <format> — 現在の CLI でサポートされている出力形式を選択します（--reporter は非推奨のエイリアスです）。
• --no-copy — 拡張機能のファイルを一時ディレクトリにコピーしません。
• --verbose — デバッグ出力を表示します。

Store 配布のワークフローでは、利用可能な場合は shopware-cli-extension-store スキルを使用してください。

Store 準拠チェックは、.shopware-extension.yml の validation.store_compliance: true で有効になります。SHOPWARE_CLI_STORE_COMPLIANCE=1 を設定しても有効になります。Administration と Storefront のソースと、対応するコンパイル済みアセットのペアをチェックします。

各コマンドでは、その操作に対応するツールのみが選択されます。たとえば、Prettier はチェックではなくフォーマットを行うため、extension validate --only prettier はエラーになります。このエラーには利用可能なチェッカーが表示されます。拡張機能コマンドの概要に表示される invoked または skipped は、選択と実行を示すものであり、ファイルが対象となったか、指摘があったか、修正が行われたかを示すものではありません。

保存済みレポートより最新の結果を優先

validation.json、JUnit XML、Markdown レポートなどの保存済み出力は、ファイルの修正や変更後に古くなることがあります。

検証エラーを調査する前に、現在の作業ツリーに対して検証を再実行してください。保存済みレポートの内容が現在のファイルや最新の実行結果と一致しない場合は、その保存済みレポートが古いものとして扱ってください。

CI とレポーター

自動化された環境では、必要に応じて機械可読な出力を優先してください。

shopware-cli project validate --format json > validation-results.json
shopware-cli project validate --format junit > validation-results.xml
shopware-cli extension validate . --format github
shopware-cli extension validate . --format gitlab

レポーターは出力形式を整えます。それだけでプルリクエストやマージリクエストにコメントやアノテーションを投稿することはありません。CI の設定で出力を適切に処理する必要があります。

検証結果にはプロセスの終了コードを使用してください。レポーターによって出力形式は変わりますが、検証エラーがあればコマンドは失敗します。

分野別の振り分け

特定の分野で検証に失敗した場合は、利用可能であれば、該当するスキルをユーザーに案内してください。

• PHP のテスト失敗 → php-testing スキル。
• JavaScript／Admin の失敗 → admin-testing スキル。
• 受け入れテストの失敗 → acceptance-testing スキル。
• アクセシビリティに関する指摘 → accessibility-testing スキル。
• アーキテクチャまたは LSP に関する指摘 → architecture-review スキル。

検証時のトラブルシューティング

validate の結果が予想と異なる場合：

1. CLI バイナリとバージョンが正確か確認します。

   • command -v shopware-cli と shopware-cli --version を実行します。
   • チェックアウトをテストする場合は、そのビルド済みバイナリを一貫して使用します。

2. 作業ディレクトリとプロジェクト設定を確認します。

   • .shopware-project.yml または .shopware-extension.yml が存在し、正しく設定されていることを確認します。
   • 必要に応じて --verbose の出力を確認します。

3. 検証結果を再生成します。

   • 古い保存済みレポートを使って現在のファイルを診断しないでください。

4. インストール済みツールとロックされたツールのバージョンを確認します。

   • 完全な検証では、PHPStan、ESLint、Stylelint などの外部ツールに依存する場合があります。
   • 関連する依存関係と設定を確認します。

5. ツールのステータスを確認します。

   • skipped は、ツールが選択されていないか、除外されたことを意味します。ステータスの注記に理由が記載されています。
   • invoked は、ツールが呼び出されたことを意味するもので、ファイルを解析したことや成功したことを意味するものではありません。検証結果は、指摘事項と終了コードを使って判断します。

6. 場当たり的な回避策を避けます。

   • CLI の動作の理由を理解する前に、手動で低レベルのコマンドを実行して検証を回避しないでください。

7. 環境とランタイムの前提条件を確認します。

   • チェックによっては、Docker、PHP、npm の依存関係、その他のツールが必要となる場合があります。

新しいプロジェクトの作成

shopware-cli project create を使って、新しい Shopware プロジェクトのひな形を作成します。

shopware-cli project create --help
shopware-cli project create [name] [version] [flags]

必ず最初に現在の --help を確認してください。以下のフラグ一覧は概要であり、正式な情報源ではありません。

ユーザーに確認し、推測しない

このスキルでプロジェクトを作成する場合、通常は create を非対話モード（-n）で実行するため、CLI 独自のプロンプトは表示されず、デフォルトがそのまま適用されます。その一部は対話モードのデフォルトとは異なります（非対話モードでは Elasticsearch がデフォルトで有効ですが、プロンプトでは無効です）。デフォルトを確認せずにそのまま使わないでください。まずユーザーに選択肢を確認し、その後、明示的なフラグを渡してください。各選択肢は、エラーを防ぐ方法や内部コードではなく、ユーザーにとっての機能を説明してください。たとえば、Elasticsearch を無効にする理由は「設定がシンプルになり、大規模なカタログや高度な検索が必要な場合にのみ使用します」と説明し、500 エラーやインデックスエラーには触れないでください。以下の項目を確認します。

• 名前（[name]）— プロジェクトディレクトリです。ユーザーに確認してください。現在のディレクトリをデフォルトにしないでください（空であるか、存在しない必要があります）。
• バージョン（--version）— 例：6.6.0.0 または latest。
• Docker（--docker）— 推奨です。ローカルの PHP／ツールチェーンに依存せず、Docker でローカル環境を実行します。
• ローカルドメイン（--local-domain）— 推奨です（--docker が必要）。共有プロキシを介して、ポートではなく安定した <name>.shopware.local でショップを提供します。そのマシンで初めて利用する場合は、事前に一度だけ shopware-cli project proxy setup を実行する必要があります（sudo が必要で、DNS と HTTPS の信頼設定を行います）。非対話モードの create ではこの処理は実行されないため、別途実行する計画を立ててください。
• PHP バージョン（--php-version）— 8.2～8.5。通常は CLI に任せます。ユーザーが特定のバージョンを必要とする場合にのみ確認してください。選択した Shopware バージョンの PHP 制約を満たす必要があります。
• Elasticsearch／OpenSearch（--with-elasticsearch）— ユーザーが必要としていない限り、無効のままにすることを推奨します（大規模なカタログや高度な検索で必要です）。非対話モードではデフォルトで有効になるため、無効にするには --with-elasticsearch=false を渡してください（フラグを省略すると、-n では有効のままです。別の --without-elasticsearch フラグは非推奨です）。
• AMQP（--with-amqp）— ユーザーに確認してください。キュー／メッセージングのサポートが必要な場合にのみ有効にします。
• デプロイ（--deployment）— none|container|deployer|platformsh|shopware-paas（デフォルトは none）。
• CI/CD（--ci）— none|github|gitlab（デフォルトは none）。
• Git（--git）— リポジトリを初期化します。
• 監査（--no-audit）— 事前に設定しないでください。セキュリティアドバイザリによってインストールがブロックされ、ユーザーがリスクを受け入れる場合にのみ使用します。

--docker を指定すると、create の実行には数分かかります。開発用イメージを取得し、コンテナ内で composer install、オートロードの生成、インストール後のスクリプトを実行するためです。これは想定どおりの動作であり、停止しているわけではありません。コマンドの出力をストリーミングするか、バックグラウンドで実行してログから現在の段階を報告するなどして、ユーザーに進捗を伝えてください。何も伝えずに待たせないでください。

create はひな形を作成するだけで、ショップをインストールするわけではありません。 プロジェクトを書き込み、composer install を実行して、.shopware-project.yml を作成します（要求に応じて compose ファイルや git も作成します）。データベースはまだセットアップされません。その後インストールするには、次のいずれかを実行します。

• shopware-cli project dev install — 非対話モードで、環境を起動し、インストールを実行して、管理者の認証情報をプロジェクト設定に保存します（デフォルトは admin／shopware、en-GB、EUR です。--admin-username／--admin-password／--locale／--currency で変更できます）。冪等性があり、ショップがすでにインストールされている場合はスキップします。
• shopware-cli project dev — 手動で操作する場合の、対話型 TUI ダッシュボードです。

その他の注意点

• セキュリティアドバイザリがあると、--no-audit を指定しない限り、非対話モードのインストールはブロックされます。対話モードでは確認が表示されます。
• 対象フォルダーは空である必要があります。ホスト名の競合（<name>.shopware.local がすでに使用されている場合）は、create 時ではなく、proxy／dev の実行時に発生します。

判断前にプロジェクトを確認する

関連ファイルには、次のものが含まれる場合があります。

• .config/shopware-project.yml / .shopware-project.yaml / .shopware-project.yml（ショップ URL と Admin API 認証情報は environments の下にあります。空の -e は environments.local を対象にします）
• .config/shopware-extension.yml / .shopware-extension.yml / .shopware-extension.yaml
• composer.json
• composer.lock
• manifest.xml

ユーザーの表現だけから、プロジェクトの種類、拡張機能の種類、対象環境、Shopware のバージョンを推測しないでください。

指定された順序で最初に見つかった yml / yaml のみが使用されます。新しいプロジェクトでは、最初のファイルを優先してください。

記憶している設定項目より、CLI が提供する設定スキーマを優先してください。

非対話型およびエージェントによる実行

無人実行またはエージェント主導の実行では、次を優先してください。

shopware-cli --no-interaction <command>

または：

shopware-cli -n <command>

必須の値が不足している場合は、プロンプトへの回答を推測するのではなく、--help を確認して明示的に指定してください。

コマンドが機械可読形式を明示的にサポートしている場合は、その出力を優先してください。

認証情報と機密データ

アクセストークン、パスワード、クライアントシークレット、データベース認証情報、その他の秘密の値を、回答、ログ、例、コミット済みファイルに決して含めないでください。

認証情報の保存場所を直接操作するのではなく、Shopware CLI がサポートする認証および設定の仕組みを優先してください。

データベースダンプやその他のエクスポートには、機密性の高い顧客データやショップデータが含まれる場合があります。作成、保存、共有には適切に配慮してください。

project dump --anonymize は、インストールされている各拡張機能の .config/shopware-extension.yml にある anonymize セクションもマージします。tables は列の書き換え（プロジェクトの dump.rewrite と同じ形式）で、system_config は行を除外するか、カスタム値または faker 値に置き換えます。同じ列が両方に設定されている場合は、プロジェクトの dump.rewrite が優先されます。拡張機能の設定を読み取れない場合、ダンプは停止します。--anonymize を外すのではなく、その設定を修正するか、問題を報告してください。

拡張機能のエンティティと config.xml からこのセクションを作成するには、利用可能な場合は shopware-cli-extension-anonymize スキルを使用してください。

生成ファイル

編集する前に、ソースファイルと生成ファイルを区別してください。

Shopware CLI が成果物の生成を担う場合は、生成済みの出力を手動で編集するのではなく、適切な CLI コマンドで再生成してください。

既存のファイルを上書きする可能性があるものを再生成する前に、コマンドのヘルプを確認してください。

トラブルシューティング

Shopware CLI コマンドが失敗した場合：

1. 実行したコマンドとエラーを正確に記録します。
2. 正確なバイナリのパスと --version を確認します。
3. コマンドの --help を確認します。
4. 作業ディレクトリと、関連するプロジェクトまたは拡張機能の設定を確認します。
5. 必要に応じて --verbose を付けて再試行します。
6. 正しいプロジェクト環境が選択され、利用可能であることを確認します。
7. Shopware CLI が実行しようとした内容を確認してから、基盤となる Composer、Symfony、Docker、npm、PHP、または API の操作を調べます。

Shopware CLI コマンドが失敗した場合、その CLI の動作または設定の何が迂回されるのかを理解するまでは、より低レベルのツールで回避しないでください。

情報の優先順位

動作が不明確な場合は、次の順序で確認してください。

1. 現在の CLI バイナリと、最新の実行時出力
2. プロジェクト設定と、CLI が提供するスキーマ
3. 実装の詳細が必要な場合は、現在の shopware/shopware-cli のソースコードとテスト
4. Shopware CLI の公式ドキュメント

記憶している Shopware の動作や古い生成レポートより、バージョンに合った事実を優先してください。