@runfile/cli 0.12.0 → 0.13.0

package/bin/darwin-arm64/README.md

@@ -111,16 +111,16 @@ Sorted from where Runfile is most differentiated to where it lags behind.
 | Argument substitution with chained fallbacks                        |    ✅    |  ❌   |  ✅   |    ❌     |
 | JSON Schema autocomplete in editors                                 |    ✅    |  ❌   |  ❌   |    ✅     |
 | Watch mode, built-in                                                |    ✅    |  ❌   |  ❌   |    ✅     |
+| Output grouping / prefixing in parallel mode                        |    ✅    |  ❌   |  ❌   |    ✅     |
 | Native Windows (no WSL / msys2 needed)                              |    ✅    |  ❌   |  ✅   |    ✅     |
-| Parallel execution                                                  |    ✅    |  ✅   |  ❌   |    ✅     |
 | Shell completions                                                   |    ✅    |  ❌   |  ✅   |    ✅     |
 | Private / internal targets (`_name`)                                |    ✅    |  ❌   |  ✅   |    ✅     |
+| Built-in string functions (upper, replace, trim, regex, base64, …)  |    ✅    |  ❌   |  ✅   |    ✅     |
+| Parallel execution                                                  |    ✅    |  ✅   |  ❌   |    ✅     |
 | Single static binary                                                |    ✅    |  ✅   |  ✅   |    ✅     |
 | Pattern rules (`%.o: %.c`)                                          |    ❌    |  ✅   |  ❌   |    ❌     |
-| Output grouping / prefixing in parallel mode                        |    ❌    |  ❌   |  ❌   |    ✅     |
 | Preconditions / status checks                                       |    ❌    |  ❌   |  ❌   |    ✅     |
 | Incremental builds (sources / timestamps / checksums)               |    ❌    |  ✅   |  ❌   |    ✅     |
-| Built-in string functions (upper, replace, trim, …)                 |    ❌    |  ❌   |  ✅   |    ✅     |
 
 ---
 
@@ -167,9 +167,9 @@ $ run :env inject -f .env.production -- ./deploy.sh       # encrypted values aut
 
 #### Powerful argument substitution
 
