# Login

URL: https://developers.uidu.org/docs/tools/cli/login

> Authenticate the uidu CLI via the OAuth browser flow (Authorization Code + PKCE), with a password-grant fallback for CI and AI agents.

`uidu login` obtains an account **Bearer token** (needed for authoring) and stores it in
`~/.uidu/config.json`. Two flows are supported.

## Browser flow (default) — Authorization Code + PKCE

```bash
uidu login --workspace your-workspace
```

This opens your browser to sign in (the standard native-app flow, like `gh` or `vercel`):

1. the CLI starts a loopback server on `http://localhost:4123/callback` (override with `--port`);
2. your browser signs in against the uidu identity provider;
3. it redirects back to the loopback with an authorization `code`;
4. the CLI exchanges the code (with a PKCE verifier — no client secret) for a token.

<Callout type="info" title="localhost is your machine">
  The `localhost` redirect is the CLI listening on your own computer — the auth server only tells
  the browser where to go. This is RFC 8252 (OAuth for Native Apps); the same shared public client
  is used for everyone.
</Callout>

On a remote/SSH session (no browser), add `--no-browser` to print the URL instead of opening it
(the loopback still receives the redirect).

## Non-interactive (CI / AI agents)

When there's no browser, use the password grant:

```bash
UIDU_PASSWORD=… uidu login --email you@uidu.org --password-grant
```

Credentials come from `--email` + `UIDU_PASSWORD` (the password is never a flag). This is the
path AI agents and CI pipelines use.

## `whoami` / `logout`

```bash
uidu whoami --json   # workspace, account, token presence + expiry
uidu logout          # clears ~/.uidu/config.json
```

<Callout type="warn" title="Tokens are short-lived">
  Access tokens currently expire after \~2h and there is no refresh token — re-run `uidu login`
  when `whoami` reports `tokenExpired: true`.
</Callout>

## Self-hosting note

`login` targets the shared uidu identity provider by default. Self-hosted deployments need a
public OAuth client registered on their provider (with the `http://localhost:4123/callback`
redirect) and PKCE enabled; point the CLI at it with `--client-id` / `UIDU_CLIENT_ID` and
`--oauth-base` / `UIDU_OAUTH_BASE`.