# Install LunaLuna

LunaLuna is the Python SDK and command-line client for the Luna HTTP API. Install it in a dedicated
uv workspace so Agent commands and Python scripts use the same isolated environment.

You need a Luna API key from your administrator. LunaLuna uses `https://api.lunaluna.nz` by default.
Never include the API key in chat output, logs, scripts, or committed files.

## macOS and Linux

Install uv if it is not already available:

```sh
if ! command -v uv >/dev/null 2>&1; then
    curl -LsSf https://astral.sh/uv/install.sh | sh
    . "$HOME/.local/bin/env"
fi
```

Create the recommended workspace and install the current LunaLuna release with its analysis tools:

```sh
mkdir -p "$HOME/lunaluna-workspace"
cd "$HOME/lunaluna-workspace"
test -f pyproject.toml || uv init --bare --python 3.12
uv add 'lunaluna[analysis] @ https://get.lunaluna.nz/dist/lunaluna-2026.9.25-py3-none-any.whl'
```

Save the connection once, then verify configuration, connectivity, authentication, and version:

```sh
uv run lunaluna config set --api-key 'sk-luna-v1-REPLACE_ME'
uv run lunaluna config status
```

## Windows PowerShell

Install uv if it is not already available:

```powershell
if (-not (Get-Command uv -ErrorAction SilentlyContinue)) {
    irm https://astral.sh/uv/install.ps1 | iex
}
```

Create the recommended workspace and install the current LunaLuna release with its analysis tools:

```powershell
$workspace = Join-Path $HOME "lunaluna-workspace"
New-Item -ItemType Directory -Force -Path $workspace | Out-Null
Set-Location $workspace
if (-not (Test-Path pyproject.toml)) { uv init --bare --python 3.12 }
uv add "lunaluna[analysis] @ https://get.lunaluna.nz/dist/lunaluna-2026.9.25-py3-none-any.whl"
```

Save the connection once, then verify configuration, connectivity, authentication, and version:

```powershell
uv run lunaluna config set --api-key "sk-luna-v1-REPLACE_ME"
uv run lunaluna config status
```

## Install the Agent Skill

LunaLuna includes a small Skill that directs Agents to the current Server-provided Help. If `npx`
is already available, ask `skills` to install it for the desired Agent and global or project scope.

macOS and Linux:

```sh
skill_file="$(uv run lunaluna skill)"
npx skills add "$(dirname "$skill_file")"
```

Windows PowerShell:

```powershell
$skillFile = (uv run lunaluna skill).Trim()
npx skills add (Split-Path -Parent $skillFile)
```

Do not install Node.js only for this step. If `npx` is unavailable or the Agent is unsupported,
run `uv run lunaluna skill` and use the reported file with the Agent's native local Skill import.

For a private Luna deployment, add `--url https://your-luna-server.example` to `config set`.

## Upgrade

When LunaLuna reports an available or required update, open `https://get.lunaluna.nz/` and rerun
the workspace installation command shown there. The versioned wheel URL updates the uv lockfile
without relying on a mutable package cache. Run `uv run lunaluna config status` afterward.

The installed Skill does not need routine updates because its analysis guidance comes from Luna
Server. Existing server configuration is retained.

## Quick Check

Run these commands from the LunaLuna workspace:

```text
uv run lunaluna config status
uv run lunaluna help
uv run lunaluna search sales
uv run lunaluna --help
```

If Status fails, resolve that error before running business commands. A `401` response means the
API key is invalid or revoked; ask the Luna administrator for a current key. Connection errors
usually mean the Server URL, DNS, proxy, or network is unavailable. An unsupported client message
means the exact wheel URL in this document must be installed before retrying.