Sessions and credentials

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:

# 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:

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:

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 for the full set of variables and GitHub Actions / container examples.

Fazer logout

File-based flows:

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).

Veja também

• Authentication — the three flows that write or bypass the credentials folder.
• Configuration — environment-variable precedence, which lives beside but separate from the credentials folder.
• uip login reference, uip login status reference, uip logout reference — per-command flag lists and examples.
• Installing UiPath CLI — Remove credentials and data — cleanup after uninstall.