From b3a8080d85f627f2a0fa2c2f8ca05f9895507bb6 Mon Sep 17 00:00:00 2001
From: Akash Kumar <91385321+AkashKumar7902@users.noreply.github.com>
Date: Fri, 29 May 2026 13:18:17 +0530
Subject: [PATCH] docs: add cli exec examples (#6629)

Co-authored-by: qwerty287 <80460567+qwerty287@users.noreply.github.com>
---
 docs/docs/10-intro/index.md              |  2 +
 docs/docs/20-usage/10-intro.md           | 14 +++-
 docs/docs/20-usage/73-local-execution.md | 87 ++++++++++++++++++++++++
 3 files changed, 101 insertions(+), 2 deletions(-)
 create mode 100644 docs/docs/20-usage/73-local-execution.md

diff --git a/docs/docs/10-intro/index.md b/docs/docs/10-intro/index.md
index 025bd1f85..a8e00c742 100644
--- a/docs/docs/10-intro/index.md
+++ b/docs/docs/10-intro/index.md
@@ -24,3 +24,5 @@ Then you might want to jump directly into it and [start creating your first pipe
 ## Want to start from scratch and deploy your own Woodpecker instance?
 
 Woodpecker is lightweight and even runs on a Raspberry Pi. You can follow the [deployment guide](../30-administration/00-general.md) to set up your own Woodpecker instance.
+
+If you want to try a pipeline before installing a server, you can also run workflow files locally with [`woodpecker-cli exec`](../20-usage/73-local-execution.md).
diff --git a/docs/docs/20-usage/10-intro.md b/docs/docs/20-usage/10-intro.md
index 095528b4e..affe61b47 100644
--- a/docs/docs/20-usage/10-intro.md
+++ b/docs/docs/20-usage/10-intro.md
@@ -66,7 +66,17 @@ You can use any image from registries like the [Docker Hub](https://hub.docker.c
        - aws help
 ```
 
-## 3. Push the file and trigger first pipeline
+## 3. Run the workflow locally
+
+If you have `woodpecker-cli` and a supported backend installed, you can run the workflow before pushing it:
+
+```shell
+woodpecker-cli exec .woodpecker/my-first-workflow.yaml
+```
+
+This is useful for checking workflow syntax, command output, and metadata conditions while you are still editing the file. For more examples, including secrets and downloaded metadata, see [local pipeline execution](./73-local-execution.md).
+
+## 4. Push the file and trigger first pipeline
 
 If you push this file to your repository now, Woodpecker will already execute your first pipeline.
 
@@ -79,7 +89,7 @@ As you probably noticed, there is another step in called `clone` which is execut
 This for example allows the first step to build your application using your source code and as the second step will receive
 the same workspace it can use the previously built binary and test it.
 
-## 4. Use a plugin for reusable tasks
+## 5. Use a plugin for reusable tasks
 
 Sometimes you have some tasks that you need to do in every project. For example, deploying to Kubernetes or sending a Slack message. Therefore you can use one of the [official and community plugins](/plugins) or simply [create your own](./51-plugins/20-creating-plugins.md).
 
diff --git a/docs/docs/20-usage/73-local-execution.md b/docs/docs/20-usage/73-local-execution.md
new file mode 100644
index 000000000..004735ef5
--- /dev/null
+++ b/docs/docs/20-usage/73-local-execution.md
@@ -0,0 +1,87 @@
+# Local pipeline execution
+
+`woodpecker-cli exec` runs workflow files from your local checkout. Use it to test pipeline changes before pushing them, to debug a workflow without waiting for a server run, or to replay a server pipeline with downloaded metadata.
+
+## Requirements
+
+- Install `woodpecker-cli` from the [distribution packages](../30-administration/05-installation/30-packages.md) or a release archive.
+- Run the command from the repository checkout, or pass `--repo-path` to point at it.
+- Make sure the backend you want to use is available locally. The Docker backend needs access to a Docker daemon. The local backend runs commands directly on your host and does not reproduce the container image environment.
+
+## Run a workflow file
+
+Create or edit a workflow file, then run it directly:
+
+```shell
+woodpecker-cli exec .woodpecker/my-first-workflow.yaml
+```
+
+You can also run every `.yaml` and `.yml` file in a workflow directory:
+
+```shell
+woodpecker-cli exec .woodpecker/
+```
+
+By default, Woodpecker auto-detects a backend. Select one explicitly when you want the local run to match a specific agent backend:
+
+```shell
+woodpecker-cli exec --backend-engine docker .woodpecker/my-first-workflow.yaml
+woodpecker-cli exec --backend-engine local .woodpecker/my-first-workflow.yaml
+```
+
+## Pass metadata
+
+Metadata values are set automatically, but you can override them to test conditions such as branches, pull requests, tags, and events:
+
+```shell
+woodpecker-cli exec \
+  --pipeline-event push \
+  --commit-branch main \
+  --commit-sha "$(git rev-parse HEAD)" \
+  --repo octocat/hello-world \
+  .woodpecker/my-first-workflow.yaml
+```
+
+If you downloaded pipeline metadata from the Woodpecker UI, pass it with `--metadata-file` and adjust individual values with other flags when needed:
+
+```shell
+woodpecker-cli exec \
+  --metadata-file pipeline-metadata.json \
+  --pipeline-event pull_request \
+  .woodpecker/my-first-workflow.yaml
+```
+
+## Pass environment variables and secrets
+
+Use `--env` for regular environment variables:
+
+```shell
+woodpecker-cli exec \
+  --env GOFLAGS=-mod=readonly \
+  .woodpecker/test.yaml
+```
+
+Secrets are not downloaded from the server. Pass the values needed for local debugging explicitly:
+
+```shell
+woodpecker-cli exec \
+  --secrets deploy_token="$DEPLOY_TOKEN" \
+  .woodpecker/deploy.yaml
+```
+
+For multiple secrets, keep them in a local YAML file that is ignored by Git:
+
+```yaml title=".woodpecker/local-secrets.yaml"
+deploy_token: ghp_example
+registry_password: example-password
+```
+
+```shell
+woodpecker-cli exec \
+  --secrets-file .woodpecker/local-secrets.yaml \
+  .woodpecker/deploy.yaml
+```
+
+## More options
+
+See the generated [CLI reference](../40-cli.md#exec) for the full list of `exec` flags.