Execution Styles#

Nash tasks support three execution styles. Each task must use exactly one style.

Command Style#

The command field passes a single string to the system shell for interpretation. Shell features like pipes, redirects, globbing, and variable expansion are all available.

[[task]]
id = "serve"
title = "Start Dev Server"
command = "npm run dev -- --port 3000"

A shell override can be used to force a specific shell regardless of the platform default:

[[task]]
id = "deploy"
title = "Deploy"
shell = ["bash", "-c"]
command = "deploy.sh --env production"

Argv Style#

The argv field passes an argument vector directly to the executable without shell interpretation. No globbing, no variable expansion, no piping — the process receives exactly the tokens you specify.

[[task]]
id = "lint"
title = "Lint Project"
argv = ["cargo", "clippy", "--", "-D", "warnings"]

This is ideal when arguments contain spaces, special characters, or when you want deterministic behavior across platforms without quoting concerns.

Multi-Step Execution#

Tasks with [[task.step]] entries run a sequence of commands in order. If any step fails, execution stops and the task is marked as failed.

[[task]]
id = "quality-gates"
title = "Quality Gates"
target = "new_tab"

[[task.step]]
name = "Format Check"
command = "cargo fmt --check"

[[task.step]]
name = "Lint"
command = "cargo clippy -- -D warnings"

[[task.step]]
name = "Tests"
argv = ["cargo", "test"]

Step-Level Overrides#

Each step can override task-level settings:

Field	Type	Description
`name`	string	Human-readable step name (shown in progress output)
`cwd`	string / path	Step-local working directory
`env`	table	Step-local environment variables (merged with task)
`shell`	array of strings	Step-local shell argv prefix
`command`	string	Shell command for this step
`argv`	array of strings	Argv-style execution for this step

[[task]]
id = "build-and-test"
title = "Build & Test"
env = { NODE_ENV = "production" }

[[task.step]]
name = "Frontend Build"
cwd = "./frontend"
command = "npm run build"

[[task.step]]
name = "Backend Tests"
cwd = "./backend"
env = { TEST_DB = "sqlite" }
command = "pytest"

Note: Step cwd and env are composed into generated scripts in declaration order. Earlier steps' env vars are inherited by later steps within the same task.

Working Directory (`cwd`) Behavior#

Nash provides native support for setting working directories at both the Task level and the Step level, with clear precedence, relative path resolution, and execution isolation.

1. Where do I specify `cwd`?#

Task-level cwd: Applies a default working directory to the entire task execution. It is configured directly inside the [[task]] block using the cwd field.
Step-level cwd: Overrides the task's default working directory for that specific step. It is configured directly inside the [[task.step]] block using the cwd field.

Both options support absolute paths as well as relative paths.

[!NOTE] Relative paths are automatically resolved relative to your active project directory at parse time by the internal path resolver.

2. Can I specify `cwd` in `task.step`?#

Yes, absolutely. ``

configure it exactly like this in your .nash.toml or tasks.toml file:

[[task.step]]
name = "My Step"
cwd = "path/to/subdirectory"
command = "npm run build"

3. Isolated Working Directories per Step#

Each step can have its own completely independent working directory.

Nash wraps the execution in a subshell (cd path/to/dir && command), the directory change cd is fully isolated to that specific step and does not leak or pollute the working directory of subsequent steps.

On Windows#

The command renderer prefixes each step with an explicit directory switch using the /d flag:

lines.push(format!("cd /d {}", cmd_quote(cwd.to_string_lossy().as_ref())));

This guarantees that each step explicitly shifts to its designated directory before running.

Concrete TOML Example#

Here is how you would configure a multi-step task in your .nash.toml where each step runs in a different directory:

[[task]]
id = "build-subprojects"
title = "Build Frontend and Backend"
description = "Compiles frontend assets and updates backend dependencies"
icon = "cod_run_all"

[[task.step]]
name = "Build Frontend"
cwd = "client/frontend"
command = "npm run build"

[[task.step]]
name = "Prepare Backend"
cwd = "server/backend"
command = "cargo build --release"

Continue to Targets & Execution Domains to control where (new window, new tab, new pane etc...) your tasks run.