nordisk/nornir

.nornir/cli-thin-client-for-idiots.md

# nornir CLI thin client — for idiots

Copy-paste recipes for driving `nornir` against a running server. The full design
is in [cli-client-modes.md](cli-client-modes.md). One rule to remember:

> **`--server` = talk to the server (thin). No `--server` = read local files (fat).**

## 1. Talk to a server (thin client)

```sh
nornir repos --server http://oden:7878 --token <TOK>
```

- Bare `host:port` is fine too: `--server oden:7878` (it adds `http://`).
- No `--token`? It uses `$NORNIR_SERVER_TOKEN`, then `~/.nornir/token`. So often:

```sh
nornir repos --server oden:7878         # token read from ~/.nornir/token
```

Flags go **anywhere** — both of these work:

```sh
nornir test run nornir --server oden:7878 --token <TOK>
nornir --server oden:7878 --token <TOK> test run nornir
```

## 2. Pick the workspace

A server hosts many workspaces (`holger`, `nordisk`, `korp`, …). Three ways to say
which one — the name is the bit **after `workspace_`** (`workspace_nordisk` → `nordisk`):

```sh
# a) stand in the workspace dir — auto-detected:
cd /…/git/workspace_nordisk && nornir repos --server oden:7878

# b) name it explicitly from anywhere:
nornir repos --server oden:7878 --workspace nordisk

# c) set it once for your shell:
export NORNIR_WORKSPACE=nordisk
```

Forget to pick one?

- **In a terminal** → you get a numbered menu: type `2` (or the name).
- **In a script/pipe** → you get an error that **lists the served workspaces**, so
  the script fails fast instead of hanging.

Typo a name? The error tells you the real ones:

```
workspace `nordsk` is not served
  workspaces served by http://oden:7878: holger, knut, korp, njord, nordisk, skade, znippy
  → pass --workspace <name>, or cd into a workspace_<name>/ dir
```

## 3. Read local files instead (fat / embedded)

Just **drop `--server`** (and don't set `$NORNIR_SERVER`):

```sh
cd /…/git/workspace_holger
nornir repos          # reads the local ~/.nornir warehouse directly, no server
```

Use this offline or when no server is running. Don't run it against a warehouse a
server is actively using.

## 4. See which workspaces exist on a server

```sh
nornir workspace ls --server oden:7878 --token <TOK>
```

## Gotchas

- "**workspace `git` is not served**" used to happen — that bug is fixed; the client
  now sends the real `workspace_<name>` suffix.
- The viz uses the **same** rule and the **same** server — `nornir viz --server …`
  and the CLI agree on the workspace.