> ## 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 utility commands

> lua update, lua completion, lua telemetry, lua admin, lua evals, lua docs, and lua --cli-version

These commands maintain the CLI itself and open the Lua web surfaces. None of them changes an agent or anything end users see.

*Verified against lua-cli 3.33.0.*

## Synopsis

```bash theme={null}
lua update
lua completion [bash|zsh|fish]
lua telemetry [on|off|status]
lua admin
lua evals
lua docs
lua --cli-version
```

## Description

`lua update` checks the npm registry for the latest `lua-cli` and runs `npm install -g lua-cli@<tag>`, where the tag is `latest` or the pre-release tag your installed version carries. It only updates global npm installs: an `npm link` development install is detected and left alone with a message, and a permissions failure prints the `sudo` form to run. When you are already on the latest version it prints `✅ lua-cli is already up to date (v<version>)`.

`lua completion <shell>` prints a completion script for `bash`, `zsh`, or `fish` (aliases `sh`, `z`, `f`) to append to your shell configuration; without a shell it prints installation instructions. The scripts complete a fixed set of top-level commands and their actions and do not cover every command the CLI has.

`lua telemetry` shows or changes whether usage events are collected. `status` (the default) prints `Telemetry: enabled` or `disabled`; `on` and `off` store the choice in `~/.lua-cli/telemetry.json`. Setting `LUA_TELEMETRY` to `false`, `0`, `off`, or `no` disables collection and overrides the stored setting. Aliases: `enable` and `activate` for `on`, `disable` and `deactivate` for `off`, `info`, `show`, and `view` for `status`. When enabled, each command sends an event to PostHog with the command name, whether it succeeded, its duration, the CLI version, the first 200 characters of any error message, the operating system and its version, the architecture and Node version, whether it ran in CI or without a terminal, the organization and agent ids from `lua.skill.yaml`, and a distinct id derived from a hash of your credential (or a random id when signed out). A notice is printed once per install the first time telemetry is active.

`lua admin` opens the admin dashboard at `https://admin.heylua.ai` for the configured agent and prints the agent and organization ids; `lua evals` opens the evaluations dashboard at `https://evals.heylua.ai` for the configured agent. Both need a project and a credential. `lua admin` signs you in through a short-lived handoff code in the URL, or opens the sign-in page when your credential cannot be handed off; `lua evals` puts your credential in the URL query string. `lua docs` opens `https://docs.heylua.ai` and needs neither. `lua --cli-version` (or `-V`) prints the installed version; `lua --ci` is a global flag that makes any command fail instead of prompting.

## Arguments

| Argument   | Values                | Description                                                     |
| ---------- | --------------------- | --------------------------------------------------------------- |
| `[shell]`  | `bash`, `zsh`, `fish` | `lua completion`: which script to print. Omit for instructions. |
| `[action]` | `on`, `off`, `status` | `lua telemetry`: defaults to `status`.                          |

## Options

None of these commands take options beyond the global `--ci` and `-h, --help`.

## Examples

Update the CLI:

```bash theme={null}
lua update
```

Install completion for zsh:

```bash theme={null}
lua completion zsh >> ~/.zshrc
source ~/.zshrc
```

Print the installation instructions:

```bash theme={null}
lua completion
```

```text Output theme={null}

🎯 Lua CLI Shell Completion

To enable autocomplete, run one of the following commands based on your shell:

Bash:
  $ lua completion bash >> ~/.bashrc
  $ source ~/.bashrc

Zsh:
  $ lua completion zsh >> ~/.zshrc
  $ source ~/.zshrc

Fish:
  $ lua completion fish > ~/.config/fish/completions/lua.fish
…
```

Check the telemetry setting:

```bash theme={null}
lua telemetry status
```

```text Output theme={null}
Telemetry: enabled

Usage:
  lua telemetry on      Enable telemetry
  lua telemetry off     Disable telemetry
  lua telemetry status  Show current setting

Or set LUA_TELEMETRY=false in your environment.
```

Turn telemetry off for this machine:

```bash theme={null}
lua telemetry off
```

Disable telemetry for one CI run without touching the stored setting:

```bash theme={null}
LUA_TELEMETRY=false lua push all --force --ci
```

Open the admin dashboard for the current project:

```bash theme={null}
lua admin
```

## Exit codes

| Code | Meaning                                                                                 |
| ---- | --------------------------------------------------------------------------------------- |
| `0`  | Success, including `already up to date` and a detected development install.             |
| `1`  | `lua update` could not reach the npm registry or the install failed.                    |
| `2`  | An unknown shell or telemetry action, or `lua admin` and `lua evals` outside a project. |
| `9`  | `lua admin` and `lua evals` without a credential.                                       |

## See also

* [CLI overview](/reference/cli/overview) — install, binaries, global flags, credential precedence
* [Environment variables](/reference/cli/environment-variables) — `LUA_TELEMETRY`, `LUA_NO_HINTS`, `LUA_DEBUG`
* [Install and sign in](/get-started/install)
* [About security and data](/concepts/security-and-data) — what telemetry and credentials store