---
title: "CLI authentication"
description: "Sign the lookio CLI in with a browser, a device code or an API key, choose scopes, use several profiles and know where credentials are stored."
canonical: "https://lookio.app/docs/developers/cli/authentication"
updated: "2026-11-08"
---

# CLI authentication

The CLI uses the same two credentials as the API: a personal connection (OAuth) and a workspace API key. See [Authentication](/docs/developers/authentication).

## Sign in

**Browser**

```bash
lookio auth login
```

The CLI opens Lookio. You approve the workspace and the permissions. The CLI stores the token. Use this for a person: the connection has your identity and keeps your conversations.

**Remote machine**

```bash
lookio auth login --device
```

Use it over SSH, or in a container without a browser. The CLI prints an address and a code. Open the address on any device and type the code.

**API key**

```bash
LOOKIO_API_KEY="sk_live_..." lookio auth login
```

Use a workspace key for CI or a server. `--key` also works, but your shell history then keeps the key. Use the environment variable. If a key leaks, rotate it.

The CLI tests the credential with `GET /v1/account` before it stores it.

### Which permissions the CLI asks for

A browser or device login asks for the **Editor** set: `account:read`, `usage:read`, `resources:read`, `resources:write`, `assistants:read`, `assistants:write` and `query`. It does not ask for `resources:delete`, `assistants:delete` or `admin`, so this login deletes nothing.

To ask for other scopes, pass `--scope`:

```bash
lookio auth login --scope account:read,resources:read,resources:delete,assistants:delete,admin
```

You get only what your role allows. `admin` needs a workspace admin. `lookio members` and `lookio tags rename` need it.

## Check and sign out

```bash
lookio auth status      # workspace, plan, credential kind, scopes and when the token expires
lookio auth logout      # forgets the credential and revokes it on the server when possible
```

If `LOOKIO_API_KEY` is still set, the CLI keeps using it after you sign out. `logout` warns you.

## Credential order

The CLI uses the first credential it finds, in this order:

```mermaid title="Which credential the CLI uses"
flowchart LR
  E{"LOOKIO_API_KEY set?"} -- "yes" --> K["Use the API key"]
  E -- "no" --> KC{"Keychain entry?"}
  KC -- "yes" --> T["Use the stored token"]
  KC -- "no" --> F{"config.json?"}
  F -- "yes" --> T
  F -- "no" --> L["lookio auth login"]
```

1. The `LOOKIO_API_KEY` environment variable. It always wins, so CI can replace an old login.
2. The OS keychain.
3. `~/.config/lookio/config.json`, with mode `0600`, when there is no keychain (a container, a Linux server). Set `LOOKIO_NO_KEYCHAIN` to skip the keychain.

- `~/.config/`
  - `lookio/`
    - `config.json`

`XDG_CONFIG_HOME` moves the config directory.

The CLI renews the access token with its refresh token. If the connection was revoked, the CLI forgets it and asks you to sign in again.

## Profiles

A profile is a named stored credential, for example one per workspace.

```bash
lookio --profile acme auth login
lookio --profile acme account
LOOKIO_PROFILE=acme lookio resources list
```

## Environment variables

| Variable             | Purpose                                                                   |
| -------------------- | ------------------------------------------------------------------------- |
| `LOOKIO_API_KEY`     | An API key. Overrides any stored credential.                              |
| `LOOKIO_PROFILE`     | The profile to use. Same as `--profile`.                                  |
| `LOOKIO_API_URL`     | The API base URL. Defaults to `https://api.lookio.app/v1`.                |
| `LOOKIO_MCP_URL`     | The MCP host, used by `lookio mcp`. Defaults to `https://mcp.lookio.app`. |
| `LOOKIO_AUTH_URL`    | The authorization server, when it is not the API host.                    |
| `LOOKIO_NO_TUI`      | Any value forces JSON output.                                             |
| `LOOKIO_NO_KEYCHAIN` | Any value skips the OS keychain.                                          |
| `NO_COLOR`           | Disables colour only. It does not change the format.                      |