Skip to main content

moops

PyPI Open in molab

Easily write Marimo notebooks that work as CLI scripts (and more!) with minimal boilerplate.

Marimo supports notebooks running as CLI scripts, but until now this required maintaining matching input handling implementations.

Using moops, both implementations are merged into one.

Installation

uv add (or pip install) moops

Transition guide

  • Create your argument group: args = moops.Group()
  • Replace your mo.ui usages with using methods of args
  • Add an args.interface call in a cell of its own, preferably near the top, and provide the UI elements to it. This makes the notebook work as a script and adds CLI info to the notebook.

Now your notebook doubles as a CLI script

Agent-assisted migrations

If you use a coding agent, moops includes an agent skill for migrating existing marimo notebooks: migrate-marimo-to-moops.

Install or point your agent at that skill, then ask it to migrate a notebook to moops while preserving the notebook's behavior.

Running notebooks from Python

Notebooks can also be called from Python with moops.run. This is useful for testing notebook logic without launching Marimo, and for reusing notebook logic from other code.

Expose a variable named result from the notebook:

@app.cell
def _(input_text, mode_dropdown):
    result = mode_dropdown.value(input_text.value)
    return (result,)

Then call the notebook module directly:

import moops
from examples.composition import name_casing

result = moops.run(
    name_casing,
    text="Hello World",
    style="snake_case",
)

assert result == "hello_world"

Keyword arguments override moops.Group inputs by their option names, with leading dashes removed and dashes converted to underscores. If no overrides are provided, moops.run uses the notebook defaults.

URL query parameters

In browser notebooks, Group() lets URL query parameters initialize controls and keeps later control changes reflected in the URL.

args = moops.Group()
input_text = args.text(value="", help_text="Input text")
style = args.dropdown(
    ["snake_case", "camel_case"],
    value="snake_case",
    help_text="Output style",
)

Opening the notebook with ?input_text=Hello&style=camel_case initializes those controls from the URL. Query keys use the same names as moops.run keyword arguments. For subgroups, use dot-separated names such as ?casing.style=camel_case.

Variant inputs

Use args.variant() to create branch subgroups controlled by a selector. Branch controls are normal controls and should still be passed to args.interface(); inactive branch controls are disabled automatically, and CLI help groups branch options under selector-specific headings.

source = args.dropdown(
    ["heuristic", "file"],
    value="heuristic",
    option="--source",
    help_text="Seed source",
)
seed = args.variant("seed", source)

budget = seed["heuristic"].number(value=100, help_text="Heuristic budget")
path = seed["file"].text(value="", help_text="Result file")

interface = args.interface(
    source,
    seed["heuristic"].interface(budget),
    seed["file"].interface(path),
)

Pass short_options=True to args.variant() to omit the variant group name from branch CLI options, such as --file-path instead of --seed-file-path. Moops rejects shortened options that would collide.

Presets

Presets save and restore named groups of control values from a JSON file stored next to the calling notebook as <notebook>_presets.json.

get_preset, set_preset = mo.state(None)
args = moops.Group(presets=moops.Presets(get_preset, set_preset))

With presets enabled, the command line shown in the script callout is editable: edit it in place (or paste a different command) and commit to initialize every control from those arguments. Malformed input is reported inline.

Custom notebook controls

Use args.custom() when the notebook needs an interactive control that moops does not wrap directly, while the CLI should use a supported fallback control. The fallback supplies the CLI parser, help text, defaults, and query-parameter format.

build(value) is a factory that constructs the notebook component from the fallback's resolved value. Passing a factory (rather than a pre-built control) lets controls_from recreate the component when the notebook is mirrored into a parent. value(component, fallback) maps the component's value to the fallback's shape.

fallback_slider = args.range_slider(
    start=0,
    stop=100,
    value=[10, 50],
    option="--x-range",
    help_text="X axis range",
)
x_range = args.custom(
    fallback_slider,
    lambda x_range: mo.ui.matplotlib(build_selection_plot(x_range)),
    value=lambda plot, fallback: (
        [plot.value.x_min, plot.value.x_max] if plot.value else fallback.value
    ),
)

Property-based testing

moops.interface_of returns the notebook's Interface, from which .strategy() generates a Hypothesis strategy that produces valid moops.run kwargs by introspecting the notebook's interface — dropdowns yield their allowed keys, switches yield booleans, and text fields yield arbitrary strings.

Hypothesis is an optional dependency, since it is only needed for .strategy(); install it with pip install moops[test] (or just pip install hypothesis).

from examples.composition import name_casing

_name_casing_interface = moops.interface_of(name_casing)
_name_casing_defaults = _name_casing_interface.default


@hypothesis.given(_name_casing_interface.strategy())
def test_name_casing_preserves_alphanumeric_count(kwargs):
    result = moops.run(name_casing, **kwargs)
    input_text = kwargs.get("input_text", _name_casing_defaults["input_text"])
    assert sum(c.isalnum() for c in result) == sum(c.isalnum() for c in input_text)

Running the examples

The examples/ directory is grouped by topic:

  • basics/ — small notebooks covering options, flags, file inputs, dataclass inputs, and status output
  • custom_controls/ — args.custom() and mirroring it via controls_from
  • composition/ — embedding and varying notebooks (embed, variant_embed)
  • game_of_life/ — a worked multi-notebook example
  • passthrough/ — passing values between notebooks

From the project root:

uv run examples/composition/notebook.py
uv run --with matplotlib --with numpy examples/custom_controls/custom_control.py --x-range 30,70

Or uv run marimo edit to run as notebooks.

Feedback welcome

This is an early release — issues, ideas, and pull requests are very welcome on GitHub.

Metadata

Release files for moops 0.17.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for moops 0.17.1
File Size Uploaded Provenance Actions
moops-0.17.1.tar.gz 74.1 kB With provenance Details for moops-0.17.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for moops 0.17.1
File Interpreter ABI Platform Actions
moops-0.17.1-py3-none-any.whl Python 3 none any Details for moops-0.17.1-py3-none-any.whl

Total release size: 158.2 kB

Release files / moops-0.17.1.tar.gz

Download URL moops-0.17.1.tar.gz
Size 74.1 kB
Tags Source
SHA-256 checksum
How to use checksums
960fa65f3ca1e60e022570fab17db9c4eec5ad70f2d5099b73892c1a6cfbdea3
BLAKE2b-256 checksum
How to use checksums
6aa6ca3acee15122b55ef800b988b1fca339eac0c957a17d3df76e7ab7f51acc
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 1, 2026.

Transparency log

Release files / moops-0.17.1-py3-none-any.whl

Download URL moops-0.17.1-py3-none-any.whl
Size 84.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
074b202113633c571623ff3bc7861a35545c2fd72f6e504a49ce84f9b2a0ae1c
BLAKE2b-256 checksum
How to use checksums
e10f8560009e46d266305247c834ca91bb4473bb2d25d7efb163c9c4ebde5c83
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 1, 2026.

Transparency log

Security for moops 0.17.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for moops-0.17.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 1, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.17.1 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page