身份验证

UiPath CLI supports three authentication flows that map to the three common use cases: a developer on a laptop, a CI/CD pipeline calling Orchestrator with an External Application, and a container or ephemeral runner that already holds an access token. All three end at the same place — an authenticated session that every subsequent uip command reuses — but they differ in how they obtain the token and how the CLI refreshes it.

Pick a flow

You are…	Use this	如何
A developer on a laptop or workstation	Interactive OAuth2	uip login opens a browser, you sign in once, tokens are stored and refreshed automatically.
A CI/CD pipeline or server	External Application (client credentials)	Create an External App in UiPath, pass its ID and secret to uip login --client-id … --client-secret …. Tokens are stored and refreshed.
A container, ephemeral runner, or any process that already holds a token	Environment-variable auth	Set UIPATH_CLI_ENABLE_ENV_AUTH=true and supply the token + organization/tenant via env vars. No file is written; no refresh.

uip logout clears any on-disk credentials from the first two flows. The env-var flow has nothing to clear — unset the env vars.

Flow 1 — Interactive OAuth2

Run uip login with no arguments:

uip login

uip opens your default browser on UiPath's sign-in page. After you authenticate, UiPath redirects back to a local callback that uip is listening on, and the CLI prompts you to pick a tenant. When the tenant is selected, the session is saved and you are done.

Useful flags:

uip login --tenant DefaultTenant                 # skip the tenant picker
uip login --organization my-org                  # skip the org picker for users in multiple orgs
uip login --interactive                          # explicitly show the tenant picker even if --tenant was set
uip login --authority https://example.com        # point at a non-default identity authority (Automation Suite, staging)
uip login --scope "OR.Folders OR.Jobs"           # restrict the session to specific scopes
uip login --file /path/to/creds                  # store credentials in a non-default folder

Where credentials are stored

By default, the session is stored inside a .uipath/ folder. uip looks for this folder in three places, in order:

1. Explicit folder — if you passed --file <folder>, the CLI uses that folder. Pass the folder, not a file path.
2. Walk up from the current working directory looking for .uipath/ — so a project folder can carry its own session without touching the user's home.
3. ~/.uipath/ — the default fallback.

When no .uipath/ exists anywhere on the walk-up chain, uip login creates one at ~/.uipath/. Treat the folder's contents as opaque — they are managed by uip login, uip login tenant set, and uip logout.

Manage tenants mid-session

The session stores a single active tenant at a time. Switch without re-running the full login flow:

uip login tenant list           # show all tenants available to your account
uip login tenant set MyTenant   # switch the active tenant

uip login status shows the current organization, tenant, and token expiration.

提示：

Every uip or … command also accepts --tenant <name> to override the session tenant for a single call — useful when you need to run against two tenants in the same script without re-logging.

Refresh is automatic

uip refreshes access tokens in the background when they are near expiry. You do not need to re-run uip login unless the refresh token itself expires or is revoked, or you change tenants/organizations.

Flow 2 — External Application (client credentials)

Create an External Application in UiPath (Automation Cloud: Admin → External Applications) with:

• Application type: Confidential
• Grant type: Client credentials
• Scopes: the scopes your pipeline needs (for example, OR.Folders, OR.Jobs, OR.Execution, OR.Assets, OR.Users)

Copy the generated App ID and App Secret, and store them in the pipeline's secret store (GitHub Actions secrets, Azure DevOps variable groups, Jenkins credentials, Vault, etc.).

Sign in from the pipeline:

uip login \
  --client-id env.UIPATH_CLIENT_ID \
  --client-secret env.UIPATH_CLIENT_SECRET \
  --tenant "$UIPATH_TENANT"

The env.VAR_NAME prefix

--client-id and --client-secret accept either a literal value or the special prefix env. that resolves to an environment variable at runtime. env.UIPATH_CLIENT_ID means "read the value from the UIPATH_CLIENT_ID environment variable". This keeps secret values out of shell history and process listings — unlike --client-secret "$UIPATH_CLIENT_SECRET", which expands on the command line.

Literal values still work:

uip login --client-id 3c7af0…-… --client-secret s3cr3t…   # works, but the secret is visible in history

警告：