-Positional, named, flags, env vars, and runtime context (`{{ RUN.os }}` / `{{ RUN.shell }}` / `{{ RUN.cwd }}` /
-`{{ RUN.file }}` / `{{ RUN.parent }}`) — with chained fallbacks and required values. The `{{ ... }}` syntax
-avoids collisions with shell `$(...)` command substitution.
+Positional, named, flags, env vars, and runtime context (`{{ RUN.os }}` / `{{ RUN.arch }}` / `{{ RUN.shell }}` /
+`{{ RUN.cwd }}` / `{{ RUN.file }}` / `{{ RUN.parent }}`) — with chained fallbacks and required values. The
+`{{ ... }}` syntax avoids collisions with shell `$(...)` command substitution.
 
 ```jsonc
 "PORT": "{{ ARGS.port ? ENV.PORT ? '3000' }}",
@@ -242,9 +242,15 @@ and work as full substitution bodies *or* as chain segments:
   //   transform : escape, repeat, replace_all, remove_all
   //   regex     : regex_replace, regex_remove, regex_matches
   //   build     : concat, join
+  //   split     : nth, first, last, count_parts
   //   encoding  : base64_encode, base64_decode
+  //   hashing   : sha256, md5
+  //   files     : read_file, file_exists
+  //   json      : json_get, json_set
+  //   error     : try
   //   shell     : shell_quote
   //   variables : define
+  //   cwd       : set_cwd
   "echo deploying-{{ to_upper(ARGS.env) }}",
   "curl -H \"X-Auth: {{ base64_encode(ENV.TOKEN) }}\" ...",
   "echo {{ concat('hello-', ARGS.name, '-2026') }}",
@@ -253,6 +259,13 @@ and work as full substitution bodies *or* as chain segments:
   "go test {{ replace_all(ARGS.flags, ' ', ' -tag=') }}",
   // Strip every match of a regex (here: collapse whitespace runs to a single space):
   "echo {{ regex_replace(ARGS.text, '\\s+', ' ') }}",
+  // Split-by-separator scalar accessors — string in, string out, no list type:
+  // basename idiom (last segment after `/`); empty string when input ends in `/`.
+  "echo basename={{ last(ARGS.path, '/') }}",
+  // Pull out the N-th comma-separated field; out-of-bounds returns "".
+  "echo target={{ nth(ARGS.csv, ',', '1') }}",
+  // Pair `count_parts` with `nth` to bound-check before indexing:
+  // "if": "{{ count_parts(ARGS.csv, ',') == '3' }}"
   // Boolean-returning helpers are valid DSL `Truthy` values — use them in `if`:
   // "if": "{{ starts_with(ARGS.path, '/usr') }}"
   // "if": "{{ regex_matches(ARGS.tag, '^v[0-9]+\\.[0-9]+$') }}"
@@ -261,6 +274,28 @@ and work as full substitution bodies *or* as chain segments:
   // `shell_quote` picks the right quoting for the active shell:
   "some-tool --json {{ shell_quote(base64_decode(ENV.SECRET_BASE64)) }}",
 
+  // Cache keys / content fingerprints. `sha256` for security-sensitive use,
+  // `md5` for cheap fingerprinting (NOT cryptographically secure).
+  "echo cache-key={{ sha256(read_file('package-lock.json')) }}",
+
+  // Branch on file presence without forking a shell. `file_exists` returns
+  // the literal "true" / "false", so it doubles as a DSL truthy value.
+  // "if": "{{ file_exists('.env.local') }}"
+
+  // Read a file inline — relative paths anchor to the Runfile directory.
+  // Use `try(...)` to recover from missing files.
+  "echo version={{ try(read_file('VERSION')) ? '0.0.0-dev' }}",
+
+  // Pull values out of arbitrary JSON without `jq` (works on every shell):
+  "echo db_host={{ json_get(read_file('config.json'), 'database.host') }}",
+
+  // Modify a JSON document in place (returns the new compact JSON):
+  "echo {{ json_set('{\"port\":3000}', 'env', 'production') }}",
+
+  // `try(expr)` swallows inner errors. Standalone returns "" on failure;
+  // chained, the next segment runs as a fallback.
+  "echo {{ try(base64_decode(ARGS.maybe_b64)) ? ARGS.maybe_b64 }}",
+
   // Nested:
   "echo {{ to_upper(to_lower(ARGS.x)) }}",
 
@@ -272,6 +307,13 @@ and work as full substitution bodies *or* as chain segments:
   "{{ VARS.sdk }}/bin/build",
   "echo using sdk at {{ VARS.sdk }}",
 
+  // `set_cwd(path)` switches the cwd subsequent commands spawn in — like
+  // shell `cd`, but works on every shell / OS without forking. Relative
+  // paths chain (matching `cd a; cd b` → `a/b`); absolute paths replace.
+  "{{ set_cwd(ARGS.subproject ? 'packages/api') }}",
+  "npm install",
+  "npm run build",
+
   // Single-quoted strings interpolate nested {{ }} substitutions:
   "{{ define(cmd, 'docker compose -f {{ VARS.compose }} pull') }}",
   "{{ VARS.cmd }}"
@@ -283,6 +325,22 @@ to only whitespace (i.e. one consisting solely of a `{{ define(...) }}` call) is
 being dispatched to the shell. `define`s in a parent target are visible to `@target` children. The `name` MUST
 be a bareword identifier matching `[A-Za-z_][A-Za-z0-9_-]*` — quotes are NOT allowed on the name.
 
+`set_cwd(path)` is the cwd analog of `define`: returns an empty string and changes the cwd that subsequent shell
+commands in the *current target* spawn in. Behaves like shell `cd`, but works uniformly across every shell / OS
+(no forked process, no `cd` binary needed). Resolution rules:
+
+- **Absolute path** → fully replaces the current override (matches `cd /abs`).
+- **Relative path** → joins onto the existing override, or onto the target's `workingDirectory` if no override
+  has been set yet. So `set_cwd('a'); set_cwd('b')` lands subsequent commands in `<workingDirectory>/a/b`,
+  matching how `cd a; cd b` chains in a shell.
+
+`set_cwd` is **per-target**: each `@target` invocation starts with a clean override (the dispatched target sees
+its own `workingDirectory`, not the caller's `set_cwd` state). Inside `parallel: true` targets each leaf
+captures the override at the moment of its substitution, so siblings don't race on the spawn cwd. Like
+`define`, the side effect is skipped on the redacted-logging pass so log lines don't double-apply it. With
+`sameShell: true`, only the *final* `set_cwd` value applies (everything joins into one shell invocation) — use
+shell `cd` directly between leaves there if you need intermediate cwd changes.
+
 Function args are separated by `, ` (comma + exactly one space).
 
 **Quote semantics inside `{{ ... }}`:**
@@ -311,13 +369,18 @@ evaluated by Runfile itself, so the logic works the same on every shell and plat
     "cases": {
       "1": "flutter emulators --launch Tier_1_Android_9",
       "2": "flutter emulators --launch Tier_2_Android_11",
-      "3": "flutter emulators --launch Tier_3_Android_14"
+      "3": "flutter emulators --launch Tier_3_Android_14",
+      // Case keys wrapped in `/.../` are treated as regex patterns.
+      // Literal cases always win over a regex that would also match.
+      "/^v\\d+$/": "echo version-tag",
+      "/^pr-\\d+$/": "echo preview-build"
     } },                                // unknown values error out, listing the valid cases
 
   { "for": "service",
     "in": ["api", "web", "worker"],
     "parallel": true,
-    "do": ["docker build -t {{ VARS.service }} services/{{ VARS.service }}"] },
+    // VARS.<name>_index exposes the 0-based iteration counter.
+    "do": ["echo [{{ VARS.service_index }}] docker build -t {{ VARS.service }} services/{{ VARS.service }}"] },
 
   { "for": "file",
     "shell": "git diff --name-only HEAD~1",
@@ -379,6 +442,27 @@ Wrap any commands in a `when:` block to run them only after a failure, or always
 ]
 ```
 
+#### Single-shell mode with `sameShell`
+
+By default each step runs in its own shell process, so `cd`, exported variables, and other shell state don't carry
+over between steps. Set `"sameShell": true` to join every step into a single shell invocation — state changes
+persist for free.
+
+```jsonc
+{
+  "deploy": {
+    "sameShell": true,
+    "commands": ["cd ci-scripts/", "./ci-deploy.sh"]
+  }
+}
+```
+
+Steps are joined with `&&` so the run stops at the first failure (or `;` / `&` when `ignoreErrors: true`). `if`,
+`for`, and `match` blocks are evaluated by Runfile and their chosen branches flow into the same joined invocation.
+`@target` calls inside the body are rejected — they have their own shell context and can't share state with the
+parent. `sameShell` also composes with `detach: true` (joined command spawns as one detached process) and is
+available on `globals` for project-wide defaults.
+
 #### Watch mode, built in
 
 Add a `watch` array to any target. No flags, no extra tooling.
@@ -397,6 +481,11 @@ $ run :generate zed-tasks
 $ run :generate jetbrains-run-configurations
 ```
 
+Skip a target from the generated configs by setting `metadata.excludeFromGenerateCommand: true`. The
+`metadata` block on `globals` and on each target is **fully open** — any property of any JSON type
+(strings, numbers, booleans, arrays, deeply-nested objects) is accepted and round-trips untouched, so
+editor extensions and CI scripts can stash arbitrary tooling-specific fields here.
+
 #### Migrate in seconds
 
 ```bash

