Working Directory (--cwd)#

Overview#

The --cwd (short: -C) global flag changes the logical working directory for all path resolution without mutating the process CWD. It behaves similarly to git -C:

scafctl --cwd /path/to/project run solution -f solution.yaml
scafctl -C /path/to/project run resolver -f demo.yaml -o json

When --cwd is set, all relative paths – including -f, --output-dir, snapshot paths, and auto-discovery – resolve against the specified directory instead of the process CWD.

Architecture#

Context-Based Resolution#

The --cwd flag is injected into the Go context.Context via provider.WithWorkingDirectory(), avoiding global state mutation. This design:

• Is safe for concurrent use (MCP server handles multiple requests)
• Does not affect other goroutines or the process environment
• Composes cleanly with --output-dir (which operates on a separate context key)

Resolution Flow#

CLI:  --cwd flag → root PersistentPreRunE → provider.WithWorkingDirectory(ctx)
MCP:  cwd param  → s.contextWithCwd()     → provider.WithWorkingDirectory(ctx)
                                                    ↓
                                          provider.AbsFromContext(ctx, path)
                                                    ↓
                                          filepath.Join(cwd, relativePath)

Key Functions#

Interaction with --output-dir#

The --cwd and --output-dir flags serve different purposes and compose together:

When both are set:

• Resolvers resolve paths against --cwd
• Actions resolve output paths against --output-dir
• A relative --output-dir itself is resolved against --cwd

# Resolvers read from /project, actions write to /project/out
scafctl --cwd /project run solution -f sol.yaml --output-dir out

MCP Server#

All MCP tools that accept file paths support an optional cwd parameter. When provided, it behaves identically to the CLI --cwd flag:

{
  "tool": "render_solution",
  "arguments": {
    "path": "solution.yaml",
    "cwd": "/path/to/project"
  }
}

Solution Directory Anchoring#

MCP tools that load and execute a solution (preview_resolvers, render_solution, run_solution, dry_run_solution, preview_action) also anchor the solution’s own directory onto the context via provider.WithSolutionDirectory() after the solution is loaded, provided the solution has a local directory (a local file path or an extracted catalog bundle). This mirrors the CLI run commands and ensures that:

• relativeTo: solution reads resolve against the solution file’s directory
• The directory and hcl providers resolve their default base path against the solution directory when cwd is not supplied (see the precedence note below – when cwd is set, AbsFromContext prefers it first)

For stdin (-) and unbundled catalog references there is no solution directory, so nothing is anchored and relativeTo: solution falls back to the process CWD.

This anchoring is independent of cwd. Even when cwd is not supplied, solution-relative reads resolve against the solution directory rather than the MCP server’s process CWD. The cwd parameter still controls where the solution path itself and other non-solution-relative paths resolve from. When both apply, AbsFromContext prefers the working directory (cwd), then the solution directory, then os.Getwd().

Tools with cwd Support#

Tools without cwd (not applicable)#

Fallback Behavior#

When --cwd is not set:

1. WorkingDirectoryFromContext returns ("", false)
2. AbsFromContext next checks SolutionDirectoryFromContext. For MCP solution-executing tools this is set to the loaded solution’s directory (see Solution Directory Anchoring ); for other cases it is unset.
3. If neither is set, AbsFromContext falls through to filepath.Abs() which uses os.Getwd()
4. Behavior is identical to running without --cwd – fully backward compatible

Validation#

The --cwd value is validated at entry point (CLI root or MCP contextWithCwd):

1. Resolved to absolute path via filepath.Abs
2. Checked for existence via os.Stat
3. Verified to be a directory (not a file)

Invalid values produce a clear error before any command logic executes.

Catalog Solution CWD#

When running a catalog solution (bare name), the bundle is extracted to a temporary directory and the process CWD is changed there so resolvers can read bundled files.

However, file-writing actions need to resolve relative paths against the caller’s original working directory – not the temporary bundle directory. The CLI injects the caller’s CWD into the action execution context via provider.WithWorkingDirectory(actionCtx, originalCwd). This ensures AbsFromContext resolves relative action paths against the caller’s CWD, matching the behaviour of local -f file runs.

Catalog run:  scafctl run solution my-app

1. User is in /projects/my-app (caller CWD)
2. Bundle extracted to /tmp/scafctl-bundle-xyz/
3. os.Chdir(/tmp/scafctl-bundle-xyz/)   ← resolvers read bundled files here
4. originalCwd captured as /projects/my-app
5. actionCtx = WithWorkingDirectory(ctx, originalCwd)
6. Actions resolve "./output" → /projects/my-app/output  ← correct

This aligns with how tools like npm init, cargo init, and cookiecutter work – they scaffold into the directory you run them from, regardless of where the template source lives.

When --output-dir is specified, it takes precedence over the context CWD for action path resolution (unchanged behaviour).