Workflow cheat sheet

1. The two formats
2. Tasks view
3. tasks.yml
4. workflows/*.yml
5. Task keys
6. Shells
7. Values
8. params:
9. Run variables
10. Errors and silent failures

---

The two formats

	tasks.yml	workflows/*.yml
Path	.local-workflows/tasks.yml	.local-workflows/workflows/*.yml
Tasks are	a map, keyed by id	a list, in order
Ordering	needs: between tasks	stages:, then needs: between jobs
needs: on a task	allowed	refused
Runs	any task, alone (plus its needs: chain); the whole file only when it is the workspace’s only tasks.yml	the whole file
version:	optional, read as 1	required, must be 1
name:	ignored	the row’s label

Both formats exist in all three scopes — folder, workspace and profile. A narrower copy hides a wider one of the same name:. See the workspace cheat sheet.

---

Tasks view

Row	A click	Inline icons
Tasks heading	expands/collapses, nothing else	sort toggle
a task	opens it, never runs it	▶ / stop, edit file

No whole-file run: a tasks.yml is a library, not a pipeline. For one click that covers the file, write a task whose needs: names what it should cover.

Sort toggle: Sort Tasks A-Z and Sort Tasks in File Order, also in the Command Palette. Sorts by the shown label (name:, else the id), case-insensitive, across every scope; equal labels keep file order. Remembered per workspace, written nowhere in the repo.

---

tasks.yml

version: 1
vars: / env: / dotenv:
plugins:
tasks:
  setup: echo hi                 # bare string = run:
  build:
    name: / desc:
    needs: [setup]
    shell: pwsh
    run: |
      echo one
      echo two

---

workflows/*.yml

version: 1                       # required
name: / desc: / label:
params:
env: / vars: / dotenv:
plugins:
stages:
  - name: / desc: / if: / artifact:
    jobs:
      <job-id>:
        name: / desc:
        needs:                   # job ids in this stage
        env: / vars: / dotenv: / cwd:
        tasks: [ ... ]

Stage keys, closed: name desc if artifact jobs Job keys: name desc needs env vars dotenv cwd tasks

---

Task keys

Closed, and the same in both formats:

name  desc  needs  run  uses  session  args  trigger  output
if  continueOnError  timeout  retries  shell  env  vars  dotenv  cwd

Key	Value
trigger	auto (default) | manual
timeout	10m, 30s
retries	integer
continueOnError	job carries on; task still reports failed
output	run-variable name
uses	id@major, or a bare plugins: alias

Bare string = run:. run: desugars to uses: shell@1, script:.

---

Shells

Declared	Runs in
nothing	cmd on Windows, bash elsewhere
shell: pwsh	PowerShell 7+
shell: cmd	Windows only; validation error elsewhere

pwsh is never the default.

---

Values

	Exported	Typed
vars:	no	yes
env:	yes	no
dotenv:	yes	no

Levels: file, job, task. cwd:: job and task only. vars: cannot read env:. A missing .env is skipped.

Resolution order:

1. workspace, root, cwd
2. vars:
3. dotenv:, then env:
4. cwd:, run:, args: — plus run.*

Anchor
workspace	where the editor opened
root	the folder holding .local-workflows
cwd	where this command runs

A value that is only one expression keeps its type.

---

params:

params:
  tag:                           # bare = required
  environment:
    desc: Where this goes
    options: [staging, production]
    default: staging

Keys, closed: desc required default options

• Required unless default: is set or required: false.
• default: + required: true — error.
• default outside options — error.
• Name pattern: [A-Za-z_][A-Za-z0-9_]*.

---

Run variables

- name: Draft
  uses: ai@1
  args: { prompt: Draft release notes. }
  output: NOTES

- name: Publish
  run: ./publish.ps1 -Title "${{ run.NOTES.title }}"

One declared output means the variable is that value. No job-level outputs: block exists.

---

Errors and silent failures

Top-level key not tasks:	parses to zero tasks, no error
Unknown task/stage/job/param key	hard error
needs: on a task in a job	hard error
ai declared twice	hard error
Unquoted scalar containing ": "	parses as a nested map
Task with no run:/uses:	legal; logs Task has nothing to run
Task with no run:/uses:/needs:	warning
Failed task	dependents skipped transitively