Orchestrator worker CLI
Debug worker steps on your own machine.
Run any step with a station's config or a saved scenario, read the error, fix it and run it again, without waiting for the Orchestrator. Then see where every workpiece is, and why the stuck ones failed.
$ npm install -g @finopsbricks/fob-worker$ fob worker lines status IN 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 —
Two ways to drive it
The same commands work for you and for your agent.
You, in the terminal
Run one step with a station's config, a saved scenario or none. Outputs chain into the next step, just as on the worker, and failures show the resolved config and the error.
$ fob-worker steps run IN1_01_check --scenario two-invoicesRun steps locally →Your AI agent
Claude Code, Cursor and Codex already run commands. Give them fob-worker and ask: "INV-1002 is stuck in IN1/failed; find out why and fix the step."
$ fob-worker workpieces show INV-1002Use with AI agents →What it covers
Reads and writes your worker repo on this machine. It never calls the Orchestrator; fob-orc does that.
| Area | Resources | Writes |
|---|---|---|
| Steps List your steps; run one with a station's config, a scenario or an empty config, and chain outputs | List your steps; run one with a station's config, a scenario or an empty config, and chain outputs | |
| Lines and stations Lines, stations, steps and conveyors from your station files; bin counts per station | Lines, stations, steps and conveyors from your station files; bin counts per station | Read only |
| Workpieces Where each one is, its journey from log.jsonl, and a live tail | Where each one is, its journey from log.jsonl, and a live tail | Read only |
| Bins Empty a line's or a station's bins while you develop, with a preview and a prompt | Empty a line's or a station's bins while you develop, with a preview and a prompt | |
| Processes Start, stop, restart and tail your worker under pm2; list every worker on the machine | Start, stop, restart and tail your worker under pm2; list every worker on the machine |
Every command and option: command reference →
Set up in four steps
About fifteen minutes from an empty folder. Running steps locally needs no Orchestrator account.
- 1
Install
npm install -g @finopsbricks/fob-worker @finopsbricks/fob-orc - 2
Create a worker repo
Clone worker-template, fill in its placeholders and run npm install.
- 3
Write a step
A file under src/steps/ that exports defineStep().
- 4
Run it
fob-worker steps run IN1_01_check --scenario two-invoices
Questions
Do I need an account?
Not to run steps locally: install fob-worker and use the worker template. To run a worker for real you need an Orchestrator account. Sign up, then create an organisation in the Orchestrator. Sign up →
Does fob-worker talk to the Orchestrator?
No. It reads and writes files in your worker repo: steps, station files, bins and workpieces. Pulling and pushing station definitions and triggering runs is fob-orc's job, and the worker itself talks to the Orchestrator when it runs. How the pieces fit →
What is a worker?
A Node.js program built on lib-worker that runs on your machine or server. It polls the Orchestrator for steps, runs your code for each one and reports back, so your data and credentials for other systems stay with you. Concepts →
Do I need pm2?
Only for fob-worker procs, which runs your worker in the background. Everything else works without it. procs is for macOS and Linux. Run in the background →
Does a local run touch real systems?
Your step runs for real, so if it calls an API, that call happens. Attachments and reports are written to temp/ instead of being sent to the Orchestrator. Point your .env at test accounts while you develop. What a run does →
Is it production-ready?
It's in Beta. Running steps, inspecting bins and pm2 management work today. Built-in lib-worker steps such as move_files don't run locally, and lines and stations come from your local station files, not a live Orchestrator view. Beta limits →
fob-worker is open source under Apache-2.0. Running a worker against the Orchestrator needs an Orchestrator account.