Skip to content

A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.

Update `marimo config describe` output to use new config struct (#11373)

Martha Cryan97fd84a1b3c3
diff --git a/marimo/_cli/config/commands.py b/marimo/_cli/config/commands.py
index 5c66b50dc0..46f8878651 100644
--- a/marimo/_cli/config/commands.py
+++ b/marimo/_cli/config/commands.py
@@ -5,7 +5,10 @@ import os
import click
-from marimo._cli.config.utils import highlight_toml_headers
+from marimo._cli.config.utils import (
+ format_config_docs,
+ highlight_toml_headers,
+)
from marimo._cli.help_formatter import ColoredCommand, ColoredGroup
from marimo._cli.print import echo, green
from marimo._config.manager import (
@@ -57,74 +60,9 @@ def show() -> None:
@click.command(cls=ColoredCommand, help="""Describe the marimo config.""")
def describe() -> None:
"""Print documentation for all config options."""
- import inspect
- from textwrap import indent
-
- import marimo._config.config as marimo_config
- from marimo._cli.print import echo, green, muted, yellow
-
- def format_type_docs(cls: type, indent_level: int = 0) -> str:
- """Recursively format type documentation."""
- output: list[str] = []
- # Get annotations and docs from the class
- annotations = (
- cls.__annotations__ if hasattr(cls, "__annotations__") else {}
- )
+ from marimo._config.config_schema import MarimoConfig
- # Get the docstring
- doc = inspect.getdoc(cls)
- if doc and indent_level == 0:
- output.append(muted(f"# {doc}\n"))
-
- for key, type_hint in annotations.items():
- # Get field documentation if available
- if hasattr(type_hint, "__forward_arg__"):
- type_hint = type_hint.__forward_arg__
- # Import from marimo._config.config
- # If NotRequired, we need to get the type from the NotRequired
- if str(type_hint).startswith("NotRequired["):
- type_hint = type_hint[12:-1]
-
- if type_hint in marimo_config.__dict__ and "TypedDict" in str(
- type(marimo_config.__dict__[type_hint])
- ):
- config = marimo_config.__dict__[type_hint]
- field_output = f"[{green(key)}]"
- output.append(indent(field_output, " " * indent_level))
- # Get the docstring for the nested TypedDict
- nested_doc = inspect.getdoc(config)
- if nested_doc:
- output.append(
- indent(
- muted(f"# {nested_doc}"),
- " " * (indent_level + 1),
- )
- )
- output.append("")
- output.append(
- indent(
- format_type_docs(config, indent_level + 1),
- " " * indent_level,
- )
- )
- elif indent_level == 0:
- output.append(f"[{green(key)}]")
- output.append(muted(f"# {type_hint}"))
- output.append("")
- else:
- output.append(
- indent(
- f"{yellow(key)}: {type_hint}", " " * indent_level
- )
- )
- output.append("")
- else:
- field_output = f"{yellow(key)}: {type_hint}"
- output.append(indent(field_output, " " * indent_level))
-
- return "\n".join(output)
-
- echo(format_type_docs(marimo_config.MarimoConfig))
+ echo(format_config_docs(MarimoConfig))
config.add_command(show)
diff --git a/marimo/_cli/config/utils.py b/marimo/_cli/config/utils.py
index 36516050b9..cfc84f4b6e 100644
--- a/marimo/_cli/config/utils.py
+++ b/marimo/_cli/config/utils.py
@@ -1,7 +1,15 @@
# Copyright 2026 Marimo. All rights reserved.
from __future__ import annotations
-from marimo._cli.print import orange
+import inspect
+import types
+from typing import Annotated, Any, Literal, Union, get_args, get_origin
+
+from msgspec import NODEFAULT, UNSET, Meta, UnsetType
+from msgspec.structs import fields
+
+from marimo._cli.print import cyan, green, muted, orange, yellow
+from marimo._config.schema_utils import Config
def highlight_toml_headers(toml_string: str) -> str:
@@ -16,3 +24,112 @@ def highlight_toml_headers(toml_string: str) -> str:
highlighted_lines.append(line)
return "\n".join(highlighted_lines)
+
+
+def _format_type(annotation: Any) -> str:
+ origin = get_origin(annotation)
+ args = get_args(annotation)
+ if origin is Annotated:
+ return _format_type(args[0])
+ if origin in (Union, types.UnionType):
+ return " | ".join(
+ _format_type(arg) for arg in args if arg is not UnsetType
+ )
+ if origin is Literal:
+ return "Literal[" + ", ".join(repr(arg) for arg in args) + "]"
+ if origin is not None:
+ return f"{origin.__name__}[{', '.join(_format_type(arg) for arg in args)}]"
+ if annotation is type(None):
+ return "None"
+ return getattr(annotation, "__name__", str(annotation))
+
+
+def format_config_docs(cls: type[Config]) -> str:
+ """Describe schema fields without loading config or dynamic defaults."""
+ output: list[str] = []
+ if doc := inspect.getdoc(cls):
+ output.extend([doc, ""])
+
+ def format_fields(
+ cls: type[Config], path: str, level: int, experimental: bool = False
+ ) -> None:
+ prefix = " " * level
+ for item in fields(cls):
+ annotation = item.type
+ metadata = Meta()
+ if get_origin(annotation) is Annotated:
+ annotation, *extras = get_args(annotation)
+ metadata = next(
+ (extra for extra in extras if isinstance(extra, Meta)),
+ metadata,
+ )
+ variants = (
+ get_args(annotation)
+ if get_origin(annotation) in (Union, types.UnionType)
+ else (annotation,)
+ )
+ present = [arg for arg in variants if arg is not UnsetType]
+ nested = present[0] if len(present) == 1 else None
+ field_path = (
+ f"{path}.{item.encode_name}" if path else item.encode_name
+ )
+ section = (
+ nested
+ if isinstance(nested, type) and issubclass(nested, Config)
+ else None
+ )
+ extra = metadata.extra or {}
+ is_experimental = (
+ experimental
+ or bool(extra.get("experimental"))
+ or field_path == "experimental"
+ )
+ labels: list[str] = []
+ if extra.get("deprecated"):
+ labels.append(orange("Deprecated"))
+ if is_experimental:
+ labels.append(muted("Experimental"))
+ if extra.get("sensitive"):
+ labels.append(cyan("Sensitive"))
+ name = (
+ green(f"[{field_path}]", bold=True)
+ if section is not None
+ else yellow(field_path)
+ )
+ heading = f"{prefix}{name}"
+ if labels:
+ heading += " (" + ", ".join(labels) + ")"
+ if section is not None and level == 0:
+ heading += " " + muted("─" * 32)
+ output.append(heading)
+ details_prefix = prefix + " "
+ if metadata.description:
+ output.extend(
+ details_prefix + line
+ for line in metadata.description.splitlines()
+ )
+ if section is not None:
+ output.append("")
+ format_fields(section, field_path, level + 1, is_experimental)
+ else:
+ output.append(
+ details_prefix + muted(f"Type: {_format_type(annotation)}")
+ )
+ if item.default is UNSET:
+ output.append("")
+ continue
+ elif item.default is not NODEFAULT:
+ default = repr(item.default)
+ elif item.default_factory in (dict, list):
+ default = repr(item.default_factory())
+ elif item.default_factory is not NODEFAULT:
+ default = "dynamic"
+ else:
+ output.extend([details_prefix + muted("Required"), ""])
+ continue
+ output.extend(
+ [details_prefix + muted(f"Default: {default}"), ""]
+ )
+
+ format_fields(cls, "", 0)
+ return "\n".join(output).rstrip()
diff --git a/marimo/_cli/print.py b/marimo/_cli/print.py
index 56ef7d3ab3..3148d3e7fd 100644
--- a/marimo/_cli/print.py
+++ b/marimo/_cli/print.py
@@ -67,7 +67,7 @@ class _StyleFn(Protocol):
self,
text: str,
*,
- fg: str | None = ...,
+ fg: str | int | None = ...,
bold: bool = ...,
dim: bool = ...,
) -> str: ...
@@ -76,13 +76,15 @@ class _StyleFn(Protocol):
def _ansi_style(
text: str,
*,
- fg: str | None = None,
+ fg: str | int | None = None,
bold: bool = False,
dim: bool = False,
) -> str:
"""Minimal ANSI fallback for environments without click (e.g. WASM)."""
codes: list[int] = []
- if fg and fg in _ANSI_COLORS:
+ if isinstance(fg, int):
+ codes.extend([38, 5, fg])
+ elif fg and fg in _ANSI_COLORS:
codes.append(_ANSI_COLORS[fg])
if bold:
codes.append(1)
@@ -96,7 +98,7 @@ def _ansi_style(
def _noop_style(
text: str,
*,
- fg: str | None = None,
+ fg: str | int | None = None,
bold: bool = False,
dim: bool = False,
) -> str:
@@ -135,7 +137,7 @@ def yellow(text: str, bold: bool = False) -> str:
def orange(text: str, bold: bool = False) -> str:
- return _style(text, fg="yellow", bold=bold)
+ return _style(text, fg=208, bold=bold)
def red(text: str, bold: bool = False) -> str:
diff --git a/tests/_cli/test_cli_config.py b/tests/_cli/test_cli_config.py
index e1e625077b..f6eba09410 100644
--- a/tests/_cli/test_cli_config.py
+++ b/tests/_cli/test_cli_config.py
@@ -4,7 +4,12 @@ from __future__ import annotations
import subprocess
import pytest
+from click.testing import CliRunner
+from inline_snapshot import snapshot
+from marimo._cli.config.commands import config
+from marimo._cli.config.utils import format_config_docs
+from marimo._config.config_schema import MCPServerStdioConfig, SaveConfig
from marimo._utils.platform import is_windows
@@ -26,3 +31,102 @@ def test_config_describe() -> None:
capture_output=True,
)
assert p.returncode == 0, p.stderr.decode()
+
+
+def test_config_describe_field_metadata() -> None:
+ assert format_config_docs(SaveConfig) == snapshot(
+ """\
+Configuration for saving.
+
+autosave
+ one of `"off"` or `"after_delay"`
+ Type: Literal['off', 'after_delay']
+ Default: 'after_delay'
+
+autosave_delay
+ Delay in milliseconds before automatically saving.
+ Type: int
+ Default: 1000
+
+format_on_save
+ if `True`, format the code on save
+ Type: bool
+ Default: False"""
+ )
+
+
+def test_config_describe_nested_and_optional_sections(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ # Describing the schema must not resolve config or environment defaults.
+ monkeypatch.setenv("MARIMO_OUTPUT_MAX_BYTES", "invalid")
+ monkeypatch.setenv("OPENAI_API_KEY", "secret-api-key")
+ result = CliRunner().invoke(config, ["describe"])
+ assert result.exit_code == 0, result.output
+ output = result.output
+ assert " [ai.models]\n" in output
+ assert " [ai.open_ai]\n" in output
+ assert "\n[experimental] (Experimental) " + "─" * 32 + "\n" in output
+ assert "\n[cache] " + "─" * 32 + "\n" in output
+ assert "\n[venv] " + "─" * 32 + "\n" in output
+ assert "Enable live debugging with gutter breakpoints and pdb." in output
+ assert "completion.model (Deprecated)\n" in output
+ assert "completion.api_key (Deprecated, Sensitive)\n" in output
+ assert "completion.codeium_api_key (Sensitive)\n" in output
+ assert "completion.activate_on_typing (Sensitive)" not in output
+ assert "experimental.debugger (Experimental)\n" in output
+ assert "[Deprecated]" not in output
+ assert "[Sensitive]" not in output
+ assert (
+ "Deprecated completion model. Use ai.models.autocomplete_model instead."
+ in output
+ )
+ assert not any(
+ line.lstrip().startswith("#") for line in output.splitlines()
+ )
+ assert "completion.activate_on_typing (Deprecated)" not in output
+ assert (
+ "display.custom_css\n list of paths to custom CSS files\n Type: list[str]"
+ in output
+ )
+ assert (
+ "ai.max_tokens\n the maximum number of tokens to use in AI completions\n Type: int | None"
+ in output
+ )
+ assert "Default: unset" not in output
+ assert "Default: dynamic" in output
+ assert "Default: []" in output
+ assert "Default: {}" in output
+ assert (
+ "dict[str, MCPServerStdioConfig | MCPServerStreamableHttpConfig]"
+ in output
+ )
+ assert "UnsetType" not in output
+ assert "Annotated" not in output
+ assert "ClassVar" not in output
+ assert "__marimo_transport__" not in output
+ assert "secret-api-key" not in output
+
+
+def test_config_describe_required_and_nullable_fields() -> None:
+ assert format_config_docs(MCPServerStdioConfig) == snapshot(
+ """\
+Configuration for STDIO transport MCP servers
+
+command
+ Command used to launch the MCP server.
+ Type: str
+ Required
+
+args
+ Arguments passed to the MCP server command.
+ Type: list[str] | None
+
+env (Sensitive)
+ Environment variables supplied to the MCP server.
+ Type: dict[str, str] | None
+
+disabled
+ Disable this MCP server.
+ Type: bool | None"""
+ )
diff --git a/tests/_cli/test_cli_print.py b/tests/_cli/test_cli_print.py
index 6c130c637f..06294a1df0 100644
--- a/tests/_cli/test_cli_print.py
+++ b/tests/_cli/test_cli_print.py
@@ -4,6 +4,10 @@ from __future__ import annotations
import io
from contextlib import redirect_stderr, redirect_stdout
+import click
+import pytest
+
+from marimo._cli import print as cli_print
from marimo._cli.print import echo
@@ -53,3 +57,19 @@ def test_echo_fallback_uses_stderr_encoding() -> None:
with redirect_stderr(stream):
echo("− err", err=True)
assert _read(stream) == "\\u2212 err\n"
+
+
[email protected]("use_click", [True, False])
+def test_orange_and_yellow_have_distinct_colors(
+ monkeypatch: pytest.MonkeyPatch, use_click: bool
+) -> None:
+ monkeypatch.setattr(
+ cli_print,
+ "_style",
+ click.style if use_click else cli_print._ansi_style,
+ )
+ reset_bold = "\033[22m" if use_click else ""
+ assert cli_print.orange("(Deprecated)") == (
+ f"\033[38;5;208m{reset_bold}(Deprecated)\033[0m"
+ )
+ assert cli_print.yellow("model") == f"\033[33m{reset_bold}model\033[0m"