@uipath/cli

UiPath CLI (uip)

A command-line interface tool for interacting with UiPath Cloud services. The CLI provides authentication, session management, and a plugin system for extending functionality with additional tools.

Installation

Using npm

npm install -g @uipath/cli

Using bun

bun install -g @uipath/cli

After installation, the uip command will be available globally.

Quick Start

• Login to UiPath Cloud

  uip login
  

• Check your login status

  uip login status
  

• View available commands

  uip --help
  

Commands

Authentication

uip login

Authenticate with UiPath Cloud using interactive OAuth login.

Options:

• -f, --file <folder> - Path to credentials folder (default: .uipath)
• --authority <url> - Custom authority URL
• --client-id <id> - Custom Client ID
• -s, --scope <scopes> - Custom scopes (space separated)
• -t, --tenant <name> - Tenant name (non-interactive mode)
• --interactive - Force interactive tenant selection
• --no-interactive - Disable interactive prompts

Examples:

# Basic interactive login
uip login

# Login with custom credentials folder
uip login -f /path/to/my-folder

# Login with specific tenant
uip login -t my-tenant-name

# Disable tenant picker prompts
uip login --no-interactive

Authentication exit-code contract:

Authentication commands reserve exit code 2 for AuthenticationError results where the CLI cannot produce or find a usable authenticated session. This includes failed uip login credential/token exchange, login refresh failures, expired sessions, and missing credentials. Exit code 1 is used for non-authentication failures such as bad host configuration, filesystem problems, or tenant-selection/config errors. Exit code 3 is used by login refresh for invalid --login-validity values.

uip login status

Display current login status and session information.

Options:

• -f, --file <folder> - Path to credentials folder (default: .uipath)

Example:

uip login status

Output:

✅ Logged in
   Organization ID: abc123...
   Base URL: https://cloud.uipath.com

uip login refresh

Refresh the access token proactively and emit a machine-readable session payload — access token, organization/tenant identity, and expiration — in a single call. Programmatic consumers (e.g. the Flow VSCode extension) use this to guarantee the returned token will still be valid for the next N minutes.

uip login status, by contrast, is a status report: it only rotates tokens incidentally when the stored access token is already past its expiry (via the auth layer's auto-refresh path) and never performs proactive refresh — so the token it returns may be about to expire.

Options:

• --login-validity <minutes> – Refresh only if the current access token expires within this many minutes. Default 5. Pass 0 to skip proactive refresh and rotate only when the token is already past its expiry. Range: 0–525600 (1 year). Invalid values exit 3 (ValidationError).

Example:

# Machine-consumption (access token emitted)
uip login refresh --output json

# Require at least 10 minutes of validity on the returned token
uip login refresh --login-validity 10 --output json

Output (--output json):

{
  "Result": "Success",
  "Code": "LoginRefresh",
  "Data": {
    "Status": "Logged in",
    "Organization": "my-org",
    "Tenant": "DefaultTenant",
    "Expiration Date": "2026-04-24T18:00:00.000Z",
    "BaseUrl": "https://cloud.uipath.com",
    "OrganizationId": "bc2ddac5-...",
    "OrganizationName": "my-org",
    "TenantId": "a1b2c3d4-...",
    "TenantName": "DefaultTenant",
    "AccessToken": "<jwt>"
  }
}

Refresh-token ownership:

The CLI is the sole owner of the refresh token — it stays in .uipath/.auth and only the auth layer rotates it. Programmatic consumers should not cache the access token long-term either; instead they call uip login refresh --login-validity N --output json whenever they need a fresh token. This avoids the rotation race that would otherwise let one party invalidate the other party's stored refresh token.

Security posture for AccessToken:

The access token is emitted only when the active format is json and at least one of the following is true:

• --output was explicitly passed on the command line (the user asked for machine output), or
• Stdout is not attached to an interactive terminal (pipe, redirect, subprocess).

Because --output json is the hard default regardless of TTY, gating on format alone would mean a bare uip login refresh in a shell dumps the token on-screen. Requiring either an explicit --output flag or a non-TTY stdout keeps the token reserved for deliberate machine-consumption paths: Flow VSCode extension spawning uip login refresh --output json, CI pipelines writing to a file, or uip login refresh | cat. Table / yaml / plain renderings never include the token in any circumstance. This preserves the sensitive-field filter posture from #752.

Success discriminator (Data.Code):

Code	Meaning
LoginRefresh	Clean success. The returned AccessToken is valid AND the rotated pair has been persisted — the next invocation will use the new tokens cleanly.
LoginRefreshPartial	The refresh rotated at the identity server but the new pair could not be persisted to .uipath/.auth (permission denied, disk full, etc.). The returned AccessToken is valid for the current call, but the next invocation will fail until the disk state is repaired. Data.Hint carries the underlying filesystem error.

Programmatic consumers should switch on Code rather than pattern-matching Hint. Exit code is 0 in both success flavours — the partial case still yielded a usable token for this call.

Exit codes:

Code	Result	When
0	Success	A valid access token is in the response (Code is either LoginRefresh or LoginRefreshPartial)
2	AuthenticationError	The CLI cannot produce a valid token — refresh failed, not logged in, or credentials file unreadable
3	ValidationError	Bad --login-validity value

Environment-variable authentication (CI/CD)

For non-interactive environments such as CI/CD pipelines, containers, or scheduled jobs, the CLI can source credentials directly from environment variables — bypassing the interactive login flow and the on-disk .uipath/.auth file entirely.

Set UIPATH_CLI_ENABLE_ENV_AUTH=true to opt in, then provide the following variables:

Variable	Description
UIPATH_CLI_AUTH_TOKEN	Access token (JWT). The server URL is derived from its iss claim.
UIPATH_CLI_ORGANIZATION_NAME	Organization slug
UIPATH_CLI_ORGANIZATION_ID	Organization UUID
UIPATH_CLI_TENANT_NAME	Tenant slug
UIPATH_CLI_TENANT_ID	Tenant UUID

Example (GitHub Actions):

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 }}

