# CLI examples — Auth and setup

The first stop in the [CLI examples cookbook](/cli/examples.md). Run the
shell setup block once per shell, then save a token with `auth login`
so the rest of the cookbook is paste-ready.

## Setup (run once per shell)

```bash
# Where the control plane lives. Override for staging / prod.
export LAKESHORE_URL=http://localhost:8080
export LAKESHORE_NAMESPACE=default

# Seed a daemon id into $D for examples that take an <id>. Once any
# daemon is registered, this picks the first one. Re-run after launch.
D=$(lakeshore daemon list --json | jq -r '.[0].id // empty')
echo "using daemon: $D"
```

`$D` is referenced in any block that needs a daemon id. If `daemon list`
is empty when you start, jump to
[Daemons](/cli/examples/daemons-and-exec.md), bring one up, then re-run
the `D=` line.

> **Warning:** With `LAKESHORE_URL` exported, `resolveServer()` takes that path and
> **does not read the saved auth file** — it sends no bearer token at
> all, so any `auth login` token is ignored. That is correct for an
> open-mode local control plane and wrong for a token-enforced
> deployment. For the latter, either skip the `LAKESHORE_URL` export and
> rely on the saved login, or `unset LAKESHORE_URL` after running
> `lakeshore auth login`.

## Auth (one-time login)

The `auth` commands are the only ones that read `LAKESHORE_SERVER`.
Their server precedence is `--server` → `LAKESHORE_SERVER` → the saved
auth file → `http://localhost:8080`.

### `auth login` — save a token

Prompts for a bearer token on a TTY (omit `--token`), validates it
against `GET <server>/v1/namespaces/<ns>/whoami`, then writes
`~/.config/lakeshore/auth.yml` with mode 600.

```bash
lakeshore auth login --server "$LAKESHORE_URL" --namespace default
lakeshore auth login --server "$LAKESHORE_URL" --namespace default --token dlk_xxxx
```

Nothing is saved if `whoami` rejects the token.

### `auth login` — non-interactive (admin-mint via env)

When `LAKESHORE_ADMIN_TOKEN` is exported and `--token` is absent, the
CLI mints a fresh per-namespace token on the server and saves that.
`--name` sets the label base; the CLI appends a timestamp so re-running
doesn't collide with the unique-name constraint.

```bash
LAKESHORE_ADMIN_TOKEN=changeme lakeshore auth login \
  --server "$LAKESHORE_URL" \
  --namespace default \
  --name laptop
```

### `auth status` — show and revalidate

Prints the config path, server, namespace, token prefix and label, last
used timestamp, and `authMode`, after re-hitting `whoami`. Exits 1 when
there is no saved auth or the revalidation fails.

```bash
lakeshore auth status
lakeshore auth status --server https://api.lakeshore.dreamlake.ai --namespace other-ns
```

```text
Auth OK.
  config path: /Users/you/.config/lakeshore/auth.yml
  server:      http://localhost:8080
  namespace:   default
  token:       dlk_abcd... (laptop-2026-01-02T03-04-05)
  lastUsedAt:  2026-01-02T03:05:11.000Z
  authMode:    token
```

`authMode` is one of `admin`, `token`, or `open`. `open` means the
control plane is running without token enforcement.

### `auth logout` — drop the saved token

Deletes `~/.config/lakeshore/auth.yml`. The next CLI invocation needs
either `LAKESHORE_URL` set (open mode) or another `auth login`.

```bash
lakeshore auth logout
```

## Minting tokens for other people

Only an admin can. `lakeshore admin ...` hard-fails with exit 1 unless
`LAKESHORE_ADMIN_TOKEN` is set.

```bash
export LAKESHORE_ADMIN_TOKEN=<admin-token>

lakeshore admin tokens create alice        # label defaults to <$USER>-<YYYY-MM-DD>
lakeshore admin tokens list                # alias: ls
lakeshore admin tokens revoke <token-id>

lakeshore admin namespace create team-a    # group alias: ns
lakeshore admin namespace list             # alias: ls
lakeshore admin namespace delete team-a    # alias: rm
```

`tokens create` prints the plaintext **once** along with a ready-made
`lakeshore auth login` line for the recipient. None of the `admin`
subcommands take flags.

## Read next

- [Installation](/cli/installation.md) — install plus the full env-var table.
- [Providers + discover](/cli/examples/providers-and-discover.md) — the next step.
- [Auth and secrets](/api/auth-and-secrets.md) — the server-side model.