# Install the CLI

```bash
npm i -g @dreamlake/lakeshore
```

> **Note:** On macOS: `brew install node && npm i -g @dreamlake/lakeshore`

The package is ESM. The `lakeshore` bin prefers the compiled
`dist/cli/index.js`; in a source checkout without a build it falls back
to running `src/cli/index.ts` directly (under Bun) or via the `tsx` ESM
loader (under Node).

Verify the install with `lakeshore --help`. There is **no**
`lakeshore --version` — the program never registers one, so Commander
rejects it as an unknown option. Use `npm ls -g @dreamlake/lakeshore`
to see which version you have.

## Authenticate

Your admin will give you a **token** and a **namespace** (e.g. `fortyfive`).

```bash
lakeshore auth login \
  --server https://api.lakeshore.dreamlake.ai \
  --namespace <your-namespace> \
  --token <your-token>
```

`login` validates the token by calling
`GET <server>/v1/namespaces/<ns>/whoami` with a Bearer header before it
saves anything. On success it writes YAML to
`$XDG_CONFIG_HOME/lakeshore/auth.yml` (default
`~/.config/lakeshore/auth.yml`) with mode `600`:

```yaml file="~/.config/lakeshore/auth.yml"
server: https://api.lakeshore.dreamlake.ai
namespace: your-namespace
token: dlk_xxxxxxxx…
```

> **Warning:** `--namespace` must match the namespace the token was minted for.
> Without it the CLI defaults to `default`, and the control plane
> rejects the call because the token does not grant access to that
> namespace.

Omit `--token` to be prompted interactively. If `LAKESHORE_ADMIN_TOKEN`
is exported, `login` instead mints a fresh per-namespace token on the
server for you and saves that; `--name <label>` labels it.

Verify with:

```bash
lakeshore auth status
```

This reloads the file and re-validates against `whoami`, printing the
config path, server, namespace, token prefix, last-used timestamp, and
`authMode`.

## Env vars that change where commands point

| Variable              | Read by                     | Effect                                                                     |
| --------------------- | --------------------------- | -------------------------------------------------------------------------- |
| `LAKESHORE_URL`       | every command **except** `auth` | Control-plane base URL. When set, the CLI sends **no bearer token** and ignores the saved login. |
| `LAKESHORE_NAMESPACE` | every command except `auth` | Namespace used alongside `LAKESHORE_URL`. Defaults to `default`.            |
| `LAKESHORE_SERVER`    | the `auth` commands only    | Server URL when `--server` is not passed.                                   |
| `LAKESHORE_ADMIN_TOKEN` | `auth login`, `admin`, `nymph`, `daemon install` | Admin bearer. Required for every `admin` subcommand. |

> **Warning:** `LAKESHORE_URL` and `LAKESHORE_SERVER` are not interchangeable, and
> `LAKESHORE_URL` is not a convenience alias for the saved server. In
> `LAKESHORE_URL` mode the CLI deliberately sends no token — which is
> right for an open-mode local stack and wrong against a token-enforced
> deployment. Unset it after `auth login` if you need the token path.

`lakeshore auth logout` deletes the saved file.

## Where to next

| I want to…                      | Page                                                       |
| ------------------------------- | ---------------------------------------------------------- |
| See the whole command surface   | [`lakeshore` CLI](/cli.md)                                    |
| Run my first commands           | [CLI examples · auth](/cli/examples/auth.md)                  |
| Set up shell tab-completion     | [Completion](/cli/completion.md)                              |
| Connect a cloud provider        | [Providers](https://docs.dreamlake.ai/lakeshore/providers) |
| Walk a verified end-to-end flow | [Happy paths](/cli/happy-paths.md)                            |