> ## 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.

# Authentication

> Configure API key authentication for Lua CLI

## Overview

Lua CLI requires authentication to access the platform and deploy skills. API keys are resolved from environment variables, a local credentials file, or a `.env` file — no system keychain is required.

## Commands

<CardGroup cols={3}>
  <Card title="configure" icon="key">
    Set up authentication
  </Card>

  <Card title="key" icon="eye">
    Display stored key
  </Card>

  <Card title="logout" icon="right-from-bracket">
    Remove credentials
  </Card>
</CardGroup>

## lua auth configure

Set up API key authentication.

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

### Authentication Methods

<Tabs>
  <Tab title="Email (Recommended)">
    **Email OTP Authentication**

    1. Choose "Email" when prompted
    2. Enter your email address
    3. Check email for 6-digit code
    4. Enter the OTP code
    5. API key automatically generated and saved

    ```bash theme={null}
    $ lua auth configure
    ? Choose authentication method: Email
    ? Enter your email address: you@example.com
    📧 Sending OTP to your email...
    ✅ OTP sent successfully!
    ? Enter the OTP code: 123456
    🔐 Verifying OTP...
    ✅ OTP verified successfully!
    🔑 Generating API key...
    ✅ API key generated and saved securely.
    ```

    **Features:**

    * No existing account needed
    * Automatic key generation
    * Most secure method
    * No manual key management
  </Tab>

  <Tab title="API Key">
    **Existing API Key**

    Use if you already have an API key:

    1. Choose "API Key" when prompted
    2. Enter your existing API key
    3. Key is validated with server
    4. Key is saved securely

    ```bash theme={null}
    $ lua auth configure
    ? Choose authentication method: API Key
    ? Enter your API key: api_abc123def456...
    🔐 Validating API key...
    ✅ API key validated and saved securely.
    ```

    **When to use:**

    * You have an existing API key
    * Setting up on multiple machines
    * Automating CI/CD pipelines
  </Tab>
</Tabs>

### Non-Interactive Authentication

Both methods support fully non-interactive flows for CI, scripts, and AI IDEs:

```bash theme={null}
# Direct API key (one shot)
lua auth configure --api-key "lk_xxx..."

# Email OTP — request a code
lua auth configure --email you@example.com
# (CLI prints "Check your email for a 6-digit code.")

# Email OTP — verify and store
lua auth configure --email you@example.com --otp 123456
```

| Option            | Description                                                                                                  |
| ----------------- | ------------------------------------------------------------------------------------------------------------ |
| `--api-key <key>` | Set API key directly. Best for CI/CD where you already have a key from the dashboard.                        |
| `--email <email>` | Request an OTP to be sent to this email. Step 1 of the OTP flow.                                             |
| `--otp <code>`    | Verify the 6-digit code from email and generate an API key. Step 2 of the OTP flow (combine with `--email`). |

<Note>
  For CI/CD where you can't read email, prefer `--api-key` (or set `LUA_API_KEY` directly — see below). The OTP flow is intended for first-time setup on developer machines, including AI IDEs that can poll for completion.
</Note>

### Where Credentials Are Stored

Credentials are stored in a plain-text file with owner-only permissions (`0600`):

```
~/.lua-cli/credentials
```

This file is created automatically by `lua auth configure`. It is never committed to version control and is only readable by your user account — the same security model used by tools like `kubectl`, `gh`, and `aws configure`.

<Warning>
  Never commit API keys to version control or share them publicly!
</Warning>

## Environment Variable Authentication

For CI/CD, Docker, and headless servers, set the `LUA_API_KEY` environment variable directly — no credentials file needed:

```bash theme={null}
export LUA_API_KEY=your-api-key
```

The environment variable always takes priority over the credentials file.

<Tabs>
  <Tab title="Local terminal">
    ```bash theme={null}
    export LUA_API_KEY=your-api-key
    lua push
    ```

    Add to `~/.zshrc` or `~/.bashrc` for persistence.
  </Tab>

  <Tab title=".env file">
    Create a `.env` file in your project root:

    ```bash theme={null}
    LUA_API_KEY=your-api-key
    ```

    The CLI loads `.env` automatically. Add `.env` to `.gitignore`.
  </Tab>

  <Tab title="Dockerfile">
    ```dockerfile theme={null}
    FROM node:22-slim
    ENV LUA_API_KEY=your-api-key
    RUN npm install -g lua-cli
    ```

    Or pass at runtime:

    ```bash theme={null}
    docker run -e LUA_API_KEY=your-api-key my-image lua push
    ```
  </Tab>

  <Tab title="GitHub Actions">
    ```yaml theme={null}
    - name: Deploy
      env:
        LUA_API_KEY: ${{ secrets.LUA_API_KEY }}
      run: lua push all --force
    ```

    Add `LUA_API_KEY` to your repository secrets.
  </Tab>
