Command line
uv tool install reaktiv-workbook # or: pip install reaktiv-workbookuvx reaktiv-workbook --help # or run it without installingThe examples below use the installed reaktiv-workbook command; with uvx, put uvx in front.
Open and create
Section titled “Open and create”| Command | Does |
|---|---|
reaktiv-workbook new [FILE] |
Create a workbook and open it (never overwrites) |
reaktiv-workbook new --from welcome |
Start from a bundled example (welcome, budget, …) |
reaktiv-workbook edit FILE |
Open a workbook in the editor; creates it if missing |
reaktiv-workbook run FILE |
Open it as an app: controls and actions work, editing is off |
The editor runs in your browser; the command serves it until you press Ctrl+C. Closing the browser does not stop it.
| Option | Use it to |
|---|---|
--sandbox |
Install the workbook’s declared packages into an environment of its own (needs uv) |
--mcp |
Let coding agents work in the open workbook (Agents) |
--port 8765 |
Use a fixed port |
--headless |
Print the link instead of opening the browser |
--host 0.0.0.0 --allow-remote |
Let other computers open the workbook (Share on a network) |
Without --sandbox, cells run in the Python that started the command, so install the
packages your workbook uses there (pip install plotly pandas). If some are missing,
the command names them and, when uv is available, offers to use a sandbox.
Adding packages while editing. After you add a package in Settings → Workbook, choose Restart with these packages (in a sandbox) or Restart in a sandbox (in your own Python); the editor also offers it when declared packages are missing. Python restarts in a sandbox with the new list, on the same address: the browser reconnects and the workbook stays open, unsaved edits included. Values computed at runtime are recomputed. Your own Python environment is never changed.
Share on a network
Section titled “Share on a network”By default only your own computer can open the editor. To let others in:
reaktiv-workbook edit analysis.workbook.py --host 0.0.0.0 --allow-remote --port 8800The command prints a link with your computer’s network address; send it to the people
who should join. Everyone works in the same running workbook: when one person moves a
slider, everyone sees it. With run instead of edit, people can only use the
workbook: change inputs, use widgets and run its exposed actions. File and folder inputs only
accept paths inside the workbook’s folder.
Anyone with the link can edit the workbook and run Python as you. Share it only on a
network you trust. The link travels as plain HTTP, so on other networks put HTTPS in
front and share that address instead, for example with
Tailscale (tailscale serve 8800) or a reverse
proxy such as Caddy. Then leave out --host but keep --allow-remote, so the workbook
knows it is shared; copy the printed link and change only its address. Some browser features, such as copy buttons and pasting
images, need HTTPS. --mcp works only without --host.
Check and evaluate
Section titled “Check and evaluate”| Command | Does |
|---|---|
reaktiv-workbook check FILE |
Run every cell; exit 1 and list errors if any fail |
reaktiv-workbook evaluate FILE [options] |
Run and print values |
reaktiv-workbook export FILE DIR |
Write charts as images and notes as Markdown |
Options for evaluate:
| Option | Use it to |
|---|---|
--cell balance --cell B3 |
Print only these cells |
--set deposit=900 |
Override an input (a Python literal; strings need quotes: region='"EU"') |
--note plan |
Print a note with its values filled in |
--check |
Exit 1 if a cell fails |
--types [strict] |
Type-check with pyright instead of running |
--json |
Print everything as JSON |
--save out.workbook.py |
Save, with overrides and fresh saved outputs |
--watch [N] |
Keep running and fire timers (stop after N ticks) |
--requirements |
Print the packages the workbook declares |
A good check after any change:
reaktiv-workbook check model.workbook.py # nothing failsreaktiv-workbook evaluate model.workbook.py --cell balance # values look rightreaktiv-workbook evaluate model.workbook.py --set rate_percent=0 --check # edge casesreaktiv-workbook export model.workbook.py out/ # look at the chartsErrors name the cell, line and cause. Cells that fail because they read a failing
cell say caused by B2: fix that one first.
error B2 ZeroDivisionError: float division by zero Cell B2, line 2 return A1 * ((1 + B1) ** months - 1) / B1error B3 ZeroDivisionError: float division by zero caused by B2Running the file directly
Section titled “Running the file directly”python model.workbook.py evaluates the workbook like evaluate; it never starts the
editor.
Safety
Section titled “Safety”The editor listens only on your own computer (unless you
share it on a network) and uses a secret link. Workbook code is
ordinary Python with your permissions, and automatic effects run on startup: open
only workbooks you trust. run mode hides editing but is not a sandbox; the
workbook’s code is still sent to the browser.