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

# Installation

> Install Lua CLI and set up your development environment

## Prerequisites

<CardGroup cols={2}>
  <Card title="Node.js" icon="node-js">
    Version 16.0.0 or higher
  </Card>

  <Card title="npm" icon="npm">
    Version 7.0.0 or higher
  </Card>
</CardGroup>

## Installation Methods

### Global Installation (Recommended)

Install Lua CLI globally to use it from anywhere:

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

  ```bash yarn theme={null}
  yarn global add lua-cli
  ```

  ```bash pnpm theme={null}
  pnpm add -g lua-cli
  ```
</CodeGroup>

Verify installation:

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

### Using Package Runners (No Installation)

Run Lua CLI without installing:

<CodeGroup>
  ```bash npx theme={null}
  npx lua-cli [command]
  ```

  ```bash yarn theme={null}
  yarn dlx lua-cli [command]
  ```

  ```bash pnpm theme={null}
  pnpm dlx lua-cli [command]
  ```
</CodeGroup>

<Note>
  Package runners are great for trying out Lua CLI, but global installation is recommended for regular use.
</Note>

## Authentication

After installation, set up your credentials:

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

### Authentication Methods

<Tabs>
  <Tab title="Email (Recommended)">
    **Sign in with a renewable session**

    1. Choose **Email**.
    2. Enter your email address and the six-digit code sent to you.
    3. The CLI saves a renewable first-party session.

    ```bash theme={null}
    $ lua auth configure
    ? Choose authentication method: Email
    ? Enter your email address: you@example.com
    ? Enter the OTP code: 123456
    ✅ Signed in as you@example.com.
    ```
  </Tab>

  <Tab title="API Key">
    **Existing API Key**

    If you already have a scoped or non-dotted legacy API key:

    1. Choose **API Key**.
    2. Enter your API key.
    3. The CLI validates and saves it unchanged.

    ```bash theme={null}
    $ lua auth configure
    ? Choose authentication method: API Key
    ? Enter your API key: api_abc123def456...
    🔐 Validating API key...
    ✅ API key validated and saved securely.
    ```
  </Tab>
</Tabs>

### Credential precedence

The CLI reads credentials in this order:

1. `LUA_API_KEY`; if it is not exported, the CLI loads it from the current project's `.env`
2. The renewable session for the active Lua environment
3. `~/.lua-cli/credentials`

Email login writes an owner-only session file under `~/.lua-cli/sessions/`. Direct API-key setup writes `~/.lua-cli/credentials`. Existing API keys remain supported alongside Email login.

<Warning>
  Never commit your API key to version control or share it publicly.
</Warning>

## Verify Installation

Check that everything is working:

```bash theme={null}
# Check CLI version
lua --version

# View stored API key
lua auth key

# Get help
lua --help
```

## Development Tools

While not required, these tools enhance the development experience:

<CardGroup cols={2}>
  <Card title="VS Code" icon="code">
    Recommended editor with TypeScript support
  </Card>

  <Card title="Git" icon="git">
    Version control for your skills
  </Card>
</CardGroup>

## TypeScript Setup

The template project includes TypeScript configuration. No additional setup needed!

When you run `lua init`, you get:

* `tsconfig.json` - TypeScript configuration
* `package.json` - Dependencies
* Full type definitions for all Lua APIs

## Troubleshooting

<AccordionGroup>
  <Accordion title="Command not found: lua">
    **Problem**: The CLI isn't in your PATH

    **Solutions**:

    * Reinstall globally: `npm install -g lua-cli`
    * Use npx instead: `npx lua-cli [command]`
    * Check npm global path: `npm config get prefix`
  </Accordion>

  <Accordion title="Permission denied">
    **Problem**: Need sudo for global installation

    **Solution on Unix**:

    ```bash theme={null}
    sudo npm install -g lua-cli
    ```

    **Better solution**: Configure npm to install globally without sudo:

    ```bash theme={null}
    mkdir ~/.npm-global
    npm config set prefix '~/.npm-global'
    export PATH=~/.npm-global/bin:$PATH
    ```
  </Accordion>

  <Accordion title="API key not found">
    **Problem**: Authentication not configured

    **Solution**:

    ```bash theme={null}
    lua auth configure
    ```
  </Accordion>

  <Accordion title="Node.js version too old">
    **Problem**: Node.js version is below 16.0.0

    **Solution**: Update Node.js

    * Visit [https://nodejs.org](https://nodejs.org)
    * Download and install LTS version
    * Or use nvm: `nvm install --lts`
  </Accordion>
</AccordionGroup>

## Next Steps

<Steps>
  <Step title="Create Your First Project">
    ```bash theme={null}
    mkdir my-skill && cd my-skill
    lua init
    ```
  </Step>

  <Step title="Explore the Template">
    Learn about the example tools and skills included

    <Card title="Template Guide" icon="layer-group" href="/template/overview" />
  </Step>

  <Step title="Start Building">
    Begin customizing tools for your use case

    <Card title="Building Skills" icon="hammer" href="/template/building-skills" />
  </Step>
</Steps>