# uip login

> Syntax and options for `uip login`, which authenticates UiPath CLI against UiPath Cloud and persists the session locally.

`uip login` authenticates the CLI against UiPath Cloud and persists the resulting session inside a local `.uipath/` folder. On success, the CLI has an access token and a selected tenant; tools run by subsequent commands pick these up automatically. See [Authentication](./authentication.md) for the credential model and [Sessions and credentials](./concepts-sessions.md) for where the folder lives.

For checking status, see [`uip login status`](./uip-login-status.md). To tear down a session, see [`uip logout`](./uip-logout.md).

## Synopsis

```
uip login [--interactive] [--tenant <name>] [--organization <name>]
         [--authority <url>] [--client-id <id>] [--client-secret <secret>]
         [--scope <scopes>] [-f <folder>]
uip login tenant list [-f <folder>]
uip login tenant set <name> [-f <folder>]
```

All `uip login` subcommands honor the [global options](./global-options.md) (`--output`, `--output-filter`, `--log-level`, `--log-file`). Exit codes follow the [standard contract](./exit-codes.md).

## uip login

Authenticates interactively through the browser, or non-interactively using External Application client credentials.

### Arguments

None.

### Options

- `-f, --file <folder>` — Path to a credentials folder. The session is persisted inside `<folder>`. Without it, the CLI uses the default location (see [Sessions and credentials](./concepts-sessions.md)).
- `--authority <url>` — Custom authority URL. Use for non-default clouds.
- `--client-id <id>` — Client ID or Application ID for a UiPath External Application. Accepts `env.NAME` to read from an environment variable.
- `--client-secret <secret>` — Client secret for a confidential External Application. Accepts `env.NAME` to read from an environment variable.
- `-s, --scope <scopes>` — Space-separated scopes (for example, `"OR.Folders OR.Jobs"`). Use with External Application credentials.
- `-t, --tenant <name>` — Tenant name (non-interactive mode). If omitted, pair with `--interactive`.
- `--organization <name>` — Organization logical name, pre-selected during browser login. Bypasses the org picker when your user is in multiple organizations.
- `--it, --interactive` — After authentication, prompt interactively to select a tenant from the list returned by the cloud.

### Credential modes

- **Interactive / user credentials** — run `uip login` (optionally with `--interactive`, `--tenant`, or `--organization`). The browser flow completes on the UiPath Cloud authority; the resulting tokens are persisted inside the credentials folder.
- **External Application (non-interactive)** — pass `--client-id`, `--client-secret`, and `--scope`, typically with `--tenant`. Suitable for CI runners. Read the secret from an environment variable with `--client-secret env.UIPATH_CLIENT_SECRET` to keep it out of your shell history.

### Examples

```bash
# Browser-based interactive login, picks tenant at the end
uip login --interactive

# Log directly into a known org + tenant (no browser picker)
uip login --organization my-org --tenant DefaultTenant

# External Application with secret from environment variable
uip login \
  --client-id "00000000-0000-0000-0000-000000000001" \
  --client-secret env.UIPATH_CLIENT_SECRET \
  --scope "OR.Folders OR.Jobs" \
  --tenant DefaultTenant

# Custom credentials folder (useful for scoping per-project sessions)
uip login --interactive -f ./.uipath
```

### Data shape (`--output json`)

```json
{
  "Code": "Authenticated",
  "Data": {
    "Status": "Logged in",
    "Organization": "my-org",
    "Tenant": "DefaultTenant"
  }
}
```

### Failure modes

- Missing tenant after a non-interactive login raises a `ConfigError` with `Message: "No tenant selected"` and instructs you to re-run with `--tenant <name>` or `--interactive`.
- Transport errors and non-2xx responses from the authority surface as `AuthenticationError`, with the original HTTP status in `Context.httpStatus` when available.
- A malformed `env.NAME` reference in `--client-id` / `--client-secret` produces a `ConfigError` before any network call.

## uip login tenant list

List all tenants visible to the authenticated user in the current organization. Requires an active login.

### Arguments

None.

### Options

- `-f, --file <folder>` — Path to the credentials folder. Defaults to the session used by the last `uip login`.

### Example

```bash
uip login tenant list
```

### Data shape (`--output json`)

```json
{
  "Code": "TenantList",
  "Data": [
    {
      "TenantName": "DefaultTenant",
      "TenantId": "a1b2c3d4-0000-0000-0000-000000000001"
    },
    {
      "TenantName": "ProductionTenant",
      "TenantId": "a1b2c3d4-0000-0000-0000-000000000002"
    }
  ]
}
```

If the session is not logged in, the command emits `AuthenticationError` with instructions to run `uip login` first.

## uip login tenant set

Select the active tenant by name. The tenant must exist in the list returned by `login tenant list`; the CLI updates the stored session with the new selection.

### Arguments
- `<name>` *(required)* — Tenant name as returned by `uip login tenant list`.

### Options

- `-f, --file <folder>` — Path to the credentials folder. Defaults to the session used by the last `uip login`.

### Example

```bash
uip login tenant set DefaultTenant
```

### Data shape (`--output json`)

```json
{
  "Code": "TenantSet",
  "Data": {
    "Name": "DefaultTenant",
    "Id": "a1b2c3d4-0000-0000-0000-000000000001"
  }
}
```

### Failure modes

- Unknown tenant name produces `ValidationError` with `Instructions` listing the available tenants, for example `argument should be one of DefaultTenant, ProductionTenant`.
- If the CLI cannot update the stored session, the error is surfaced as `Failure` with a permissions-related hint.

## Related

- [`uip login status`](./uip-login-status.md) — show the current session without refreshing.
- [`uip logout`](./uip-logout.md) — clear the stored session.
- [Authentication](./authentication.md) — user vs External Application flows.
- [Sessions and credentials](./concepts-sessions.md) — how the credentials folder is located and rotated.
- [Configuration](./configuration.md) — precedence of credential sources (env vars, file, flags).