Skip to main content
lua is the command-line interface for building, testing, and releasing Lua agents. This page covers what applies to every command; each command has its own reference page, listed at the end. Verified against lua-cli 3.33.0.

​
Install

lua-cli requires Node.js 16 or later. Install it globally with npm.
The package installs three identical binaries: lua, heylua, and lua-ai. Use heylua or lua-ai when another tool already owns the lua name. Confirm the version:
Output
lua update upgrades a global npm install to the latest version. The CLI also checks the npm registry once every 24 hours and, when a newer version exists, prints a boxed Update available notice on stderr after the command finishes.

​
Global flags

Every command that changes something has a non-interactive form built from a type argument, --name, --set-version, and --force. In automation add --ci so a missing flag fails the job instead of waiting on a prompt. --ci stops only the prompts that check for it. These prompts appear even under --ci and the command waits on stdin, so pass the flags that avoid them or keep the command out of scripts:
  • lua chat without -e and -m: the environment question; without -m: the chat loop.
  • lua env without an environment; lua env <environment> without --list, -k, or --delete: the variable menu.
  • lua logs without --type, --name, --user-id, or --json: the log browser.
  • lua init without --agent-id, --agent-name, or --from-agent-id: the mode, organization, and agent questions.
  • lua test skill without --name: the tool picker.
  • lua deploy <type> without --set-version, or without --force: the version picker and the confirmation. The type menu and the entity picker do exit 1.
  • lua models set without --model: the model picker.
  • lua pull, lua source rollback, lua auth key, and lua auth logout without --force.
  • lua auth configure without --api-key or --email.
  • lua channels without an action, and every channel creation flow.
Every other prompt, including those of lua push, lua skills, lua persona, lua governance, lua devices, lua features, lua sync, lua workflows, and lua test workflow, exits 1 under --ci; lua version create and lua version delete skip theirs and proceed. Scripted forms of the release commands are on Automate releases in CI.

​
Credentials

Commands that call the platform resolve one credential, in this order, and stop at the first match:
  1. LUA_API_KEY from the shell environment or from a .env file in the current directory.
  2. The user session created by lua auth configure with email, stored under ~/.lua-cli/sessions/.
  3. The API key saved by lua auth configure --api-key in ~/.lua-cli/credentials.
With no credential the command exits 9 with No Lua CLI authentication found. Run `lua auth configure` or set LUA_API_KEY. A set LUA_API_KEY masks a saved user session, and lua auth configure warns when that happens. See lua auth.

​
Local files

lua status --json reports the config directory, the API base URL, and which credential source is active.

​
Errors

A failing command prints one typed line on stderr, ✖ <class>: <message>, a 💡 hint when there is one, and exits with a code that names the class: 0 ok, 1 error, 2 usage, 3 not found, 9 auth, 10 forbidden, 11 unavailable, 12 provider rejected. lua workflows adds 4–8 for run outcomes. The full table, the --json error envelope, and the common messages are on Errors and exit codes. Success hints (✨ Tip: run …) are silenced with LUA_NO_HINTS=1; see Environment variables.

​
Shell completion

lua completion bash, lua completion zsh, and lua completion fish print a completion script for that shell. Append it to your shell profile. Details are on Utilities.

​
Commands

​
See also