> ## 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. # CLI overview > Install lua-cli, global flags, credential precedence, local files, the error format, and an index of every command `lua` is the command-line interface for building, testing, and releasing Lua [agents](/concepts/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. ```bash theme={null} npm install -g lua-cli ``` 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: ```bash theme={null} lua --version ``` ```text Output theme={null} 3.33.0 ``` `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 | Flag | Description | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `--ci` | Fail instead of prompting. A command that reaches a question exits 1 with `Interactive prompt required but --ci flag is set`. Accepted before or after the command name. | | `--debug` | Print the stack trace under an error's typed line. Accepted anywhere on the line; same as `LUA_DEBUG=1`. | | `-V`, `--cli-version` | Print the CLI version. Bare `lua --version` also works; the long name leaves `--version ` free for subcommands such as `lua pull`. | | `-h`, `--help` | Print help for the program or one command, for example `lua push --help`. | 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 ` 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 ` 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](/ship/ci-and-automation). ## 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](/concepts/credentials) created by `lua auth configure` with email, stored under `~/.lua-cli/sessions/`. 3. The [API key](/concepts/credentials) 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`](/reference/cli/auth). ## Local files | Path | Contents | | -------------------------------- | --------------------------------------------------------------------------------------- | | `~/.lua-cli/credentials` | API key from `lua auth configure`, mode `0600` | | `~/.lua-cli/sessions/.json` | Renewable user session; one file per API and auth URL pair, named by a hash of the URLs | | `~/.lua-cli/telemetry.json` | Telemetry choice and first-run notice state | | `~/.lua-cli/version-check.json` | Cached npm version check | | `~/.lua-cli/sandbox.json` | Sandbox primitive ids that `lua chat` uses | | `~/.lua-cli/auth.json` | Git provider tokens from `lua git auth` | | `/lua.skill.yaml` | Project state manifest; see [lua.skill.yaml](/reference/cli/lua-skill-yaml) | | `/dist-v2/` | Compiled artifacts and manifest from `lua compile`; gitignored | `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, `✖ : `, 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](/reference/cli/errors-and-exit-codes). Success hints (`✨ Tip: run …`) are silenced with `LUA_NO_HINTS=1`; see [Environment variables](/reference/cli/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](/reference/cli/utilities). ## Commands | Command | Purpose | | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | | [`lua auth`](/reference/cli/auth) | Sign in, save an API key, list and revoke sessions | | [`lua init`](/reference/cli/init) | Create a project and bind it to an agent | | [`lua compile`](/reference/cli/compile) | Bundle the project into `dist-v2/` | | [`lua test`](/reference/cli/test) | Run a tool, webhook, job, processor, or workflow locally | | [`lua push`](/reference/cli/push) | Push a version of a primitive, or stage everything | | [`lua deploy`](/reference/cli/deploy) | Make a pushed version of one primitive live | | [`lua version`](/reference/cli/version) | Create, promote, diff, and roll back agent versions | | [`lua sync`](/reference/cli/sync) | Detect and resolve drift between local code and the server | | [`lua pull`](/reference/cli/pull) | Restore the agent's source into the current directory | | [`lua source`](/reference/cli/source) | List and restore source backup versions | | [`lua git`](/reference/cli/git) | Opt-in git auto-commits and GitHub auto-push | | [`lua status`](/reference/cli/status) | Environment, auth, project, sync state, and updates; alias `lua describe` | | [`lua chat`](/reference/cli/chat) | Talk to the agent in sandbox or production | | [`lua logs`](/reference/cli/logs) | Read execution logs by primitive type | | [`lua env`](/reference/cli/env) | Manage sandbox and production environment variables | | [`lua skills`](/reference/cli/skills) | View, deploy, and delete skills | | [`lua webhooks`](/reference/cli/webhooks) | View, deploy, activate, and subscribe webhooks | | [`lua triggers`](/reference/cli/triggers) | Create and manage trigger URLs | | [`lua jobs`](/reference/cli/jobs) | View, activate, trigger, and inspect scheduled jobs | | [`lua workflows`](/reference/cli/workflows) | Manage workflows, runs, approvals, schedules, and goals | | [`lua preprocessors`](/reference/cli/processors), [`lua postprocessors`](/reference/cli/processors) | Manage message and response processors | | [`lua mcp`](/reference/cli/mcp) | List, activate, and deactivate MCP servers | | [`lua devices`](/reference/cli/devices) | List, test, enable, and remove connected devices | | [`lua voice`](/reference/cli/voice) | Try a voice live in the browser or by phone; run voice tests | | [`lua persona`](/reference/cli/persona) | View and deploy persona versions | | [`lua production`](/reference/cli/production) | Summarize what is live in production | | [`lua agents`](/reference/cli/agents-and-models), [`lua models`](/reference/cli/agents-and-models) | List accessible agents; list and set the model | | [`lua channels`](/reference/cli/channels) | List and set up channels | | [`lua features`](/reference/cli/features) | Enable and configure agent features | | [`lua resources`](/reference/cli/resources) | Manage knowledge-base resources | | [`lua integrations`](/reference/cli/integrations) | Connect third-party integrations and subscribe to their events | | [`lua marketplace`](/reference/cli/marketplace) | Publish and install marketplace skills and agent templates | | [`lua governance`](/reference/cli/governance) | Add or remove governance enforcement | | [`lua admin`](/reference/cli/utilities), [`lua evals`](/reference/cli/utilities), [`lua docs`](/reference/cli/utilities) | Open the admin dashboard, evaluations, and docs in a browser | | [`lua completion`](/reference/cli/utilities), [`lua update`](/reference/cli/utilities), [`lua telemetry`](/reference/cli/utilities) | Shell completion, self-update, telemetry on or off | ## See also * [Errors and exit codes](/reference/cli/errors-and-exit-codes) * [Environment variables](/reference/cli/environment-variables) * [lua.skill.yaml](/reference/cli/lua-skill-yaml) * [Automate releases in CI](/ship/ci-and-automation)