> ## 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.

# Install the CLI and sign in

> Install lua-cli with npm, sign in with an email code or an API key, and confirm the setup with lua status

After this guide, `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](/build-with-ai/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](/concepts/credentials) created in the admin dashboard.

<Steps>
  <Step title="Install the CLI">
    Install `lua-cli` globally so the `lua` command is on your `PATH`.

    <CodeGroup>
      ```bash npm theme={null}
      npm install -g lua-cli
      ```

      ```bash pnpm theme={null}
      pnpm add -g lua-cli
      ```

      ```bash yarn theme={null}
      yarn global add lua-cli
      ```
    </CodeGroup>

    The package also installs `heylua` and `lua-ai`, identical binaries for machines where another tool owns the `lua` name. Confirm the version:

    ```bash theme={null}
    lua --version
    ```

    ```text Output theme={null}
    3.33.0
    ```
  </Step>

  <Step title="Sign in">
    `lua auth configure` asks for a method and stores the result under `~/.lua-cli/`.

    <Tabs>
      <Tab title="Email">
        Choose **Email**, enter your address, then enter the six-digit code the CLI emails you. The command ends with `✅ Signed in as you@example.com.` and saves a renewable [user session](/concepts/credentials) that follows the organizations and agents your account can reach, so you sign in once per machine.

        ```bash theme={null}
        lua auth configure
        ```

        In a script, request the code and verify it as two commands:

        ```bash theme={null}
        lua auth configure --email you@example.com
        lua auth configure --email you@example.com --otp 123456
        ```
      </Tab>

      <Tab title="API key">
        Choose **API Key** and paste a scoped or legacy key; the CLI validates it against the server and writes it to `~/.lua-cli/credentials`.

        ```bash theme={null}
        lua auth configure --api-key <key>
        ```

        In CI, skip the file and export `LUA_API_KEY` instead; it takes precedence over any stored user session or key.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Verify">
    `lua status` reports the CLI version, the credential in use, and whether the server answered; add `--json` in scripts.

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

    ```text Output theme={null}
    Environment
    ├─ CLI version: 3.33.0 (channel: latest)
    ├─ Node: v26.5.0
    …
    Auth
    ├─ ✓ authenticated (10213ms)
    ├─ Key source: renewable session
    ├─ Email: you@example.com
    …
    Project
    └─ not inside a lua project
    ```
  </Step>
</Steps>

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

<AccordionGroup>
  <Accordion title="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`.
  </Accordion>

  <Accordion title="EACCES during npm install -g">
    The global npm directory is not writable by your user. Follow npm's guide, [Resolving EACCES permissions errors](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally), rather than installing with `sudo`.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Next steps

<Columns cols={2}>
  <Card title="Quickstart" href="/get-started/quickstart">Create an agent, add one tool, and release it.</Card>
  <Card title="Project structure" href="/get-started/project-structure">What `lua init` writes and which files you edit.</Card>
  <Card title="lua auth reference" href="/reference/cli/auth">Every flag of `configure`, `logout`, `sessions`, and `key`.</Card>
  <Card title="About credentials" href="/concepts/credentials">User sessions, scoped keys, legacy keys, and scopes.</Card>
</Columns>