# Inspect lines and workpieces

These commands read the worker repo on the machine you run them on: station and line files from `.orchestrator/`, and bins from `temp/stations/`. Run them on the machine where the worker runs to see its real state.

## Lines

```bash
fob-worker lines list
```

```text
LINE  NAME            LOCATION  STATIONS  MEMBERS
--------------------------------------------------
IN    Invoice intake  acme      2         IN0, IN1

Total: 1 lines, 2 stations
```

`lines show <line>` lists a line's stations in order, their steps and dependencies, and the conveyors between them. See [Stations and lines](/docs/workers/stations-and-lines#the-move-files-conveyor).

## How much is where

```bash
fob-worker lines status
```

```text
LINE  IN-FLIGHT  STUCK  FINISHED  HEALTH
---------------------------------------------------
IN    0          1      2         ⚠ 1 at IN1/failed
```

- **In-flight**: workpieces in `input`, `doing` or `output` of any station except the last.
- **Stuck**: workpieces in a `failed` bin.
- **Finished**: workpieces in the last station's `output`.

Name a line for its bins, station by station:

```bash
fob-worker lines status IN
```

```text
Line: IN
Stations:     IN0 → IN1
Terminal:     IN1

STATION  INPUT  DOING  OUTPUT  FAILED  (DONE)
---------------------------------------------
IN0      —      —      0       —       —
IN1      0      0      2       1       (2)
live     0      0      2       1       —
```

`—` means the bin folder doesn't exist yet. `done` is shown in brackets because it holds receipts, not live work.

`stations status IN1` lists the workpieces in each of one station's bins. Add `--watch` to `lines status` or `stations status` to redraw every second (`--interval 5` for every five) while a run is going.

## One workpiece

```bash
fob-worker workpieces show INV-1002
```

```text
Workpiece: INV-1002
Position:  IN1/failed  (stuck)

Journey (UTC)
-------------
2026-10-03 14:35:02  IN0  workpiece_created
2026-10-03 14:35:03  IN1  station_started
2026-10-03 14:35:03  IN1  station_failed       (0ms)

Folder: file:///home/dev/worker-acme/temp/stations/IN1/failed/INV-1002
```

The journey comes from the workpiece's `log.jsonl`, in your local time zone. The folder link opens in most terminals; for a failed workpiece, `error.txt` there has the error.

Part of an id works too. If it matches several workpieces, you get the list instead.

## All workpieces

```bash
fob-worker workpieces list
fob-worker workpieces list --line IN
fob-worker workpieces list --bin IN1/failed
fob-worker workpieces list --match 1002
```

```text
Workpieces — 3 workpieces

WORKPIECE  POSITION               LAST EVENT (UTC)
--------------------------------------------------------------------
INV-1001   IN1/output (finished)  14:35  IN1  station_complete (1ms)
INV-1002   IN1/failed (stuck)     14:35  IN1  station_failed (0ms)
INV-1003   IN1/output (finished)  14:35  IN1  station_complete (0ms)
```

A workpiece's position is the furthest live bin it's in; the `done` copies don't count.

## Live tail

```bash
fob-worker workpieces watch INV-1002          # one workpiece
fob-worker workpieces watch --line IN         # everything on a line
fob-worker workpieces watch --bin IN1/input
```

It prints each move between bins and each new log event as it happens, until you press Ctrl-C.

## JSON

`lines list`, `lines show`, `lines status`, `stations status`, `workpieces list`, `workpieces show` and `procs list` take `--json`:

```bash
fob-worker stations status IN1 --json | jq '.bins.failed'
```

```json
[
  "INV-1002"
]
```

## Clearing bins

While you develop, empty a line's or a station's bins to start over:

```bash
fob-worker lines empty-bins IN --all-bins     # every bin on the line
fob-worker stations empty-bins IN1 --failed   # one station's failed bin
```

| Flag | Empties |
| --- | --- |
| `--input`, `--doing`, `--output`, `--failed`, `--done` | That bin |
| `--all-bins` | All five bins |
| `--intake-registry` | The line head's `intake-registry.jsonl` |
| `--all` | All five bins and the intake registry |

It shows what it will delete and asks before deleting. `--yes` skips the question; use it with care on a machine running a real worker.