package/bin/darwin-x64/README.md

@@ -111,16 +111,16 @@ Sorted from where Runfile is most differentiated to where it lags behind.
 | Argument substitution with chained fallbacks                        |    ✅    |  ❌   |  ✅   |    ❌     |
 | JSON Schema autocomplete in editors                                 |    ✅    |  ❌   |  ❌   |    ✅     |
 | Watch mode, built-in                                                |    ✅    |  ❌   |  ❌   |    ✅     |
+| Output grouping / prefixing in parallel mode                        |    ✅    |  ❌   |  ❌   |    ✅     |
 | Native Windows (no WSL / msys2 needed)                              |    ✅    |  ❌   |  ✅   |    ✅     |
-| Parallel execution                                                  |    ✅    |  ✅   |  ❌   |    ✅     |
 | Shell completions                                                   |    ✅    |  ❌   |  ✅   |    ✅     |
 | Private / internal targets (`_name`)                                |    ✅    |  ❌   |  ✅   |    ✅     |
+| Built-in string functions (upper, replace, trim, regex, base64, …)  |    ✅    |  ❌   |  ✅   |    ✅     |
+| Parallel execution                                                  |    ✅    |  ✅   |  ❌   |    ✅     |
 | Single static binary                                                |    ✅    |  ✅   |  ✅   |    ✅     |
 | Pattern rules (`%.o: %.c`)                                          |    ❌    |  ✅   |  ❌   |    ❌     |
-| Output grouping / prefixing in parallel mode                        |    ❌    |  ❌   |  ❌   |    ✅     |
 | Preconditions / status checks                                       |    ❌    |  ❌   |  ❌   |    ✅     |
 | Incremental builds (sources / timestamps / checksums)               |    ❌    |  ✅   |  ❌   |    ✅     |
-| Built-in string functions (upper, replace, trim, …)                 |    ❌    |  ❌   |  ✅   |    ✅     |
 
 ---
 
@@ -167,9 +167,9 @@ $ run :env inject -f .env.production -- ./deploy.sh       # encrypted values aut
 
 #### Powerful argument substitution
 
