Tasks, aliases, and hooks

Declare a task with its context

Tasks live alongside resources. The default working directory is the entry point’s directory; relative cwd values resolve there. Environment overrides affect only that process.

import { defineConfig, task } from "@dovocode/workstation";

export default defineConfig({
  tasks: {
    test: task("pnpm", ["test"], {
      cwd: "projects/app",
      environment: { NODE_ENV: "test" },
      description: "Run the app tests",
    }),
  },
  aliases: { t: "test" },
});

Dispatch only the selected command

A task evaluates the configuration and executes the selected command. It does not reconcile resources or write ownership state. Use build for the setup itself.

Place Workstation flags before the task name. Arguments after it belong to the task. One optional -- separator is removed; remaining arguments are appended unchanged.

workstation --list-tasks
workstation t -- --watch
workstation --machine studio test

Understand direct execution

Commands execute without shell interpolation. Declare a shell explicitly for pipelines. Output streams live and the CLI returns the task’s exit code. No PTY is allocated; fully interactive terminal programs can behave differently.

Selected node, npm, npx, and pnpm CLI tasks prepare their pinned runtime through mise. Other executables must already be available. Embedded API tasks do not perform this CLI bootstrap.

Use hooks for post-apply work

Declare afterApply with task helpers for commands that should follow successful build or upgrade reconciliation. Hooks run sequentially, including after unchanged builds, so make them safe to repeat.