Notes:

• The access token is treated as opaque — the caller is responsible for its freshness. There is no refresh flow: if the token is expired, uip login status reports Expired and commands fail until the env var is rotated.
• The server URL is not a separate env var — it is derived from the token's iss claim, which is the authoritative source for the identity server that minted the token. This prevents mis-routing when a user sets UIPATH_URL inconsistently with the token.
• When UIPATH_CLI_ENABLE_ENV_AUTH is unset (or any value other than the literal string true), the file-based auth flow is used — no behavior change for existing users.
• Missing or empty required variables produce a clear error naming the offending variable rather than a generic "not authenticated".

Robot-credentials-only authentication (Studio Desktop)

For consumers that spawn uip from a process whose user is already signed in to the local UiPath Robot/Assistant (e.g. Studio Desktop's Publish Solution feature), the CLI can be forced to authenticate via the Robot IPC fallback and bypass ~/.uipath/.auth entirely.

Set UIPATH_CLI_ENFORCE_ROBOT_AUTH=true on the spawned uip child process. When set:

• The Robot fallback (introduced in #1055) is consulted first. If it yields a session, the CLI returns Logged in with Source: robot — no on-disk credentials are read or written.
• If the Robot is not running, not signed in, or the IPC handshake times out, the CLI does not fall back to ~/.uipath/.auth or to env-var auth. The reported login status is Not logged in, with a hint that names the env var and points at the Assistant.
  • uip login status itself surfaces this as Status: "Not logged in" in its JSON payload and exits 0 (it's a diagnostic command and does not fail on missing auth).
  • Any auth-requiring command (e.g. uip solution publish) fails with AuthenticationError and exits 2, surfacing the same hint.
• UIPATH_CLI_ENFORCE_ROBOT_AUTH and UIPATH_CLI_ENABLE_ENV_AUTH are mutually exclusive. Setting both produces an explicit error rather than silently picking one.
• UIPATH_URL's "skip Robot fallback" behavior is overridden — when UIPATH_CLI_ENFORCE_ROBOT_AUTH=true, the Robot path is taken regardless of UIPATH_URL.

This flag is intended as a per-process opt-in set programmatically on the spawned uip child only (e.g. via ProcessStartInfo.EnvironmentVariables in .NET). Setting it at User or Machine scope would force every CLI invocation on the host into Robot-only auth — not the intended use.

Tool Management

The CLI supports a plugin system that allows you to extend functionality by installing additional tools.

uip tools list

List all currently installed tools.

Example:

uip tools list

Output:

🔧 Installed Tools:

  ✓ automation-tool v1.0.0
    Command: uip automation
    Automate workflows and processes

uip tools search [query]

Search for available tools in the configured registry.

Example:

# Search for tools
uip tools search automation

# Interactive search (prompts for query)
uip tools search

Output:

🔍 Searching for 'automation'...

📦 Found: @uipath/automation-tool (v1.0.0)
   Description: Automate workflows and processes
   Publisher: uipath

To install: uip tools install <package-name>

uip tools install <package-name>

Install a tool from the registry.

Example:

uip tools install @uipath/automation-tool

Output:

📦 Installing '@uipath/automation-tool'...
✅ Successfully installed @uipath/automation-tool

Getting Help

• View all available commands: uip --help
• View help for a specific command: uip <command> --help
• View version: uip --version

Proxy Support

The CLI respects standard HTTP proxy environment variables. This is useful in corporate environments where internet access goes through a proxy server.

Supported environment variables:

Variable	Description
HTTP_PROXY / http_proxy	Proxy for HTTP requests
HTTPS_PROXY / https_proxy	Proxy for HTTPS requests
NO_PROXY / no_proxy	Comma-separated list of hosts that bypass the proxy

Examples:

# Linux / macOS
export HTTPS_PROXY=http://proxy.example.com:8080
uip login

# Windows (cmd)
set HTTPS_PROXY=http://proxy.example.com:8080
uip login

# Windows (PowerShell)
$env:HTTPS_PROXY = "http://proxy.example.com:8080"
uip login

# With authentication
export HTTPS_PROXY=http://user:[e-mail]:8080
uip login

# Bypass proxy for specific hosts
export HTTPS_PROXY=http://proxy.example.com:8080
export NO_PROXY=localhost,127.0.0.1,.internal.corp
uip login

Note: When running under Bun, proxy support is built-in. When running under Node.js, the CLI uses Node's built-in undici module to enable proxy-aware fetch().

Troubleshooting

Not logged in error

If you see ❌ Not logged in, run uip login to authenticate.

Tool not found after installation

After installing a new tool with uip tools install, you may need to restart your terminal or CLI session for the tool to become available.

Authentication issues

If you're having trouble logging in, try:

• Check your internet connection
• Verify your credentials
• Run uip login in a terminal to select a tenant, or pass --tenant <name>

For Developers

Development Setup

To work on the CLI locally:

# Install dependencies
bun install

# Run in development mode
bun run index.ts

# Build the project
bun run build

# Run tests
bun test

Contributing

For bug reports and feature requests, please visit the GitHub repository.