Command line¶
Every noodlelab command, with its options, from noodlelab <command> --help.
noodlelab serve¶
Start the editor, API and admin portal.
usage: noodlelab serve [-h] [--host HOST] [--port PORT] [--home HOME]
[--auth {none,users}] [--no-browser] [--demo]
[--no-sync]
[folder]
positional arguments:
folder open this folder as a workspace
options:
-h, --help show this help message and exit
--host HOST default 127.0.0.1
--port PORT default 8000
--home HOME server state, default ~/.noodlelab
--auth {none,users} default: none on localhost, users otherwise
--no-browser
--demo public demo: no login, no admin, files confined to the
workspace (NOODLELAB_DEMO=1)
--no-sync do not install the plugins the server's lockfile pins
when starting
noodlelab run¶
Run a saved graph without the editor.
usage: noodlelab run [-h] [--home HOME] [--workspace WORKSPACE]
[--no-checkpoints] [--seed SEED] [--target TARGET]
[--no-provenance] [-v] [--run-id RUN_ID]
[--events EVENTS] [--cancel-file CANCEL_FILE]
[--info INFO]
graph
positional arguments:
graph
options:
-h, --help show this help message and exit
--home HOME
--workspace WORKSPACE
--no-checkpoints compute everything
--seed SEED a run seed: random nodes left at their default seed
get seeds derived from it
--target TARGET only run what this node id needs
--no-provenance do not write provenance.json
-v, --verbose
--run-id RUN_ID the run's id (default: a new one)
--events EVENTS append the run's events to this file (JSONL)
--cancel-file CANCEL_FILE
stop between nodes once this file exists
--info INFO JSON added to the run's provenance, e.g. who ran it
noodlelab test¶
Run graphs as tests: checks and baselines, for CI.
usage: noodlelab test [-h] [--home HOME] [--workspace WORKSPACE]
[--no-checkpoints] [--seed SEED] [--rtol RTOL]
[--atol ATOL] [--baseline BASELINE] [--junit JUNIT]
graphs [graphs ...]
positional arguments:
graphs
options:
-h, --help show this help message and exit
--home HOME
--workspace WORKSPACE
--no-checkpoints compute everything
--seed SEED a run seed: random nodes left at their default seed
get seeds derived from it
--rtol RTOL relative tolerance (1e-9)
--atol ATOL absolute tolerance (0)
--baseline BASELINE compare with a run: 'final' (the newest run of the
graph marked final) or a run folder name
--junit JUNIT write a JUnit XML report
noodlelab reproduce¶
Run a recorded run again and check that its results are the same.
usage: noodlelab reproduce [-h] [--home HOME] [--rtol RTOL] [--atol ATOL]
[--json] [--clean-env] [--python PYTHON]
[--requirements REQUIREMENTS]
source
Run a run folder, its provenance.json or a reproducibility bundle (.zip) again
exactly as recorded (same graph, settings and run seed, nothing reused from
caches), and compare every result with the recorded one. Exit code 0 when all
are the same within the tolerances, 1 when some differ (with the likely
causes), 2 when it could not run.
positional arguments:
source run folder, provenance.json or bundle.zip
options:
-h, --help show this help message and exit
--home HOME
--rtol RTOL relative tolerance (1e-9)
--atol ATOL absolute tolerance (0)
--json machine-readable output
--clean-env reproduce in a new environment with the recorded
Python and packages (needs uv)
--python PYTHON with --clean-env: this Python instead of the recorded
--requirements REQUIREMENTS
with --clean-env: install these instead of the
recorded packages
noodlelab plan¶
Lock an analysis plan before the results (preregistration), and check against it.
usage: noodlelab plan [-h] [--home HOME] [--workspace WORKSPACE] [--json]
[--hypothesis HYPOTHESIS] [--primary PRIMARY]
[--note NOTE] [--reason REASON] [--tag]
{lock,status,amend} graph
lock: record the analysis (every node, the requirements and a hash of each
data file, or that it is not there yet) with its hypotheses, next to the graph
(<graph>.plan.json; commit it). status: how the analysis compares with the
plan; exit 1 on a deviation nobody explained. amend: explain the deviations
(--reason).
positional arguments:
{lock,status,amend}
graph
options:
-h, --help show this help message and exit
--home HOME
--workspace WORKSPACE
--json machine-readable output
--hypothesis HYPOTHESIS
what the analysis tests
--primary PRIMARY a primary outcome, NODE:OUTPUT (e.g. 7:result)
--note NOTE anything else to record with the plan
--reason REASON amend: why the analysis deviates from the plan
--tag lock: also tag the git commit
noodlelab signoff¶
Sign a run of a graph as preparer, checker or approver.
usage: noodlelab signoff [-h] [--home HOME] [--workspace WORKSPACE]
[--role {preparer,checker,approver}] [--run RUN]
[--rev REV] [--comment COMMENT] [--list] [--json]
graph
Record who prepared, checked and approved a calculation, bound to a run and to
the analysis, requirements and data as they are now (<graph>.signoff.json).
Any later change voids the sign-off, which noodlelab verify then reports
(NL018).
positional arguments:
graph
options:
-h, --help show this help message and exit
--home HOME
--workspace WORKSPACE
--role {preparer,checker,approver}
--run RUN the run to sign (default: the newest that succeeded)
--rev REV the revision, e.g. B
--comment COMMENT a remark to keep with the signature
--list list the sign-offs and their state
--json with --list: machine-readable
noodlelab verify¶
Run scripts or graphs and audit them: checks, requirements, units, provenance.
usage: noodlelab verify [-h] [--home HOME] [--workspace WORKSPACE]
[--no-checkpoints] [--seed SEED] [--json] [--strict]
[--arg ARGS]
targets [targets ...]
Run Python scripts that use noodlelab.verify.record() and graphs
(.graph.json), or read records written earlier (provenance.json or a folder),
and audit them. Exit code 0 when all pass, 1 when a check fails or is
inconclusive or a requirement was not verified, 2 when a target could not run.
positional arguments:
targets script.py, graph.json or records
options:
-h, --help show this help message and exit
--home HOME
--workspace WORKSPACE
--no-checkpoints compute everything
--seed SEED a run seed: random nodes left at their default seed
get seeds derived from it
--json machine-readable output
--strict warnings fail too
--arg ARGS script argument
noodlelab diff¶
What changed between two runs: inputs, results, checks, code, files, packages.
usage: noodlelab diff [-h] [--rtol RTOL] [--atol ATOL] [--json] run base
Compare two records: run folders or their provenance.json, both from scripts
(noodlelab.verify) or both from graphs. A script's record is compared by its
inputs, results, requirements and checks; a graph run's by its settings, node
code and results. Code, files read and written, Python and packages are
compared for both. Exit code 0 when nothing differs, 1 when something does, 2
when a record cannot be read or the two are of different kinds.
positional arguments:
run the run to look at (folder or provenance.json)
base the earlier run to compare it with
options:
-h, --help show this help message and exit
--rtol RTOL relative tolerance (1e-9)
--atol ATOL absolute tolerance (0)
--json machine-readable output
noodlelab mcp¶
MCP server for AI agents (stdio): build, run and verify graphs and reports.
usage: noodlelab mcp [-h] [--home HOME] [--workspace WORKSPACE]
A Model Context Protocol server on stdin/stdout. Add it to Claude Code with
`claude mcp add noodlelab -- noodlelab mcp`, to Codex CLI with `codex mcp add
noodlelab -- noodlelab mcp`, or run `noodlelab init-agent` in a project.
options:
-h, --help show this help message and exit
--home HOME
--workspace WORKSPACE
default: this folder
noodlelab init-agent¶
Set up a project for AI agents: AGENTS.md, CLAUDE.md, skill and .mcp.json.
usage: noodlelab init-agent [-h] [--command COMMAND_LINE] [--no-claude]
[folder]
positional arguments:
folder
options:
-h, --help show this help message and exit
--command COMMAND_LINE
how agents start the server, quoted as in a shell
(default: noodlelab mcp)
--no-claude skip CLAUDE.md and the skill
noodlelab nodes¶
List installed nodes.
usage: noodlelab nodes [-h] [--json] [--strict]
options:
-h, --help show this help message and exit
--json
--strict apply strict typing rules
noodlelab constants¶
List the named constants: built-in, the workspace’s constants.toml, a graph’s own.
usage: noodlelab constants [-h] [--workspace WORKSPACE] [--json] [graph]
positional arguments:
graph include this graph's constants
options:
-h, --help show this help message and exit
--workspace WORKSPACE
workspace root (default: cwd)
--json
noodlelab tiers¶
Show the installed tier and how to add others.
usage: noodlelab tiers [-h] [--json]
options:
-h, --help show this help message and exit
--json
noodlelab export¶
Export a graph as a Python script.
usage: noodlelab export [-h] [-o OUTPUT] [--workspace WORKSPACE] graph
positional arguments:
graph
options:
-h, --help show this help message and exit
-o OUTPUT, --output OUTPUT
--workspace WORKSPACE
where the graph's file paths start
noodlelab plugins¶
Install, upgrade, remove and check plugins (node packs).
usage: noodlelab plugins [-h]
{list,check,search,info,add,upgrade,remove,sync,lock,test,build-index,init-index,enable,disable}
...
positional arguments:
{list,check,search,info,add,upgrade,remove,sync,lock,test,build-index,init-index,enable,disable}
list installed plugins, their versions and health
check plugin health; exit code 1 if anything is wrong
search search the plugin indexes
info one plugin: installed and available versions
add install plugins and the plugins they require
upgrade upgrade plugins (all, if none are named)
remove uninstall plugins
sync install exactly what the lockfile pins
lock write the lockfile from what is installed
test run plugins' example graphs
build-index build a plugin index from a folder of registrations
init-index scaffold a plugin index repository
enable enable installed plugins
disable disable installed plugins
options:
-h, --help show this help message and exit
noodlelab new-plugin¶
Scaffold a new plugin.
usage: noodlelab new-plugin [-h] [--directory DIRECTORY] name
positional arguments:
name e.g. 'spectroscopy'
options:
-h, --help show this help message and exit
--directory DIRECTORY
noodlelab new-pack¶
Old name of new-plugin.
usage: noodlelab new-pack [-h] [--directory DIRECTORY] name
positional arguments:
name e.g. 'spectroscopy'
options:
-h, --help show this help message and exit
--directory DIRECTORY
noodlelab check-plugin¶
Check a plugin against the plugin standard.
usage: noodlelab check-plugin [-h] [--pack PACK] [--no-examples] target
positional arguments:
target the plugin's folder, or an importable module
options:
-h, --help show this help message and exit
--pack PACK id prefix, for a module
--no-examples do not run the examples
noodlelab check-pack¶
Old name of check-plugin.
usage: noodlelab check-pack [-h] [--pack PACK] [--no-examples] target
positional arguments:
target the plugin's folder, or an importable module
options:
-h, --help show this help message and exit
--pack PACK id prefix, for a module
--no-examples do not run the examples
noodlelab update¶
Look for a newer noodlelab and official plugins, and install them.
usage: noodlelab update [-h] [--home HOME] [--check] [--yes] [--pre]
options:
-h, --help show this help message and exit
--home HOME
--check only say what is newer
--yes, -y install without asking
--pre offer pre-releases too
noodlelab docker-swap¶
==SUPPRESS==.
usage: noodlelab docker-swap [-h] --old OLD --image IMAGE [--within WITHIN]
options:
-h, --help show this help message and exit
--old OLD the container to replace
--image IMAGE the image to run instead
--within WITHIN seconds to become healthy
noodlelab admin-token¶
Print a new admin token.
usage: noodlelab admin-token [-h] [--home HOME]
options:
-h, --help show this help message and exit
--home HOME