-Positional, named, flags, env vars, and runtime context (`{{ RUN.os }}` / `{{ RUN.shell }}` / `{{ RUN.cwd }}` /
-`{{ RUN.file }}` / `{{ RUN.parent }}`) — with chained fallbacks and required values. The `{{ ... }}` syntax
-avoids collisions with shell `$(...)` command substitution.
+Positional, named, flags, env vars, and runtime context (`{{ RUN.os }}` / `{{ RUN.arch }}` / `{{ RUN.shell }}` /
+`{{ RUN.cwd }}` / `{{ RUN.file }}` / `{{ RUN.parent }}`) — with chained fallbacks and required values. The
+`{{ ... }}` syntax avoids collisions with shell `$(...)` command substitution.
 
 ```jsonc
 "PORT": "{{ ARGS.port ? ENV.PORT ? '3000' }}",
@@ -242,9 +242,15 @@ and work as full substitution bodies *or* as chain segments:
   //   transform : escape, repeat, replace_all, remove_all
   //   regex     : regex_replace, regex_remove, regex_matches
   //   build     : concat, join
+  //   split     : nth, first, last, count_parts
   //   encoding  : base64_encode, base64_decode
+  //   hashing   : sha256, md5
+  //   files     : read_file, file_exists
+  //   json      : json_get, json_set
+  //   error     : try
   //   shell     : shell_quote
   //   variables : define
+  //   cwd       : set_cwd
   "echo deploying-{{ to_upper(ARGS.env) }}",
   "curl -H \"X-Auth: {{ base64_encode(ENV.TOKEN) }}\" ...",
   "echo {{ concat('hello-', ARGS.name, '-2026') }}",
@@ -253,6 +259,13 @@ and work as full substitution bodies *or* as chain segments:
   "go test {{ replace_all(ARGS.flags, ' ', ' -tag=') }}",
   // Strip every match of a regex (here: collapse whitespace runs to a single space):
   "echo {{ regex_replace(ARGS.text, '\\s+', ' ') }}",
+  // Split-by-separator scalar accessors — string in, string out, no list type:
+  // basename idiom (last segment after `/`); empty string when input ends in `/`.
+  "echo basename={{ last(ARGS.path, '/') }}",
+  // Pull out the N-th comma-separated field; out-of-bounds returns "".
+  "echo target={{ nth(ARGS.csv, ',', '1') }}",
+  // Pair `count_parts` with `nth` to bound-check before indexing:
+  // "if": "{{ count_parts(ARGS.csv, ',') == '3' }}"
   // Boolean-returning helpers are valid DSL `Truthy` values — use them in `if`:
   // "if": "{{ starts_with(ARGS.path, '/usr') }}"
   // "if": "{{ regex_matches(ARGS.tag, '^v[0-9]+\\.[0-9]+$') }}"
@@ -261,6 +274,28 @@ and work as full substitution bodies *or* as chain segments:
   // `shell_quote` picks the right quoting for the active shell:
   "some-tool --json {{ shell_quote(base64_decode(ENV.SECRET_BASE64)) }}",
 
+  // Cache keys / content fingerprints. `sha256` for security-sensitive use,
+  // `md5` for cheap fingerprinting (NOT cryptographically secure).
+  "echo cache-key={{ sha256(read_file('package-lock.json')) }}",
+
+  // Branch on file presence without forking a shell. `file_exists` returns
+  // the literal "true" / "false", so it doubles as a DSL truthy value.
+  // "if": "{{ file_exists('.env.local') }}"
+
+  // Read a file inline — relative paths anchor to the Runfile directory.
+  // Use `try(...)` to recover from missing files.
+  "echo version={{ try(read_file('VERSION')) ? '0.0.0-dev' }}",
+
+  // Pull values out of arbitrary JSON without `jq` (works on every shell):
+  "echo db_host={{ json_get(read_file('config.json'), 'database.host') }}",
+
+  // Modify a JSON document in place (returns the new compact JSON):
+  "echo {{ json_set('{\"port\":3000}', 'env', 'production') }}",
+
+  // `try(expr)` swallows inner errors. Standalone returns "" on failure;
+  // chained, the next segment runs as a fallback.
+  "echo {{ try(base64_decode(ARGS.maybe_b64)) ? ARGS.maybe_b64 }}",
+
   // Nested:
   "echo {{ to_upper(to_lower(ARGS.x)) }}",
 
@@ -272,6 +307,13 @@ and work as full substitution bodies *or* as chain segments:
   "{{ VARS.sdk }}/bin/build",
   "echo using sdk at {{ VARS.sdk }}",
 
+  // `set_cwd(path)` switches the cwd subsequent commands spawn in — like
+  // shell `cd`, but works on every shell / OS without forking. Relative
+  // paths chain (matching `cd a; cd b` → `a/b`); absolute paths replace.
+  "{{ set_cwd(ARGS.subproject ? 'packages/api') }}",
+  "npm install",
+  "npm run build",
+
   // Single-quoted strings interpolate nested {{ }} substitutions:
   "{{ define(cmd, 'docker compose -f {{ VARS.compose }} pull') }}",
   "{{ VARS.cmd }}"
@@ -283,6 +325,22 @@ to only whitespace (i.e. one consisting solely of a `{{ define(...) }}` call) is
 being dispatched to the shell. `define`s in a parent target are visible to `@target` children. The `name` MUST
 be a bareword identifier matching `[A-Za-z_][A-Za-z0-9_-]*` — quotes are NOT allowed on the name.
 
+`set_cwd(path)` is the cwd analog of `define`: returns an empty string and changes the cwd that subsequent shell
+commands in the *current target* spawn in. Behaves like shell `cd`, but works uniformly across every shell / OS
+(no forked process, no `cd` binary needed). Resolution rules:
+
+- **Absolute path** → fully replaces the current override (matches `cd /abs`).
+- **Relative path** → joins onto the existing override, or onto the target's `workingDirectory` if no override
+  has been set yet. So `set_cwd('a'); set_cwd('b')` lands subsequent commands in `<workingDirectory>/a/b`,
+  matching how `cd a; cd b` chains in a shell.
+
+`set_cwd` is **per-target**: each `@target` invocation starts with a clean override (the dispatched target sees
+its own `workingDirectory`, not the caller's `set_cwd` state). Inside `parallel: true` targets each leaf
+captures the override at the moment of its substitution, so siblings don't race on the spawn cwd. Like
+`define`, the side effect is skipped on the redacted-logging pass so log lines don't double-apply it. With
+`sameShell: true`, only the *final* `set_cwd` value applies (everything joins into one shell invocation) — use
+shell `cd` directly between leaves there if you need intermediate cwd changes.
+
 Function args are separated by `, ` (comma + exactly one space).
 
 **Quote semantics inside `{{ ... }}`:**
@@ -311,13 +369,18 @@ evaluated by Runfile itself, so the logic works the same on every shell and plat
     "cases": {
       "1": "flutter emulators --launch Tier_1_Android_9",
       "2": "flutter emulators --launch Tier_2_Android_11",
-      "3": "flutter emulators --launch Tier_3_Android_14"
+      "3": "flutter emulators --launch Tier_3_Android_14",
+      // Case keys wrapped in `/.../` are treated as regex patterns.
+      // Literal cases always win over a regex that would also match.
+      "/^v\\d+$/": "echo version-tag",
+      "/^pr-\\d+$/": "echo preview-build"
     } },                                // unknown values error out, listing the valid cases
 
   { "for": "service",
     "in": ["api", "web", "worker"],
     "parallel": true,
-    "do": ["docker build -t {{ VARS.service }} services/{{ VARS.service }}"] },
+    // VARS.<name>_index exposes the 0-based iteration counter.
+    "do": ["echo [{{ VARS.service_index }}] docker build -t {{ VARS.service }} services/{{ VARS.service }}"] },
 
   { "for": "file",
     "shell": "git diff --name-only HEAD~1",
@@ -379,6 +442,27 @@ Wrap any commands in a `when:` block to run them only after a failure, or always
 ]
 ```
 
+#### Single-shell mode with `sameShell`
+
+By default each step runs in its own shell process, so `cd`, exported variables, and other shell state don't carry
+over between steps. Set `"sameShell": true` to join every step into a single shell invocation — state changes
+persist for free.
+
+```jsonc
+{
+  "deploy": {
+    "sameShell": true,
+    "commands": ["cd ci-scripts/", "./ci-deploy.sh"]
+  }
+}
+```
+
+Steps are joined with `&&` so the run stops at the first failure (or `;` / `&` when `ignoreErrors: true`). `if`,
+`for`, and `match` blocks are evaluated by Runfile and their chosen branches flow into the same joined invocation.
+`@target` calls inside the body are rejected — they have their own shell context and can't share state with the
+parent. `sameShell` also composes with `detach: true` (joined command spawns as one detached process) and is
+available on `globals` for project-wide defaults.
+
 #### Watch mode, built in
 
 Add a `watch` array to any target. No flags, no extra tooling.
@@ -397,6 +481,11 @@ $ run :generate zed-tasks
 $ run :generate jetbrains-run-configurations
 ```
 
+Skip a target from the generated configs by setting `metadata.excludeFromGenerateCommand: true`. The
+`metadata` block on `globals` and on each target is **fully open** — any property of any JSON type
+(strings, numbers, booleans, arrays, deeply-nested objects) is accepted and round-trips untouched, so
+editor extensions and CI scripts can stash arbitrary tooling-specific fields here.
+
 #### Migrate in seconds
 
 ```bash

package/bin/linux-arm64/README.md

