# Sessions and credentials

> Sessions and credentials in UiPath CLI, covering how sessions are persisted, resolved per command, and refreshed across authentication flows.

A `uip` session is the state that binds a command to a specific UiPath organization and tenant, and that lets the CLI present a valid access token without prompting the user on every call. Sessions are persisted on disk for the interactive and External App flows, and are reconstructed from environment variables for the env-var flow. This page explains where that state lives, how `uip` finds it, and what to expect when you move between tenants or machines.

## The credentials folder

`uip login` persists the session inside a folder called `.uipath/`. Treat its contents as opaque — they are managed by `uip login`, `uip login tenant set`, and `uip logout`, and the on-disk layout is an implementation detail that may change between releases. The folder holds an access token, a refresh token, and the active organization and tenant.

Protect the folder. It contains tokens that can impersonate your session until they are revoked. In multi-user or shared environments, keep it in a home directory with the usual `0600` permissions on its contents. On a developer machine it is usually enough to leave it where `uip login` put it. Add `.uipath/` to `.gitignore` if a project-local session is per-developer.

## Location resolution (walk-up)

When any `uip` command runs, the CLI looks for the credentials folder in this order:

1. **Explicit path** — if a command was invoked with `-f /path/to/folder`, that folder is used. The path can be absolute or relative.
2. **Walk up from the current directory** — starting at `cwd`, the CLI checks `./.uipath/`, then walks up the parent chain looking for the same folder. The first one it finds wins.
3. **User home** — if no project-local folder was found on the walk-up, the CLI falls back to `~/.uipath/`.

`uip login` writes to the path that would be read by the next command:

- If you ran `uip login` inside a directory with an existing `.uipath/` on the walk-up chain, the login refreshes that session in place.
- Otherwise, it creates `~/.uipath/` in your home directory.

### Why walk-up?

Walking up from `cwd` lets a project folder carry its own session without modifying your home directory. Place a `.uipath/` folder in a repo root, and everyone who runs `uip` from inside the repo picks up that project's login — useful for per-project client credentials, staging tenants, or demo environments.

### Overriding the location

Three ways to override the lookup:

- `-f, --file <folder>` on `uip login` and `uip logout` — use the specified folder for this command only.
- A separate home directory — on a shared build server, run `HOME=/srv/build-home uip login` to write to `/srv/build-home/.uipath/`.
- `uip completion` and other commands do not take a `-f` flag and always use the walk-up + home fallback.

For inspection:

```bash
# print the current session status (reads via walk-up)
uip login status
```

`uip login status` always reads via the walk-up + home fallback; it does not accept `-f`. To inspect a session in a non-default folder, change into that directory (or a subdirectory of it) before running `uip login status`, or list available tenants with `uip login tenant list -f /path/to/creds`.

## Active organization and tenant

A session stores one organization and one tenant at a time. The tenant is the UiPath concept that scopes folders, jobs, queues, and resources — effectively the "account" the CLI reaches whenever you run `uip or …`.

Change the active tenant without re-authenticating:

```bash
uip login tenant list           # show all tenants this session can access
uip login tenant set MyTenant   # switch the active tenant
```

Behind the scenes, `uip login tenant set` mints new access/refresh tokens for the new tenant and updates the stored session in place.

Pass `--tenant <name>` on any `uip or …` call to override the session's active tenant for a single command, without changing the on-disk session:

```bash
uip or folders list --tenant Staging
uip or jobs start "$PROCESS_KEY" --tenant Production
```

## Refreshing tokens

Access tokens are short-lived. When the CLI detects that the stored access token is near expiry, it uses the refresh token to request a new one and silently updates the stored session. You do not need to re-run `uip login` unless one of the following happens:

- The refresh token itself expires or is revoked (typically after weeks of inactivity, or when an admin forces a sign-out).
- You changed organization.
- You need a different scope set from what the session was authenticated with.

`uip login status` reports `Expired` when the refresh has failed; that is the signal to run `uip login` again.

## The env-var flow (no file)

The third authentication flow, enabled by `UIPATH_CLI_ENABLE_ENV_AUTH=true`, bypasses the credentials folder entirely. Every `uip` command reads the token and tenant from environment variables, uses them as-is, and writes nothing to disk.

This is the right choice for:

- Containers that receive a token from a parent pipeline.
- Ephemeral CI runners where persisting credentials to disk is wasteful or forbidden.
- Any environment where the CLI must be stateless between invocations.

Differences from the file-based flows:

- **No refresh.** The token is opaque to `uip` — if it is expired, the caller is responsible for rotating it.
- **`uip logout` does nothing.** There is no file to remove. Unset the env vars to "sign out".
- **Base URL is derived from the token.** Whatever `iss` claim the JWT carries is treated as authoritative — do not set `UIPATH_URL` in tandem with `UIPATH_CLI_AUTH_TOKEN`, or you will desync.

See [Authentication — Flow 3](./authentication.md#flow-3-environment-variable-auth-access-token-already-in-hand) for the full set of variables and GitHub Actions / container examples.

## Signing out

File-based flows:

```bash
uip logout                        # clear ~/.uipath/ or the walk-up match
uip logout -f /path/to/creds      # clear a specific credentials folder
```

`logout` clears the stored session. Subsequent `uip or …` calls will fail with `AuthenticationError` (exit code `2`) until you run `uip login` again. To invalidate the session on the server side as well, revoke the External App's secret in Automation Cloud or sign out of your user account.

Env-var flow: unset `UIPATH_CLI_ENABLE_ENV_AUTH` (and the token variables, to be safe).

## See also

- [Authentication](./authentication.md) — the three flows that write or bypass the credentials folder.
- [Configuration](./configuration.md) — environment-variable precedence, which lives beside but separate from the credentials folder.
- [uip login reference](./uip-login.md), [uip login status reference](./uip-login-status.md), [uip logout reference](./uip-logout.md) — per-command flag lists and examples.
- [Installing UiPath CLI — Remove credentials and data](./installing-uipath-cli.md#remove-credentials-and-data) — cleanup after uninstall.