# ci.path

The `ci.path` function prepends a directory to `PATH` for the steps that run after the current one. Locally, it
prints the matching `export` line.

## Usage

```python
ci.path(dir)
```

## Arguments

- **`dir`**
  Required. The directory to add, as a string. Use an absolute path so later steps resolve it from any working directory.

## Returns

The return value is `None`.

## Behavior

- On GitHub Actions, the directory is written to the path file that the runner reads between steps. It does not
  change the `PATH` of the script that calls it.
- Locally, the call prints `export PATH=dir:"$PATH"` on stderr, with the directory shell-quoted only when it needs
  quoting. When `ATMOS_CI_PATH` names a file, the directory is appended to that file, one per line.
- Under `pull_request_target` and `workflow_run`, the call is held for a pull request from a fork. See the
  [fork gate](/functions/automation/ci#fork-gate).
- In CI the call is gated by [`ci.output.enabled`](/cli/configuration/ci/output), which also gates `ci.output` and
  `ci.env`. When it is off, the call warns, renders locally, and the script continues. See
  [gating](/functions/automation/ci#gating).

## Examples

### Add a tool directory

```python
ci.path("/opt/tools/bin")
```

### Add a freshly built binary

Save this as `build.star` and pass an absolute output directory:

```python
build_dir = ctx.args[0]
exec.run(["go", "build", "-o", build_dir + "/atmos", "."])
ci.path(build_dir)
```

```shell
atmos ./build.star /absolute/path/to/build
```

## Errors

- A missing or non-string `dir` fails with an argument error that names `ci.path`.
- A failure to write the path file fails the script. A gated-off call never fails.

## Related

- [`ci`](/functions/automation/ci) describes the module and the shared behavior rules.
- [`ci.env`](/functions/automation/ci.env) exports an environment variable.
- [`ctx.args`](/functions/automation/ctx.args) provides the arguments passed to a standalone script.