@@ -111,16 +111,16 @@ Sorted from where Runfile is most differentiated to where it lags behind.
 | Argument substitution with chained fallbacks                        |    ✅    |  ❌   |  ✅   |    ❌     |
 | JSON Schema autocomplete in editors                                 |    ✅    |  ❌   |  ❌   |    ✅     |
 | Watch mode, built-in                                                |    ✅    |  ❌   |  ❌   |    ✅     |
+| Output grouping / prefixing in parallel mode                        |    ✅    |  ❌   |  ❌   |    ✅     |
 | Native Windows (no WSL / msys2 needed)                              |    ✅    |  ❌   |  ✅   |    ✅     |
-| Parallel execution                                                  |    ✅    |  ✅   |  ❌   |    ✅     |
 | Shell completions                                                   |    ✅    |  ❌   |  ✅   |    ✅     |
 | Private / internal targets (`_name`)                                |    ✅    |  ❌   |  ✅   |    ✅     |
+| Built-in string functions (upper, replace, trim, regex, base64, …)  |    ✅    |  ❌   |  ✅   |    ✅     |
+| Parallel execution                                                  |    ✅    |  ✅   |  ❌   |    ✅     |
 | Single static binary                                                |    ✅    |  ✅   |  ✅   |    ✅     |
 | Pattern rules (`%.o: %.c`)                                          |    ❌    |  ✅   |  ❌   |    ❌     |
-| Output grouping / prefixing in parallel mode                        |    ❌    |  ❌   |  ❌   |    ✅     |
 | Preconditions / status checks                                       |    ❌    |  ❌   |  ❌   |    ✅     |
 | Incremental builds (sources / timestamps / checksums)               |    ❌    |  ✅   |  ❌   |    ✅     |
-| Built-in string functions (upper, replace, trim, …)                 |    ❌    |  ❌   |  ✅   |    ✅     |
 
 ---
 
@@ -167,9 +167,9 @@ $ run :env inject -f .env.production -- ./deploy.sh       # encrypted values aut
 
 #### Powerful argument substitution
 
