---
name: setup-lupine-cli
description: Install and authenticate the Lupine Cloud CLI, then verify that a local command can see a remote Lupine GPU. Use when a user asks to install Lupine, configure Lupine Cloud, connect a machine to a cloud GPU, or confirm GPU access through Lupine.
---

# Set up the Lupine CLI

Set up Lupine on the user's current machine and prove that a local process can
see a GPU through Lupine Cloud. Do not claim success from `lupine status` alone:
complete an actual GPU enumeration command.

## Guardrails

- Run commands on the user's local machine, not on a remote shell.
- Never ask for, print, or copy OAuth tokens or payment details.
- Let the user complete browser authentication and billing steps themselves.
- Do not install NVIDIA drivers just to perform this check.
- End the test lease after verification so it does not remain billable.

## 1. Check the environment

Run:

```sh
uname -s
uname -m
command -v curl
```

The installer supports Linux and macOS on `x86_64`/`amd64` and
`aarch64`/`arm64`. If the OS or architecture is unsupported, stop and report it.
If `curl` is missing, ask before using a system package manager or `sudo`.

## 2. Install the CLI

If `lupine` is not already on `PATH`, run the official installer:

```sh
curl -fsSL https://dl.lupine.sh/install.sh | sh
```

If it installs to `$HOME/.local/bin`, make it available in the current shell:

```sh
export PATH="$HOME/.local/bin:$PATH"
```

Do not edit shell startup files unless the user asks. Confirm the install:

```sh
command -v lupine
lupine version
```

## 3. Authenticate

Run:

```sh
lupine login
```

The command opens `console.lupine.sh` and waits for up to five minutes. If a
browser cannot open automatically, give the printed login URL to the user.
Pause while the user completes GitHub or Google sign-in. Never inspect Lupine's
credential files.

Confirm account and billing readiness:

```sh
lupine billing
```

If it says no payment method is on file, direct the user to
`https://console.lupine.sh/billing` and wait for them to finish. Do not handle
card information. Run `lupine billing` again afterward.

## 4. Verify GPU visibility

Optionally show the available GPU catalog:

```sh
lupine gpus
```

If `nvidia-smi` exists locally, run:

```sh
lupine run -- nvidia-smi -L
```

Success requires all of the following:

- the command exits with status 0;
- Lupine reports that it acquired or reused a lease and connected through an
  HTTPS gateway;
- output contains at least one `GPU 0:` line; and
- the GPU name contains `(via lupine ...)`, proving the local command used the
  Lupine NVML shim rather than an unrelated physical GPU.

If `nvidia-smi` is not installed, use Python's standard library instead of
installing NVIDIA drivers:

```sh
lupine run -- python3 - <<'PY'
import ctypes

cuda = ctypes.CDLL("libcuda.so.1")

def check(call, code):
    if code != 0:
        raise SystemExit(f"{call} failed with CUDA error {code}")

check("cuInit", cuda.cuInit(0))
count = ctypes.c_int()
check("cuDeviceGetCount", cuda.cuDeviceGetCount(ctypes.byref(count)))
if count.value < 1:
    raise SystemExit("Lupine connected, but no GPU is visible")

device = ctypes.c_int()
name = ctypes.create_string_buffer(256)
check("cuDeviceGet", cuda.cuDeviceGet(ctypes.byref(device), 0))
check("cuDeviceGetName", cuda.cuDeviceGetName(name, len(name), device))
print(f"GPU 0: {name.value.decode()} (Lupine GPU count: {count.value})")
PY
```

For this fallback, require a zero exit status, Lupine's lease and HTTPS gateway
messages, and a printed GPU name with a count of at least one.

Always release the test lease when finished, including after a failed probe:

```sh
lupine end
```

If authentication, billing, capacity, the local GPU shim, or the probe fails,
report the exact failing command and error. Do not describe the setup as
complete.

## 5. Report the result

Tell the user:

- the installed `lupine version`;
- which verification command ran;
- the GPU name and count, if verification succeeded; and
- whether `lupine end` released the test lease.