Skip to content

Marimo CLI Overrides

Runnable experiment notebooks keep defaults in a visible top-level dictionary and call notebooks.marimo_cli.apply_cli_overrides(...). The helper returns a new mapping; it neither mutates nor persists the input.

Invocation

Marimo arguments follow a -- separator:

uv run marimo run notebooks/gridworlds/pursuit/Capture_2_mo.py -- \
  --num-runs=1 \
  --calculate-conv-quick=false

Keys are case-insensitive and normalize hyphens to underscores, so --NUM_AGENTS, --num_agents, and --num-agents all target num_agents. Passing two raw spellings that normalize to the same key raises DuplicateCLIArgumentsError.

String values are coerced with these rules:

  • case-insensitive true, false, and none become Python values;
  • Python literals such as integers, floats, lists, tuples, and quoted strings are parsed with ast.literal_eval;
  • other values remain strings.

Allowed Keys

apply_cli_overrides accepts only keys present in the notebook config mapping. Unknown arguments raise UnknownCLIArgumentsError. Top-level keys retain their ordinary names. A field one level below a mapping uses an underscore-joined alias: for example, --ippo-gamma=1.0, ippo_gamma=1.0, and --IPPO_GAMMA=1.0 override config["ippo"]["gamma"]. The helper copies only the affected nested block, so neither the input mapping nor its algorithm mapping is mutated.

Nested aliases deliberately stop at one level and do not accept arbitrary dotted paths. An alias that collides with a top-level key is rejected rather than resolved implicitly. This keeps scheduled tuning flags visible and typo- checked while allowing isolated optimizer sweeps without editing notebook defaults.

Temporal-game notebooks also expose --reward-mode=objective|handcrafted. Their visible default is objective; a handcrafted training pass remains subject to frozen-policy satisfaction evaluation against the unchanged PLTLF objective.

Every suite notebook must therefore declare all 15 run_* toggles plus the shared verification and resume keys, even when most default to False. See Notebook Algorithm Toggle Coverage.

The lower-level cli_arg(...) helper automatically discovers allowed literal keys from the calling notebook's AST. Discovery recognizes cli_arg(...), the top-level dictionary passed to apply_cli_overrides(...), and keyword arguments to create_base_config(...).

Path And Config Invariants

Notebook config cells call set_cwd_to_project_root() before constructing save_dir. This keeps relative exports rooted in the repository regardless of the launch directory. Experiment helpers normalize save_dir with Path and validate the merged config before training.

When adding a notebook:

  1. Keep all user-tunable top-level values in one literal config mapping.
  2. Include the complete algorithm and verification surface supported by its suite helper.
  3. Keep algorithm hyperparameters in the visible nested blocks; their CLI spelling is <block>-<field>, such as --ippo-ent-coef.
  4. Run uv run marimo check --strict <notebook> and the notebook-config tests.