windows_path
Experimental. One folder in a Windows host’s Path, the machine’s or the login user’s. The other folders and their order stay as they are. New logons see a change; programs already running keep the Path they started with.
Experimental. New, and tested on GitHub’s Windows Server 2022 and 2025 runners, not yet on an Azure server. See Windows readiness.
Use windows_path to put one folder on a Windows host’s Path, such as a tool’s bin folder, and leave every other folder where it is. Path is one long string, so setting it whole with setx or SetEnvironmentVariable is how servers lose half their tools, and how %SystemRoot% gets expanded into a fixed C:\Windows. This step changes one folder and nothing else.
Example usage
Section titled “Example usage”step "go_on_path" { windows_path { element = "C:\\Program Files\\Go\\bin" }}Take an old folder out of the user’s own Path:
step "old_tool_gone" { windows_path { element = "C:\\OldTool" scope = "user" state = "absent" }}Arguments
Section titled “Arguments”| Name | Type | Required | Description |
|---|---|---|---|
element |
string | Yes | The folder, such as C:\Program Files\Go\bin. Compared as Windows does, without case and with or without a trailing backslash. Added at the end. |
on_remove |
string | No | What happens on the host when this resource is removed: “forget” (default) leaves the folder in Path, “delete” takes it out. |
scope |
string | No | “machine” (default), in HKLM for every account, or “user”, in HKCU for the account Conn3x logs in as. Changing it is a different Path entry. |
state |
string | No | “present” (default), or “absent” to take every copy of the folder out. |
Read-only attributes
Section titled “Read-only attributes”Conn3x sets these; reference them as conn3x_windows_path.<circuit>__<step>["<host>"].<name>.
| Name | Type | Description |
|---|---|---|
in_sync |
bool | Whether Path had the folder, or didn’t for state “absent”, at the last refresh. |
revision |
string | Changes each time Conn3x changes this on the host. Handlers watch it. |
A step lowers to the conn3x_windows_path resource, one instance per host, and connects with its circuit’s ssh block.
How it works
Section titled “How it works”Reading. On every plan, Conn3x reads Path from the registry, the machine’s or the user’s, without expanding it, and looks for the folder. Folders compare the way Windows compares them: C:\Tools, c:\tools and C:\Tools\ are the same folder.
Applying. To add the folder, Conn3x reads Path again and writes it back with the folder at the end. To remove it, every copy of it comes out. The other folders, their order and their %SystemRoot%-style names are written back exactly as they were, and Path keeps its type, so it still expands.
When it takes effect. New logons, and programs they start, see the change. Programs already running, services included, keep the Path they started with until they restart.
Changes. Changing state updates Path in place. Changing element or scope replaces the step.
Removal
Section titled “Removal”on_remove = "forget", the default, leaves the folder on Path. on_remove = "delete" takes it out.