From a37a8d33af070ac492ce70a96863d6cb95db62b5 Mon Sep 17 00:00:00 2001
From: "shopware-docs-updater[bot]"
 <313750211+shopware-docs-updater[bot]@users.noreply.github.com>
Date: Mon, 24 Aug 2026 09:23:27 +0000
Subject: [PATCH 1/2] docs: document project sql --file flag

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .../cli/project-commands/helper-commands.md   | 23 +++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/products/tools/cli/project-commands/helper-commands.md b/products/tools/cli/project-commands/helper-commands.md
index 790b6dd66..e42c8cc43 100644
--- a/products/tools/cli/project-commands/helper-commands.md
+++ b/products/tools/cli/project-commands/helper-commands.md
@@ -129,6 +129,29 @@ shopware-cli project console <command>
 
 A shorter `swx` alias is also available. See [Running Shopware commands](../../../../guides/development/dev-environment.md#running-shopware-commands).
 
+## SQL shell
+
+The `project sql` command connects to the configured database and executes SQL, without needing to look up connection details manually:
+
+```bash
+shopware-cli project sql "SELECT * FROM sales_channel"
+```
+
+Without a query argument, it starts an interactive SQL shell. It also accepts a script from stdin:
+
+```bash
+shopware-cli project sql < script.sql
+```
+
+Or from a file with `--file`:
+
+```bash
+shopware-cli project sql --file script.sql
+shopware-cli project sql --file script.sql --format json
+```
+
+`--file` cannot be combined with a query argument.
+
 ## Admin API
 
 The `project admin-api` command is a pre-authenticated curl wrapper for the Shopware Admin API. Instead of manually handling JWT token generation and headers, this command handles authentication automatically:

From 5cc079ec5eebd51286439cf9c6b75b31d9829503 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 24 Aug 2026 09:28:10 +0000
Subject: [PATCH 2/2] docs: move sql --file docs to dedicated sql.md, revert
 helper-commands.md

Co-authored-by: shyim <6224096+shyim@users.noreply.github.com>
---
 .../cli/project-commands/helper-commands.md   | 23 --------
 products/tools/cli/project-commands/sql.md    | 54 +++++++++++++++++++
 2 files changed, 54 insertions(+), 23 deletions(-)
 create mode 100644 products/tools/cli/project-commands/sql.md

diff --git a/products/tools/cli/project-commands/helper-commands.md b/products/tools/cli/project-commands/helper-commands.md
index e42c8cc43..790b6dd66 100644
--- a/products/tools/cli/project-commands/helper-commands.md
+++ b/products/tools/cli/project-commands/helper-commands.md
@@ -129,29 +129,6 @@ shopware-cli project console <command>
 
 A shorter `swx` alias is also available. See [Running Shopware commands](../../../../guides/development/dev-environment.md#running-shopware-commands).
 
-## SQL shell
-
-The `project sql` command connects to the configured database and executes SQL, without needing to look up connection details manually:
-
-```bash
-shopware-cli project sql "SELECT * FROM sales_channel"
-```
-
-Without a query argument, it starts an interactive SQL shell. It also accepts a script from stdin:
-
-```bash
-shopware-cli project sql < script.sql
-```
-
-Or from a file with `--file`:
-
-```bash
-shopware-cli project sql --file script.sql
-shopware-cli project sql --file script.sql --format json
-```
-
-`--file` cannot be combined with a query argument.
-
 ## Admin API
 
 The `project admin-api` command is a pre-authenticated curl wrapper for the Shopware Admin API. Instead of manually handling JWT token generation and headers, this command handles authentication automatically:
diff --git a/products/tools/cli/project-commands/sql.md b/products/tools/cli/project-commands/sql.md
new file mode 100644
index 000000000..73906326a
--- /dev/null
+++ b/products/tools/cli/project-commands/sql.md
@@ -0,0 +1,54 @@
+---
+nav:
+  title: SQL Shell
+  position: 8
+
+---
+
+# SQL Shell
+
+Shopware CLI can connect to the project database using the connection details of the current environment (local, Docker, ...), so you don't need to know the host or credentials.
+
+## Interactive shell
+
+Run without arguments to open an interactive SQL shell:
+
+```bash
+shopware-cli project sql
+```
+
+Type `exit` or press <kbd>Ctrl</kbd>+<kbd>D</kbd> to quit.
+
+## Running a single query
+
+Pass the query as an argument:
+
+```bash
+shopware-cli project sql "SELECT id, tax_rate FROM tax"
+```
+
+## Providing a script via stdin
+
+A SQL script can also be provided via stdin:
+
+    shopware-cli project sql < script.sql
+
+## Running a script from a file
+
+Use the `--file` flag to execute a SQL script from disk:
+
+```bash
+shopware-cli project sql --file script.sql
+```
+
+`--file` cannot be combined with a query argument. A missing file is reported before the database connection opens.
+
+## Output format
+
+Use the `--format` flag to control the output format: `table`, `tsv`, or `json`.
+
+```bash
+shopware-cli project sql --format json "SELECT * FROM sales_channel" | jq
+```
+
+By default, the output is rendered as a `table` when stdout is a terminal, and as `tsv` otherwise.