Do not set UIPATH_CLIENT_ID / UIPATH_CLIENT_SECRET as environment variables and expect uip login to pick them up automatically. Prior to UiPath CLI 1.0, uip login --env and implicit env-var reading were supported; they were removed. You must pass the flag explicitly, either with a literal value or with the env. prefix.

Scope overrides

If the External App has multiple scopes and you want a narrower session for a specific script, pass --scope:

uip login \
  --client-id env.UIPATH_CLIENT_ID \
  --client-secret env.UIPATH_CLIENT_SECRET \
  --tenant "$UIPATH_TENANT" \
  --scope "OR.Folders OR.Jobs"

Flow 3 — Environment-variable auth (access token already in hand)

Some environments — containers built by another pipeline, scheduled jobs, test fixtures — already hold a valid UiPath access token and have no need for interactive sign-in or client-credentials exchange. Enable the env-var auth flow by setting:

export UIPATH_CLI_ENABLE_ENV_AUTH=true

export UIPATH_CLI_AUTH_TOKEN="$UIPATH_TOKEN"            # JWT access token
export UIPATH_CLI_ORGANIZATION_NAME=my-org
export UIPATH_CLI_ORGANIZATION_ID="$UIPATH_ORG_ID"
export UIPATH_CLI_TENANT_NAME=DefaultTenant
export UIPATH_CLI_TENANT_ID="$UIPATH_TENANT_ID"

With UIPATH_CLI_ENABLE_ENV_AUTH=true, every uip invocation authenticates from these variables and bypasses the .uipath/ folder entirely. There is no uip login step and nothing is written to disk.

Notes and limitations

• Opaque token. The caller is responsible for the token's freshness. There is no refresh flow. When the token expires, uip login status reports Expired and commands fail until the variable is rotated.
• Server URL is derived from the token. The iss claim in the JWT is authoritative — you do not set UIPATH_URL. This prevents mis-routing when a pipeline sets UIPATH_URL inconsistently with the token.
• The gate matters. If UIPATH_CLI_ENABLE_ENV_AUTH is unset or set to anything other than the literal string true, the file-based flow is used. Misspelling the gate silently falls back — check with uip login status.
• Missing values fail explicitly. If any required variable is empty, uip returns a clear error naming the offending variable, not a generic "not authenticated".

Example GitHub Actions step using env-var auth:

- name: Run uip against Orchestrator
  env:
    UIPATH_CLI_ENABLE_ENV_AUTH: "true"
    UIPATH_CLI_AUTH_TOKEN: ${{ secrets.UIPATH_TOKEN }}
    UIPATH_CLI_ORGANIZATION_NAME: contoso
    UIPATH_CLI_ORGANIZATION_ID: ${{ secrets.UIPATH_ORG_ID }}
    UIPATH_CLI_TENANT_NAME: Default
    UIPATH_CLI_TENANT_ID: ${{ secrets.UIPATH_TENANT_ID }}
  run: uip or folders list --output json

注销

uip logout                         # clear the default credentials folder
uip logout --file /path/to/creds   # clear a non-default credentials folder

logout clears the stored session inside .uipath/. On the env-var flow there is nothing to remove — unset the variables.

故障排除

❌ Not logged in

Either no .uipath/ folder was found on the walk-up chain, or the stored session is unreadable. Run uip login (or set the env-var flow) and retry.

Token expired

Interactive and External App sessions refresh automatically when near expiry. If you see Expired, the refresh token itself expired or was revoked — re-run uip login. For env-var auth, rotate UIPATH_CLI_AUTH_TOKEN.

Multiple org members, wrong org picked

Pass --organization <logical-name> on uip login to bypass the org picker, or uip login tenant list after the fact to see what the session is actually bound to.

Corporate proxy blocks the browser callback

The interactive flow opens a local callback port on 127.0.0.1. Most proxies leave loopback alone, but some aggressive setups block it. Work around by using Flow 2 (External App) or Flow 3 (env-var auth) — both avoid the browser callback entirely.

另请参阅

• Installing UiPath CLI — one-time setup before authentication.
• Configuration — environment variables and flag precedence.
• Sessions and credentials — on-disk layout of the credentials folder.
• uip login reference, uip logout reference.