# 02 · Hello, hosted control plane

Two commands prove the CLI can authenticate against a real control
plane, send a bearer token, and read its namespace back. Run this when
you've just installed the CLI and want to confirm the wire works before
anything else. Takes under a minute.

## Before you begin

- Network access to a control plane. The hosted one lives at
  `https://api.lakeshore.dreamlake.ai`.
- A valid client token (`dlk_...`) scoped to at least one namespace. If
  you don't have one yet, see
  [15 · Token lifecycle](/cli/happy-paths/15-token-lifecycle.md).
- `LAKESHORE_URL` **unset**. If it's exported, every non-`auth` command
  will use it and send no token at all, which defeats the point of this
  test.

## Step 1: Log in

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

`login` validates by calling `GET /v1/namespaces/<ns>/whoami` with the
Bearer header **before** it writes anything. On success it saves
`~/.config/lakeshore/auth.yml` with mode 600 and prints:

```text
Saved auth to /Users/you/.config/lakeshore/auth.yml
  server:    https://api.lakeshore.dreamlake.ai
  namespace: <your-namespace>
  token:     dlk_abcd...
  authMode:  token
```

## Step 2: Check status

```bash
lakeshore auth status
```

This reloads the file and re-validates it against the same `whoami`
endpoint.

## What success looks like

```text
Auth OK.
  config path: /Users/you/.config/lakeshore/auth.yml
  server:      https://api.lakeshore.dreamlake.ai
  namespace:   <your-namespace>
  token:       dlk_abcd... (laptop-2026-01-02T03-04-05)
  lastUsedAt:  2026-01-02T03:05:11.000Z
  authMode:    token
```

`authMode: token` plus your namespace means the full auth path — TLS,
Bearer header, token-hash lookup, namespace scoping — works end to end.

## If something goes wrong

| Symptom | Likely cause |
| --- | --- |
| `whoami failed (401)` | Token typo or revoked. Re-mint via [15 · Token lifecycle](/cli/happy-paths/15-token-lifecycle.md). |
| `whoami failed (403)` | Token valid but scoped to a different namespace. Check `--namespace`. |
| `ENOTFOUND` / DNS error | Server URL typo, or no internet. |
| `No saved auth.` from `status` | `login` never completed — it does not save when `whoami` rejects the token. |
| `authMode: open` | You hit a control plane running without token enforcement. Fine for local dev, not what you want against the hosted CP. |

## You're done

The CLI can talk to the hosted control plane. Next, run the same
exercise against a local stack:
[03 · Hello, local stack](/admin/happy-paths/03-hello-local-stack.md).