# 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
command -v uv >/dev/null 2>&1 || curl -LsSf https://astral.sh/uv/install.sh | sh
```

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

The Skill teaches an Agent the Luna analysis workflow and the exact LunaLuna commands. If `npx` is
already available, download the Skill to a temporary directory and let `skills` select the Agent
and global or project scope.

macOS and Linux:

```sh
skill_dir="$(mktemp -d)"
curl -fsSL https://get.lunaluna.nz/SKILL.md -o "$skill_dir/SKILL.md"
npx skills add "$skill_dir"
rm -rf "$skill_dir"
```

Windows PowerShell uses `curl.exe` explicitly because Windows PowerShell 5.1 aliases `curl`:

```powershell
$skillDir = Join-Path ([System.IO.Path]::GetTempPath()) ("lunaluna-skill-" + [guid]::NewGuid())
New-Item -ItemType Directory -Force -Path $skillDir | Out-Null
curl.exe -fsSL https://get.lunaluna.nz/SKILL.md -o (Join-Path $skillDir "SKILL.md")
npx skills add $skillDir
Remove-Item -Recurse -Force $skillDir
```

Do not install Node.js only for this step. If `npx` is unavailable or the Agent is unsupported,
download `SKILL.md` the same way and use 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.

Download and install `SKILL.md` again after upgrading so the Agent instructions match the current
client. Existing server configuration is retained.

## Quick Check

Run these commands from the LunaLuna workspace:

```text
uv run lunaluna config status
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.