-Positional, named, flags, env vars, and runtime context (`{{ RUN.os }}` / `{{ RUN.shell }}` / `{{ RUN.cwd }}` /
-`{{ RUN.file }}` / `{{ RUN.parent }}`) — with chained fallbacks and required values. The `{{ ... }}` syntax
-avoids collisions with shell `$(...)` command substitution.
+Positional, named, flags, env vars, and runtime context (`{{ RUN.os }}` / `{{ RUN.arch }}` / `{{ RUN.shell }}` /
+`{{ RUN.cwd }}` / `{{ RUN.file }}` / `{{ RUN.parent }}`) — with chained fallbacks and required values. The
+`{{ ... }}` syntax avoids collisions with shell `$(...)` command substitution.
 
 ```jsonc
 "PORT": "{{ ARGS.port ? ENV.PORT ? '3000' }}",
@@ -242,9 +242,15 @@ and work as full substitution bodies *or* as chain segments:
   //   transform : escape, repeat, replace_all, remove_all
   //   regex     : regex_replace, regex_remove, regex_matches
   //   build     : concat, join
+  //   split     : nth, first, last, count_parts
   //   encoding  : base64_encode, base64_decode
+  //   hashing   : sha256, md5
+  //   files     : read_file, file_exists
+  //   json      : json_get, json_set
+  //   error     : try
   //   shell     : shell_quote
   //   variables : define
+  //   cwd       : set_cwd
   "echo deploying-{{ to_upper(ARGS.env) }}",
   "curl -H \"X-Auth: {{ base64_encode(ENV.TOKEN) }}\" ...",
   "echo {{ concat('hello-', ARGS.name, '-2026') }}",
@@ -253,6 +259,13 @@ and work as full substitution bodies *or* as chain segments:
   "go test {{ replace_all(ARGS.flags, ' ', ' -tag=') }}",
   // Strip every match of a regex (here: collapse whitespace runs to a single space):
   "echo {{ regex_replace(ARGS.text, '\\s+', ' ') }}",
+  // Split-by-separator scalar accessors — string in, string out, no list type:
+  // basename idiom (last segment after `/`); empty string when input ends in `/`.
+  "echo basename={{ last(ARGS.path, '/') }}",
+  // Pull out the N-th comma-separated field; out-of-bounds returns "".
+  "echo target={{ nth(ARGS.csv, ',', '1') }}",
+  // Pair `count_parts` with `nth` to bound-check before indexing:
+  // "if": "{{ count_parts(ARGS.csv, ',') == '3' }}"
   // Boolean-returning helpers are valid DSL `Truthy` values — use them in `if`:
   // "if": "{{ starts_with(ARGS.path, '/usr') }}"
   // "if": "{{ regex_matches(ARGS.tag, '^v[0-9]+\\.[0-9]+$') }}"
@@ -261,6 +274,28 @@ and work as full substitution bodies *or* as chain segments:
   // `shell_quote` picks the right quoting for the active shell:
   "some-tool --json {{ shell_quote(base64_decode(ENV.SECRET_BASE64)) }}",
 
+  // Cache keys / content fingerprints. `sha256` for security-sensitive use,
+  // `md5` for cheap fingerprinting (NOT cryptographically secure).
+  "echo cache-key={{ sha256(read_file('package-lock.json')) }}",
+
+  // Branch on file presence without forking a shell. `file_exists` returns
+  // the literal "true" / "false", so it doubles as a DSL truthy value.
+  // "if": "{{ file_exists('.env.local') }}"
+
+  // Read a file inline — relative paths anchor to the Runfile directory.
+  // Use `try(...)` to recover from missing files.
+  "echo version={{ try(read_file('VERSION')) ? '0.0.0-dev' }}",
+
+  // Pull values out of arbitrary JSON without `jq` (works on every shell):
+  "echo db_host={{ json_get(read_file('config.json'), 'database.host') }}",
+
+  // Modify a JSON document in place (returns the new compact JSON):
+  "echo {{ json_set('{\"port\":3000}', 'env', 'production') }}",
+
+  // `try(expr)` swallows inner errors. Standalone returns "" on failure;
+  // chained, the next segment runs as a fallback.
+  "echo {{ try(base64_decode(ARGS.maybe_b64)) ? ARGS.maybe_b64 }}",
+
   // Nested:
   "echo {{ to_upper(to_lower(ARGS.x)) }}",
 
@@ -272,6 +307,13 @@ and work as full substitution bodies *or* as chain segments:
   "{{ VARS.sdk }}/bin/build",
   "echo using sdk at {{ VARS.sdk }}",
 
+  // `set_cwd(path)` switches the cwd subsequent commands spawn in — like
+  // shell `cd`, but works on every shell / OS without forking. Relative
+  // paths chain (matching `cd a; cd b` → `a/b`); absolute paths replace.
+  "{{ set_cwd(ARGS.subproject ? 'packages/api') }}",
+  "npm install",
+  "npm run build",
+
   // Single-quoted strings interpolate nested {{ }} substitutions:
   "{{ define(cmd, 'docker compose -f {{ VARS.compose }} pull') }}",
   "{{ VARS.cmd }}"
@@ -283,6 +325,22 @@ to only whitespace (i.e. one consisting solely of a `{{ define(...) }}` call) is
 being dispatched to the shell. `define`s in a parent target are visible to `@target` children. The `name` MUST
 be a bareword identifier matching `[A-Za-z_][A-Za-z0-9_-]*` — quotes are NOT allowed on the name.
 
+`set_cwd(path)` is the cwd analog of `define`: returns an empty string and changes the cwd that subsequent shell
+commands in the *current target* spawn in. Behaves like shell `cd`, but works uniformly across every shell / OS
+(no forked process, no `cd` binary needed). Resolution rules:
+
+- **Absolute path** → fully replaces the current override (matches `cd /abs`).
+- **Relative path** → joins onto the existing override, or onto the target's `workingDirectory` if no override
+  has been set yet. So `set_cwd('a'); set_cwd('b')` lands subsequent commands in `<workingDirectory>/a/b`,
+  matching how `cd a; cd b` chains in a shell.
+
+`set_cwd` is **per-target**: each `@target` invocation starts with a clean override (the dispatched target sees
+its own `workingDirectory`, not the caller's `set_cwd` state). Inside `parallel: true` targets each leaf
+captures the override at the moment of its substitution, so siblings don't race on the spawn cwd. Like
+`define`, the side effect is skipped on the redacted-logging pass so log lines don't double-apply it. With
+`sameShell: true`, only the *final* `set_cwd` value applies (everything joins into one shell invocation) — use
+shell `cd` directly between leaves there if you need intermediate cwd changes.
+
 Function args are separated by `, ` (comma + exactly one space).
 
 **Quote semantics inside `{{ ... }}`:**
@@ -311,13 +369,18 @@ evaluated by Runfile itself, so the logic works the same on every shell and plat
     "cases": {
       "1": "flutter emulators --launch Tier_1_Android_9",
       "2": "flutter emulators --launch Tier_2_Android_11",
-      "3": "flutter emulators --launch Tier_3_Android_14"
+      "3": "flutter emulators --launch Tier_3_Android_14",
+      // Case keys wrapped in `/.../` are treated as regex patterns.
+      // Literal cases always win over a regex that would also match.
+      "/^v\\d+$/": "echo version-tag",
+      "/^pr-\\d+$/": "echo preview-build"
     } },                                // unknown values error out, listing the valid cases
 
   { "for": "service",
     "in": ["api", "web", "worker"],
     "parallel": true,
-    "do": ["docker build -t {{ VARS.service }} services/{{ VARS.service }}"] },
+    // VARS.<name>_index exposes the 0-based iteration counter.
+    "do": ["echo [{{ VARS.service_index }}] docker build -t {{ VARS.service }} services/{{ VARS.service }}"] },
 
   { "for": "file",
     "shell": "git diff --name-only HEAD~1",
@@ -379,6 +442,27 @@ Wrap any commands in a `when:` block to run them only after a failure, or always
 ]
 ```
 
+#### Single-shell mode with `sameShell`
+
+By default each step runs in its own shell process, so `cd`, exported variables, and other shell state don't carry
+over between steps. Set `"sameShell": true` to join every step into a single shell invocation — state changes
+persist for free.
+
+```jsonc
+{
+  "deploy": {
+    "sameShell": true,
+    "commands": ["cd ci-scripts/", "./ci-deploy.sh"]
+  }
+}
+```
+
+Steps are joined with `&&` so the run stops at the first failure (or `;` / `&` when `ignoreErrors: true`). `if`,
+`for`, and `match` blocks are evaluated by Runfile and their chosen branches flow into the same joined invocation.
+`@target` calls inside the body are rejected — they have their own shell context and can't share state with the
+parent. `sameShell` also composes with `detach: true` (joined command spawns as one detached process) and is
+available on `globals` for project-wide defaults.
+
 #### Watch mode, built in
 
 Add a `watch` array to any target. No flags, no extra tooling.
@@ -397,6 +481,11 @@ $ run :generate zed-tasks
 $ run :generate jetbrains-run-configurations
 ```
 
+Skip a target from the generated configs by setting `metadata.excludeFromGenerateCommand: true`. The
+`metadata` block on `globals` and on each target is **fully open** — any property of any JSON type
+(strings, numbers, booleans, arrays, deeply-nested objects) is accepted and round-trips untouched, so
+editor extensions and CI scripts can stash arbitrary tooling-specific fields here.
+
 #### Migrate in seconds
 
 ```bash

package/bin/linux-x64/README.md

