One name per setting

A tool with forty knobs usually has three names for each one: a config
key, an environment variable that grew a _MS suffix, and a flag someone
shortened. vx gives every setting one path, and spells the other two
from it.

Setting	Variable	Flag
run.retries	VX_RUN_RETRIES	--retries
run.concurrency	VX_RUN_CONCURRENCY	--concurrency
cache.dir	VX_CACHE_DIR	--cache-dir
cache.scope	VX_CACHE_SCOPE	--cache-scope

The settings live in three groups in .vx/workspace.ts: run, cache
and watch.

// .vx/workspace.ts
import { defineWorkspace } from '@vzn/vx/config'

export default defineWorkspace({
  run: { concurrency: 4, killGrace: '5s' },
  cache: { retention: { olderThan: '30d', maxSize: '10GB' } },
})

Which value wins

A flag beats its variable, which beats the file, which beats the
built-in default. A task's own field beats all four: exec.retries on
a task is that task's count, whatever --retries says. vx info lists
every setting that is not at its default and where its value came from:

$ VX_RUN_CONCURRENCY=2 vx info
…
settings:         run.concurrency 2 (VX_RUN_CONCURRENCY), run.killGrace 5s (.vx/workspace)

Units are part of the value

A duration says its unit ('500ms', '30s', '10m', '2h', '30d'),
and a size says its own ('10GB'). A bare number is refused, because
nobody can tell whether 2000 means milliseconds or seconds:

$ VX_RUN_KILL_GRACE=2000 vx run build
vx: VX_RUN_KILL_GRACE takes a duration with its unit, like '2000ms' or '2s' (got 2000)

Old names stop working

The names from before vx 0.0.637 are gone, with no alias. An old key in
.vx/workspace.ts is an unknown field, and an old flag an unknown flag:

$ vx run build
vx: /repo/.vx/workspace.ts has unknown field "concurrency" (allowed: cache, plugins, run, watch)

An old variable such as VX_KILL_GRACE_MS is no longer read; set
VX_RUN_KILL_GRACE instead.

A few settings are read before the workspace file loads, such as
run.outputLogs and debug.timing. Those are set only by a variable
or a flag, never in the file. Every setting, with its variable, flag, values and default, is in
the settings table.

---

Originally published on the vx blog. vx is open-source (MIT) task orchestration with a build cache: vznjs.github.io/vx · GitHub.

_{Written with AI assistance.}