# CLI configuration

> Where the CLI keeps sessions and selections, and how pier.yaml anchors a directory

URL: https://pier.run/docs/cli/configuration

## pier.yaml is the link

`pier` finds the project by walking up from the current directory to the nearest
`pier.yaml` and reading its `project:` key. Nothing is saved per directory; the file itself
links the directory to the project. `pier config init` writes it for a new project;
`pier config sync` writes it for one that already exists on the server.

```bash
pier config init --name acme        # new project + pier.yaml here
pier config sync                     # pull the server's state into pier.yaml
pier config diff                     # what pier.yaml would change
pier config validate                 # syntax and references, no server call
```

The file's shape: [Concepts](/docs/concepts#environment).

## State on disk

| Path (macOS; XDG on Linux)                       | Holds                                                          |
| ------------------------------------------------ | -------------------------------------------------------------- |
| `~/Library/Application Support/pier/config.json` | profiles and their session tokens                              |
| `~/Library/Application Support/pier/state.json`  | sticky selections: workspace, project, environment per profile |

`--no-state` ignores the saved selections and prompts. `pier logout` removes the
profile's token; `pier uninstall` removes everything.

## Precedence

| Setting     | Order                                                               |
| ----------- | ------------------------------------------------------------------- |
| profile     | `--profile` → `PIER_PROFILE` → `pier profiles use`                  |
| workspace   | `-w` → `pier workspaces use` → the only one                         |
| project     | `pier.yaml` above cwd → `-p` / `PIER_PROJECT` → `pier projects use` |
| environment | `-e` → `pier use` / accepted picker → the only one                  |