@@ -111,16 +111,16 @@ Sorted from where Runfile is most differentiated to where it lags behind.
 | Argument substitution with chained fallbacks                        |    ✅    |  ❌   |  ✅   |    ❌     |
 | JSON Schema autocomplete in editors                                 |    ✅    |  ❌   |  ❌   |    ✅     |
 | Watch mode, built-in                                                |    ✅    |  ❌   |  ❌   |    ✅     |
+| Output grouping / prefixing in parallel mode                        |    ✅    |  ❌   |  ❌   |    ✅     |
 | Native Windows (no WSL / msys2 needed)                              |    ✅    |  ❌   |  ✅   |    ✅     |
-| Parallel execution                                                  |    ✅    |  ✅   |  ❌   |    ✅     |
 | Shell completions                                                   |    ✅    |  ❌   |  ✅   |    ✅     |
 | Private / internal targets (`_name`)                                |    ✅    |  ❌   |  ✅   |    ✅     |
+| Built-in string functions (upper, replace, trim, regex, base64, …)  |    ✅    |  ❌   |  ✅   |    ✅     |
+| Parallel execution                                                  |    ✅    |  ✅   |  ❌   |    ✅     |
 | Single static binary                                                |    ✅    |  ✅   |  ✅   |    ✅     |
 | Pattern rules (`%.o: %.c`)                                          |    ❌    |  ✅   |  ❌   |    ❌     |
-| Output grouping / prefixing in parallel mode                        |    ❌    |  ❌   |  ❌   |    ✅     |
 | Preconditions / status checks                                       |    ❌    |  ❌   |  ❌   |    ✅     |
 | Incremental builds (sources / timestamps / checksums)               |    ❌    |  ✅   |  ❌   |    ✅     |
-| Built-in string functions (upper, replace, trim, …)                 |    ❌    |  ❌   |  ✅   |    ✅     |
 
 ---
 
@@ -167,9 +167,9 @@ $ run :env inject -f .env.production -- ./deploy.sh       # encrypted values aut
 
 #### Powerful argument substitution
 
