Marimo as CLI: linking command line inputs to query parameters with Cyclopts and Pydantic

[liquidcarbon]

I've been playing with this really nice, modern, low-dependency CLI tool called cyclopts.

Turns out it's quite easy to reuse pydantic or dataclass model that I've described for query parameters in #4960 as a CLI model.

The notebook can be used as usual, with interactive inputs, but you also get in-terminal documentation, where you can describe what it does, what inputs it takes and their type, etc.:

Complete example [molab link]:

<side-note> would be nice if molab preview actually took query params! </side-note>

# /// script
# requires-python = ">=3.12"
# dependencies = [
#     "cyclopts==3.24.0",
#     "marimo",
#     "pydantic==2.11.9",
# ]
# ///

import marimo

__generated_with = "0.15.5"
app = marimo.App(width="medium", auto_download=["html"])


@app.cell
def _():
    import marimo as mo
    from cyclopts import App, Parameter
    from pydantic import BaseModel
    from typing import Annotated, Optional

    class Data(BaseModel):
        """Pydantic input model, enriched with CLI annotations"""
        a: Annotated[
            Optional[str], Parameter(name=["-a"], help="word", show_default=True)
        ] = "answer"
        x: Annotated[
            Optional[int],
            Parameter(name=["-x"], help="number", show_default=True),
        ] = 42
    return App, Data, mo


@app.cell
def _(App, Data, mo):
    # set up CLI, propagate these inputs to query params
    cli = App(help="Marimo + Cyclopts CLI")

    @cli.default
    def data_from_cli(data: Data = Data()):
        print(data.model_dump_json(indent=2))
        return data

    if mo.app_meta().mode == "script":
        data_in = cli()
        if not data_in:
            exit()
        qp = mo.query_params()
        for k, v in data_in.model_dump().items():
            qp[k] = v  # set query params from CLI inputs
    return


@app.cell
def _(Data, mo):
    # populate initial UI values from CLI / query params
    data = Data(**mo.query_params().to_dict())
    a_input = mo.ui.text(value=data.a)
    x_input = mo.ui.slider(start=20, stop=50, step=1, value=data.x, show_value=True)
    a_input, x_input
    return a_input, x_input


@app.cell
def _(a_input, x_input):
    # process inputs into outputs
    output = f"{a_input.value} is {x_input.value}"
    print(output)
    return


if __name__ == "__main__":
    app.run()

And now that CLI inputs plug into query params, you can test it programmatically, which might just fit into the use case of testing such notebooks I've been looking for in #5814

Of course, the intermediate step of query parameters is optional, and you can pass the CLI args into UI directly.

What are your thoughts? Should I make a PR adding docs to guides/scripts maybe?

P.S. I'm aware of mo.cli_args - but this option is quite a bit more powerful.