Authentication

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

configure

Set up authentication

key

Display stored key

logout

Remove credentials

lua auth configure

Set up API key authentication.

lua auth configure

Authentication Methods

Email (Recommended)
API Key

Email OTP Authentication

Choose “Email” when prompted
Enter your email address
Check email for 6-digit code
Enter the OTP code
API key automatically generated and saved

$ lua auth configure
? Choose authentication method: Email
? Enter your email address: [email protected]
📧 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

Existing API KeyUse if you already have an API key:

Choose “API Key” when prompted
Enter your existing API key
Key is validated with server
Key is saved securely

$ 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

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.

Never commit API keys to version control or share them publicly!

Environment Variable Authentication

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

export LUA_API_KEY=your-api-key

The environment variable always takes priority over the credentials file.

Local terminal
.env file
Dockerfile
GitHub Actions

export LUA_API_KEY=your-api-key
lua push

Add to ~/.zshrc or ~/.bashrc for persistence.

Create a .env file in your project root:

LUA_API_KEY=your-api-key

The CLI loads .env automatically. Add .env to .gitignore.

FROM node:22-slim
ENV LUA_API_KEY=your-api-key
RUN npm install -g lua-cli

Or pass at runtime:

docker run -e LUA_API_KEY=your-api-key my-image lua push

- name: Deploy
  env:
    LUA_API_KEY: ${{ secrets.LUA_API_KEY }}
  run: lua push all --force

Add LUA_API_KEY to your repository secrets.

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.

lua auth key

Security Confirmation

For security, you must confirm before displaying the key:

$ 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):

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.

lua auth logout

Confirmation Required

$ 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:

lua auth logout --force

What Happens

Credentials File Removed

~/.lua-cli/credentials is deleted

CLI Access Lost

You’ll need to run lua auth configure or set LUA_API_KEY to use the CLI again

Key Still Valid on Server

The key is NOT invalidated on the server — it just removes the local copy

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.

Troubleshooting

No API key found

Error: No API key found.Solution: Authenticate using one of:

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

OTP not received

Problem: Didn’t receive OTP emailSolutions:

Check spam/junk folder
Wait a few minutes (can take up to 5 min)
Try again with lua auth configure
Use API Key method instead

Invalid OTP

Error: ❌ Invalid OTP codeSolutions:

Double-check the code from email
OTP expires after 10 minutes
Request new OTP by running command again

API key validation failed

Error: ❌ Authentication failedSolutions:

Verify you copied the complete key
Check key hasn’t been revoked
Ensure no extra spaces
Generate new key via email method

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:

lua auth configure

Or set the environment variable directly:

export LUA_API_KEY=your-api-key

Best Practices

Use Email Authentication for Local Dev

Recommended for individual developers — automatic key management, no manual key to remember.

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.

# GitHub Actions
env:
  LUA_API_KEY: ${{ secrets.LUA_API_KEY }}

# Docker
docker run -e LUA_API_KEY=your-key my-image lua push

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

Disable Telemetry in CI

LUA_TELEMETRY=false lua push

Or set LUA_TELEMETRY=false in your CI environment variables.

Next Steps

Initialize Project

Create your first skill after authentication

Deploy Commands

Deploy primitives to production

Getting Started

Core Concepts

CLI Commands

API Reference

Template & Examples

Overview

Commands

configure

key

logout

lua auth configure

Authentication Methods

Where Credentials Are Stored

Environment Variable Authentication

Key Resolution Order

lua auth key

Security Confirmation

Use Cases

lua auth logout

Confirmation Required

What Happens

Troubleshooting

Best Practices

Next Steps

Initialize Project

Deploy Commands

Getting Started

Core Concepts

CLI Commands

API Reference

Template & Examples

Documentation Index

​Overview

​Commands

configure

key

logout

​lua auth configure

​Authentication Methods

​Where Credentials Are Stored

​Environment Variable Authentication

​Key Resolution Order

​lua auth key

​Security Confirmation

​Use Cases

​lua auth logout

​Confirmation Required

​What Happens

​Troubleshooting

​Best Practices

​Next Steps

Initialize Project

Deploy Commands

Overview

Commands

lua auth configure

Authentication Methods

Where Credentials Are Stored

Environment Variable Authentication

Key Resolution Order

lua auth key

Security Confirmation

Use Cases

lua auth logout

Confirmation Required

What Happens

Troubleshooting

Best Practices

Next Steps