> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heylua.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# lua auth

> Sign in with email, save an API key, show the stored key, sign out, and manage the devices signed in as you

`lua auth` manages the credential every other command uses. It changes nothing on the agent; it changes which account, and which access, the CLI acts with.

*Verified against lua-cli 3.33.0.*

## Synopsis

```bash theme={null}
lua auth configure [--api-key <key> | --email <email> [--otp <code>]]
lua auth key [--force]
lua auth logout [--all] [--force]
lua auth sessions [--json]
lua auth sessions revoke <sessionId>
```

## Description

`configure` stores one of two credential kinds. Email sign-in creates a renewable [user session](/concepts/credentials): a six-digit code is sent to the address, and the resulting user session is saved under `~/.lua-cli/sessions/` and refreshed automatically. It follows your current access, so joining an organization or creating an agent in the admin dashboard needs no new sign-in. `--api-key` validates an existing [API key](/concepts/credentials) against the platform and saves it to `~/.lua-cli/credentials` with mode `0600`. Saving one kind removes the other, so a machine holds either a user session or a key. Both files hold the secret in plain text; the owner-only permission is the protection.

Commands resolve the credential in this order: `LUA_API_KEY` from the shell or `./.env`, then the saved user session, then the credentials file. When `LUA_API_KEY` is set, `configure` warns that it masks the credential it saved.

The platform classifies a credential when it is used:

| Credential | Form | What it can do |
| - | - | - |
| User session | email and code | Everything your account can, including `lua init --agent-name` and `--from-agent-id` |
| Legacy key | `api_` followed by a hex string | Acts as your user; can create and duplicate agents |
| Scoped key | `api_<uuid>.<secret>` | Acts as a key principal with the roles it was granted; cannot create or duplicate agents, so those `lua init` modes exit 10 |

`key` prints the stored API key, or `LUA_API_KEY` when it is set, after a confirmation. With a user session it prints `You are signed in with a renewable session. No API key is stored.` and exits 0.

`logout` removes the local user session and credentials file and ends this device's user session on the platform; `--all` ends every user session of your account. A saved API key is removed only locally and stays valid until you revoke it in the admin dashboard. When the platform cannot confirm the sign-out the CLI warns `Local session removed, but Lua could not confirm the sign-out on its side.`

`sessions` lists the devices and apps signed in as you, one user session each, with its id, app and version, sign-in method, and last-seen time. `sessions revoke <sessionId>` signs one of them out.

## Arguments

| Argument | Values | Description |
| - | - | - |
| subcommand | `configure`, `key`, `logout`, `sessions` | Required; `lua auth` alone prints help |
| `sessionId` | an id from `lua auth sessions` | Required by `sessions revoke` |

## Options

| Option | Description | Default |
| - | - | - |
| `--api-key <key>` | `configure`: validate and save this key without prompting | prompt |
| `--email <email>` | `configure`: send a sign-in code to this address (step 1) | prompt |
| `--otp <code>` | `configure`: verify the six-digit code for `--email` and save the user session (step 2) | — |
| `--force` | `key`, `logout`: skip the confirmation prompt | prompt |
| `--all` | `logout`: sign out everywhere | this device |
| `--json` | `sessions`: print the list as JSON | text list |

## Examples

Sign in interactively and choose email or API key at the prompt:

```bash theme={null}
lua auth configure
```

Sign in with email from a script in two steps; the first step prints the second command to run:

```bash theme={null}
lua auth configure --email user@example.com
```

```text Output theme={null}
✅ OTP sent successfully!

📬 Check your email, then run:
   lua auth configure --email user@example.com --otp <code>
```

```bash theme={null}
lua auth configure --email user@example.com --otp 123456
```

`--ci` does not stop the prompts of `configure`, `key`, or `logout`; pass `--api-key` or `--email`, and `--force` for `key` and `logout`.

Save a key on a build machine without prompts:

```bash theme={null}
lua auth configure --api-key "$LUA_CI_KEY" --ci
```

In CI you can skip `configure` and export `LUA_API_KEY` instead; it takes precedence over anything saved.

Print the stored key for a secret manager, then sign this device out:

```bash theme={null}
lua auth key --force
lua auth logout --force
```

Review the signed-in devices and sign one out:

```bash theme={null}
lua auth sessions --json
lua auth sessions revoke <sessionId>
```

## Exit codes

| Code | When |
| - | - |
| `0` | Success; `key` with no stored key; a declined confirmation |
| `1` | Invalid email, a code that is not six digits, `Invalid OTP`, or a server that does not offer per-device sessions |
| `3` | `sessions revoke` with an unknown id |
| `9` | The key failed validation; no credential for `sessions` |
| `10` | `sessions revoke` when per-device sign-out is not enabled for the account |
| `11` | The authentication service or the network is unavailable |

## See also

* [Credentials](/concepts/credentials) — user sessions, legacy and scoped keys, roles
* [Environment variables](/reference/cli/environment-variables) — `LUA_API_KEY`, `LUA_AUTH_URL`
* [Automate releases in CI](/ship/ci-and-automation)
* [`lua init`](/reference/cli/init)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.