-Positional, named, flags, env vars, and runtime context (`{{ RUN.os }}` / `{{ RUN.shell }}` / `{{ RUN.cwd }}` /
-`{{ RUN.file }}` / `{{ RUN.parent }}`) — with chained fallbacks and required values. The `{{ ... }}` syntax
-avoids collisions with shell `$(...)` command substitution.
+Positional, named, flags, env vars, and runtime context (`{{ RUN.os }}` / `{{ RUN.arch }}` / `{{ RUN.shell }}` /
+`{{ RUN.cwd }}` / `{{ RUN.file }}` / `{{ RUN.parent }}`) — with chained fallbacks and required values. The
+`{{ ... }}` syntax avoids collisions with shell `$(...)` command substitution.
 
 ```jsonc
 "PORT": "{{ ARGS.port ? ENV.PORT ? '3000' }}",
@@ -242,9 +242,15 @@ and work as full substitution bodies *or* as chain segments:
   //   transform : escape, repeat, replace_all, remove_all
   //   regex     : regex_replace, regex_remove, regex_matches
   //   build     : concat, join
+  //   split     : nth, first, last, count_parts
   //   encoding  : base64_encode, base64_decode
+  //   hashing   : sha256, md5
+  //   files     : read_file, file_exists
+  //   json      : json_get, json_set
+  //   error     : try
   //   shell     : shell_quote
   //   variables : define
+  //   cwd       : set_cwd
   "echo deploying-{{ to_upper(ARGS.env) }}",
   "curl -H \"X-Auth: {{ base64_encode(ENV.TOKEN) }}\" ...",
   "echo {{ concat('hello-', ARGS.name, '-2026') }}",
@@ -253,6 +259,13 @@ and work as full substitution bodies *or* as chain segments:
   "go test {{ replace_all(ARGS.flags, ' ', ' -tag=') }}",
   // Strip every match of a regex (here: collapse whitespace runs to a single space):
   "echo {{ regex_replace(ARGS.text, '\\s+', ' ') }}",
+  // Split-by-separator scalar accessors — string in, string out, no list type:
+  // basename idiom (last segment after `/`); empty string when input ends in `/`.
+  "echo basename={{ last(ARGS.path, '/') }}",
+  // Pull out the N-th comma-separated field; out-of-bounds returns "".
+  "echo target={{ nth(ARGS.csv, ',', '1') }}",
+  // Pair `count_parts` with `nth` to bound-check before indexing:
+  // "if": "{{ count_parts(ARGS.csv, ',') == '3' }}"
   // Boolean-returning helpers are valid DSL `Truthy` values — use them in `if`:
   // "if": "{{ starts_with(ARGS.path, '/usr') }}"
   // "if": "{{ regex_matches(ARGS.tag, '^v[0-9]+\\.[0-9]+$') }}"
@@ -261,6 +274,28 @@ and work as full substitution bodies *or* as chain segments:
   // `shell_quote` picks the right quoting for the active shell:
   "some-tool --json {{ shell_quote(base64_decode(ENV.SECRET_BASE64)) }}",
 
+  // Cache keys / content fingerprints. `sha256` for security-sensitive use,
+  // `md5` for cheap fingerprinting (NOT cryptographically secure).
+  "echo cache-key={{ sha256(read_file('package-lock.json')) }}",
+
+  // Branch on file presence without forking a shell. `file_exists` returns
+  // the literal "true" / "false", so it doubles as a DSL truthy value.
+  // "if": "{{ file_exists('.env.local') }}"
+
+  // Read a file inline — relative paths anchor to the Runfile directory.
+  // Use `try(...)` to recover from missing files.
+  "echo version={{ try(read_file('VERSION')) ? '0.0.0-dev' }}",
+
+  // Pull values out of arbitrary JSON without `jq` (works on every shell):
+  "echo db_host={{ json_get(read_file('config.json'), 'database.host') }}",
+
+  // Modify a JSON document in place (returns the new compact JSON):
+  "echo {{ json_set('{\"port\":3000}', 'env', 'production') }}",
+
+  // `try(expr)` swallows inner errors. Standalone returns "" on failure;
+  // chained, the next segment runs as a fallback.
+  "echo {{ try(base64_decode(ARGS.maybe_b64)) ? ARGS.maybe_b64 }}",
+
   // Nested:
   "echo {{ to_upper(to_lower(ARGS.x)) }}",
 
@@ -272,6 +307,13 @@ and work as full substitution bodies *or* as chain segments:
   "{{ VARS.sdk }}/bin/build",
   "echo using sdk at {{ VARS.sdk }}",
 
+  // `set_cwd(path)` switches the cwd subsequent commands spawn in — like
+  // shell `cd`, but works on every shell / OS without forking. Relative
+  // paths chain (matching `cd a; cd b` → `a/b`); absolute paths replace.
+  "{{ set_cwd(ARGS.subproject ? 'packages/api') }}",
+  "npm install",
+  "npm run build",
+
   // Single-quoted strings interpolate nested {{ }} substitutions:
   "{{ define(cmd, 'docker compose -f {{ VARS.compose }} pull') }}",
   "{{ VARS.cmd }}"
@@ -283,6 +325,22 @@ to only whitespace (i.e. one consisting solely of a `{{ define(...) }}` call) is
 being dispatched to the shell. `define`s in a parent target are visible to `@target` children. The `name` MUST
 be a bareword identifier matching `[A-Za-z_][A-Za-z0-9_-]*` — quotes are NOT allowed on the name.
 
+`set_cwd(path)` is the cwd analog of `define`: returns an empty string and changes the cwd that subsequent shell
+commands in the *current target* spawn in. Behaves like shell `cd`, but works uniformly across every shell / OS
+(no forked process, no `cd` binary needed). Resolution rules:
+
+- **Absolute path** → fully replaces the current override (matches `cd /abs`).
+- **Relative path** → joins onto the existing override, or onto the target's `workingDirectory` if no override
+  has been set yet. So `set_cwd('a'); set_cwd('b')` lands subsequent commands in `<workingDirectory>/a/b`,
+  matching how `cd a; cd b` chains in a shell.
+
+`set_cwd` is **per-target**: each `@target` invocation starts with a clean override (the dispatched target sees
+its own `workingDirectory`, not the caller's `set_cwd` state). Inside `parallel: true` targets each leaf
+captures the override at the moment of its substitution, so siblings don't race on the spawn cwd. Like
+`define`, the side effect is skipped on the redacted-logging pass so log lines don't double-apply it. With
+`sameShell: true`, only the *final* `set_cwd` value applies (everything joins into one shell invocation) — use
+shell `cd` directly between leaves there if you need intermediate cwd changes.
+
 Function args are separated by `, ` (comma + exactly one space).
 
 **Quote semantics inside `{{ ... }}`:**
@@ -311,13 +369,18 @@ evaluated by Runfile itself, so the logic works the same on every shell and plat
     "cases": {
       "1": "flutter emulators --launch Tier_1_Android_9",
       "2": "flutter emulators --launch Tier_2_Android_11",
-      "3": "flutter emulators --launch Tier_3_Android_14"
+      "3": "flutter emulators --launch Tier_3_Android_14",
+      // Case keys wrapped in `/.../` are treated as regex patterns.
+      // Literal cases always win over a regex that would also match.
+      "/^v\\d+$/": "echo version-tag",
+      "/^pr-\\d+$/": "echo preview-build"
     } },                                // unknown values error out, listing the valid cases
 
   { "for": "service",
     "in": ["api", "web", "worker"],
     "parallel": true,
-    "do": ["docker build -t {{ VARS.service }} services/{{ VARS.service }}"] },
+    // VARS.<name>_index exposes the 0-based iteration counter.
+    "do": ["echo [{{ VARS.service_index }}] docker build -t {{ VARS.service }} services/{{ VARS.service }}"] },
 
   { "for": "file",
     "shell": "git diff --name-only HEAD~1",
@@ -379,6 +442,27 @@ Wrap any commands in a `when:` block to run them only after a failure, or always
 ]
 ```
 
+#### Single-shell mode with `sameShell`
+
+By default each step runs in its own shell process, so `cd`, exported variables, and other shell state don't carry
+over between steps. Set `"sameShell": true` to join every step into a single shell invocation — state changes
+persist for free.
+
+```jsonc
+{
+  "deploy": {
+    "sameShell": true,
+    "commands": ["cd ci-scripts/", "./ci-deploy.sh"]
+  }
+}
+```
+
+Steps are joined with `&&` so the run stops at the first failure (or `;` / `&` when `ignoreErrors: true`). `if`,
+`for`, and `match` blocks are evaluated by Runfile and their chosen branches flow into the same joined invocation.
+`@target` calls inside the body are rejected — they have their own shell context and can't share state with the
+parent. `sameShell` also composes with `detach: true` (joined command spawns as one detached process) and is
+available on `globals` for project-wide defaults.
+
 #### Watch mode, built in
 
 Add a `watch` array to any target. No flags, no extra tooling.
@@ -397,6 +481,11 @@ $ run :generate zed-tasks
 $ run :generate jetbrains-run-configurations
 ```
 
+Skip a target from the generated configs by setting `metadata.excludeFromGenerateCommand: true`. The
+`metadata` block on `globals` and on each target is **fully open** — any property of any JSON type
+(strings, numbers, booleans, arrays, deeply-nested objects) is accepted and round-trips untouched, so
+editor extensions and CI scripts can stash arbitrary tooling-specific fields here.
+
 #### Migrate in seconds
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runfile/cli",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Runfile CLI — an easy-to-use, batteries-included task runner",
   "repository": "https://github.com/Skiley/runfile",
   "homepage": "https://github.com/Skiley/runfile",