</Tabs>

### Key Resolution Order

The CLI checks sources in this priority order:

| Priority | Source                   | Best for                        |
| -------- | ------------------------ | ------------------------------- |
| 1        | `LUA_API_KEY` env var    | CI/CD, Docker, headless servers |
| 2        | `~/.lua-cli/credentials` | Local development               |
| 3        | `.env` file              | Local development fallback      |

## lua auth key

Display your stored API key.

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

### Security Confirmation

For security, you must confirm before displaying the key:

```bash theme={null}
$ lua auth key
? This will display your API key. Are you sure you want to continue? Yes
🔑 Your API key:
api_abc123def456...
```

Use `--force` to skip the confirmation prompt (useful in scripts):

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

### Use Cases

* **Copying to another machine**: Get key to set up elsewhere
* **CI/CD configuration**: Copy key for automated deployments
* **Verification**: Confirm which key is currently configured

## lua auth logout

Delete the stored credentials file.

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

### Confirmation Required

```bash theme={null}
$ lua auth logout
? Are you sure you want to delete your API key? This action cannot be undone. Yes
✅ API key deleted successfully.
```

Use `--force` to skip the confirmation:

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

### What Happens

<Steps>
  <Step title="Credentials File Removed">
    `~/.lua-cli/credentials` is deleted
  </Step>

  <Step title="CLI Access Lost">
    You'll need to run `lua auth configure` or set `LUA_API_KEY` to use the CLI again
  </Step>

  <Step title="Key Still Valid on Server">
    The key is NOT invalidated on the server — it just removes the local copy
  </Step>
</Steps>

<Note>
  After logout, the key still works if used elsewhere (e.g. as an env var). To fully revoke access, regenerate a new key from the admin dashboard.
</Note>

## Troubleshooting

<AccordionGroup>
  <Accordion title="No API key found">
    **Error**: `No API key found.`

    **Solution**: Authenticate using one of:

    ```bash theme={null}
    lua auth configure          # Interactive setup (stores in ~/.lua-cli/credentials)
    export LUA_API_KEY=your-key # Environment variable
    echo "LUA_API_KEY=key" >> .env  # .env file
    ```
  </Accordion>

  <Accordion title="OTP not received">
    **Problem**: Didn't receive OTP email

    **Solutions**:

    1. Check spam/junk folder
    2. Wait a few minutes (can take up to 5 min)
    3. Try again with `lua auth configure`
    4. Use API Key method instead
  </Accordion>

  <Accordion title="Invalid OTP">
    **Error**: `❌ Invalid OTP code`

    **Solutions**:

    * Double-check the code from email
    * OTP expires after 10 minutes
    * Request new OTP by running command again
  </Accordion>

  <Accordion title="API key validation failed">
    **Error**: `❌ Authentication failed`

    **Solutions**:

    * Verify you copied the complete key
    * Check key hasn't been revoked
    * Ensure no extra spaces
    * Generate new key via email method
  </Accordion>

  <Accordion title="Upgrading from v3.8.x or earlier">
    Previous versions stored credentials in the OS keychain (via `keytar`). Starting in v3.9.0, credentials are stored in `~/.lua-cli/credentials`.

    **One-time migration step:**

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

    Or set the environment variable directly:

    ```bash theme={null}
    export LUA_API_KEY=your-api-key
    ```
  </Accordion>
</AccordionGroup>

## Best Practices

<AccordionGroup>
  <Accordion title="Use Email Authentication for Local Dev">
    Recommended for individual developers — automatic key management, no manual key to remember.
  </Accordion>

  <Accordion title="Use LUA_API_KEY for CI/CD and Docker">
    Inject the key as an environment variable or secret. No credentials file needed, no native dependencies.

    ```bash theme={null}
    # GitHub Actions
    env:
      LUA_API_KEY: ${{ secrets.LUA_API_KEY }}

    # Docker
    docker run -e LUA_API_KEY=your-key my-image lua push
    ```
  </Accordion>

  <Accordion title="Keep Keys Private">
    * Don't commit `.env` to git (add to `.gitignore`)
    * Don't share in chat or email
    * Use `lua auth logout` when done on shared machines
    * Rotate keys regularly
  </Accordion>

  <Accordion title="Disable Telemetry in CI">
    ```bash theme={null}
    LUA_TELEMETRY=false lua push
    ```

    Or set `LUA_TELEMETRY=false` in your CI environment variables.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Initialize Project" icon="plus" href="/cli/skill-management">
    Create your first skill after authentication
  </Card>

  <Card title="Deploy Commands" icon="rocket" href="/cli/production-command">
    Deploy primitives to production
  </Card>
</CardGroup>