From d541ecd112cec1b27c6e52e945a720e2737abeaa Mon Sep 17 00:00:00 2001
From: Joe Clark <joe@openfn.org>
Date: Mon, 12 Oct 2026 12:08:40 +0100
Subject: [PATCH 1/2] explain workflow aliases

---
 docs/build-for-developers/cli-sync.md | 38 +++++++++++++++++++++++++--
 1 file changed, 36 insertions(+), 2 deletions(-)

diff --git a/docs/build-for-developers/cli-sync.md b/docs/build-for-developers/cli-sync.md
index 432be5126c8..4b0baf97ca6 100644
--- a/docs/build-for-developers/cli-sync.md
+++ b/docs/build-for-developers/cli-sync.md
@@ -241,6 +241,8 @@ The `project pull` command does three things:
 
 ## Aliases
 
+### Project
+
 Rather than identify a local project with a long-winded UUID or id string, you
 can use an _alias_.
 
@@ -258,6 +260,35 @@ This will save the project to `dev@app.openfn.org.yaml`.
 To change the alias, you can simply rename the file. Whatever goes before the
 `@` will be treated as the alias.
 
+### Workflow
+
+You can also alias a Workflow. Simply rename the folder which holds the
+workflow.yaml, and anywhere you would normally reference a workflow, you can
+pass the alias instead of the id.
+
+So for the following project:
+
+```
+├── openfn.yaml
+└── workflows
+    ├── my-workflow
+    │   ├── my-workflow.yaml
+    │   ├── my-step.js
+```
+
+You can alias `my-workflow` to `wf`:
+
+```
+├── openfn.yaml
+└── workflows
+    ├── wf
+    │   ├── my-workflow.yaml
+    │   ├── my-step.js
+```
+
+And run the workflow with `openfn wf`, or deploy only that workflow with
+`openfn project deploy --workflows wf`
+
 ## Checking Out
 
 You can checkout a project any time with:
@@ -278,7 +309,7 @@ files) they will be untouched.
 
 ## Running workflows in projects
 
-You can execute any workflow in the checked out project by name:
+You can execute any workflow in the checked out project by id or alias:
 
 ```bash
 openfn my-workflow
@@ -287,13 +318,16 @@ openfn my-workflow
 The CLI will find the workflow in your `workflows` folder and run it. You can
 pass state via `-s` and set log levels as per usual.
 
-When running a workflow by name like this, you get two benefits:
+When running a workflow by id like this, you get two benefits:
 
 - **Credentials** are loaded automatically from the credential map in
   `openfn.yaml`, so you don't need to pass `--credential-map`
 - **Collections** use the server configured in `openfn.yaml`, so you don't need
   to pass `--collections-endpoint` or anything.
 
+By default, the workflow's output will be written to
+`workflows/<id-or-alias>/tmp/output.json`, where it can easily be gitignored.
+
 ## Deploying a Project
 
 To push your local changes back to the app, run:

From 83aee7bc8ad9a0fad65270a3ba179b950a0755ce Mon Sep 17 00:00:00 2001
From: Joe Clark <joe@openfn.org>
Date: Mon, 12 Oct 2026 12:18:11 +0100
Subject: [PATCH 2/2] a bit extra

---
 docs/build-for-developers/cli-sync.md | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/docs/build-for-developers/cli-sync.md b/docs/build-for-developers/cli-sync.md
index 4b0baf97ca6..20c8b629570 100644
--- a/docs/build-for-developers/cli-sync.md
+++ b/docs/build-for-developers/cli-sync.md
@@ -241,6 +241,9 @@ The `project pull` command does three things:
 
 ## Aliases
 
+Aliases are a convenient way to reference things in the local CLI. Aliases are
+never pushed to the app on deploy: they're a purely local artefact.
+
 ### Project
 
 Rather than identify a local project with a long-winded UUID or id string, you