lua runs on your machine and is signed in to your Lua account. Use it when you work from a terminal or an editor; to build from inside Claude Code, install the Claude Code plugin, which wraps the same CLI.
Verified against lua-cli 3.33.0.
Before you begin
- Node.js 16 or later (
node --version) with npm, pnpm, or yarn. - The email address of your Lua account, or an API key created in the admin dashboard.
1
Install the CLI
Install The package also installs
lua-cli globally so the lua command is on your PATH.heylua and lua-ai, identical binaries for machines where another tool owns the lua name. Confirm the version:Output
2
Sign in
lua auth configure asks for a method and stores the result under ~/.lua-cli/.- Email
- API key
Choose Email, enter your address, then enter the six-digit code the CLI emails you. The command ends with In a script, request the code and verify it as two commands:
✅ Signed in as [email protected]. and saves a renewable user session that follows the organizations and agents your account can reach, so you sign in once per machine.3
Verify
lua status reports the CLI version, the credential in use, and whether the server answered; add --json in scripts.Output
Options you may need
Where credentials live
Every command resolves a credential in this order and stops at the first match:LUA_API_KEY in the environment (a .env in the current directory is loaded into it first), the user session for the active environment in ~/.lua-cli/sessions/, then the key in ~/.lua-cli/credentials. Both files are owner-only and hold the secret in plaintext. lua auth logout ends the user session on this device; lua auth logout --all ends it on every device and app.
If it isn’t working
Exit 9: No Lua CLI authentication found, or Your Lua CLI session was signed out
Exit 9: No Lua CLI authentication found, or Your Lua CLI session was signed out
No credential was found, or the user session was revoked (
lua auth logout --all, or a sign-out from the admin dashboard, desktop, or mobile app). Run lua auth configure again, or export LUA_API_KEY.EACCES during npm install -g
EACCES during npm install -g
The global npm directory is not writable by your user. Follow npm’s guide, Resolving EACCES permissions errors, rather than installing with
sudo.EBADENGINE during npm install -g
EBADENGINE during npm install -g
The package declares Node 16 or later and your Node is older. Install a current LTS release and run the install again.
Next steps
Quickstart
Create an agent, add one tool, and release it.
Project structure
What
lua init writes and which files you edit.lua auth reference
Every flag of
configure, logout, sessions, and key.About credentials
User sessions, scoped keys, legacy keys, and scopes.