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.
Python artificial-intelligencedagdata-sciencedata-visualizationdataflowdeveloper-toolsmachine-learningnotebookspipelinepythonreactivesqlweb-app
cli: format help message with colors, bold (#8141)
Akshay Agrawalb276cd50b262
diff --git a/marimo/_cli/cli.py b/marimo/_cli/cli.pyindex 68fe89f095..aa7d39cbe9 100644--- a/marimo/_cli/cli.py+++ b/marimo/_cli/cli.py@@ -23,8 +23,9 @@ from marimo._cli.development.commands import developmentfrom marimo._cli.envinfo import get_system_infofrom marimo._cli.export.commands import exportfrom marimo._cli.file_path import validate_name+from marimo._cli.help_formatter import ColoredGroupfrom marimo._cli.parse_args import parse_args-from marimo._cli.print import red+from marimo._cli.print import bright_green, light_blue, redfrom marimo._cli.run_docker import (prompt_run_in_docker_container,)@@ -81,7 +82,7 @@ def _key_value_bullets(items: list[tuple[str, str]]) -> str:lines.append("\b")lines.append(" * "- + key+ + light_blue(key, bold=True)+ _sep(desc)+ " " * (max_length - len(key) + 2)+ desc@@ -94,7 +95,7 @@ main_help_msg = "\n".join("\b","Welcome to marimo!","\b",- "Getting started:",+ bright_green("Getting started:", bold=True),"",_key_value_bullets([@@ -103,7 +104,7 @@ main_help_msg = "\n".join(),"\b","",- "Example usage:",+ bright_green("Example usage:", bold=True),"",_key_value_bullets([@@ -156,6 +157,7 @@ except Exception:@click.group(+ cls=ColoredGroup,help=main_help_msg,context_settings={"help_option_names": ["-h", "--help"],diff --git a/marimo/_cli/config/commands.py b/marimo/_cli/config/commands.pyindex ad93319210..dfb7cf5f1c 100644--- a/marimo/_cli/config/commands.py+++ b/marimo/_cli/config/commands.py@@ -6,6 +6,7 @@ import osimport clickfrom marimo._cli.config.utils import highlight_toml_headers+from marimo._cli.help_formatter import ColoredCommand, ColoredGroupfrom marimo._cli.print import echo, greenfrom marimo._config.manager import (UserConfigManager,@@ -14,12 +15,14 @@ from marimo._config.manager import (from marimo._config.reader import find_nearest_pyproject_toml[email protected](help="""Various commands for the marimo config.""")+ cls=ColoredGroup, help="""Various commands for the marimo config."""+)def config() -> None:pass[email protected](help="""Show the marimo config.""")[email protected](cls=ColoredCommand, help="""Show the marimo config.""")def show() -> None:"""Print out marimo config information.@@ -51,7 +54,7 @@ def show() -> None:echo(highlight_toml_headers(tomlkit.dumps(user_config)))[email protected](help="""Describe the marimo config.""")[email protected](cls=ColoredCommand, help="""Describe the marimo config.""")def describe() -> None:"""Print documentation for all config options."""import inspectdiff --git a/marimo/_cli/development/commands.py b/marimo/_cli/development/commands.pyindex a0897aeab9..606b7ca7b4 100644--- a/marimo/_cli/development/commands.py+++ b/marimo/_cli/development/commands.py@@ -10,6 +10,7 @@ from typing import TYPE_CHECKING, Anyimport click+from marimo._cli.help_formatter import ColoredCommand, ColoredGroupfrom marimo._data.models import DataTypefrom marimo._messaging.errors import Error as MarimoErrorfrom marimo._messaging.notification import NotificationMessage@@ -277,13 +278,15 @@ def _generate_server_api_schema() -> dict[str, Any]:@click.group(- help="""Various commands for the marimo development.""", hidden=True+ cls=ColoredGroup,+ help="""Various commands for the marimo development.""",+ hidden=True,)def development() -> None:pass[email protected](help="""Print the marimo OpenAPI schema""")[email protected](cls=ColoredCommand, help="""Print the marimo OpenAPI schema""")def openapi() -> None:"""Example usage:@@ -297,7 +300,11 @@ def openapi() -> None:)[email protected](help="Various commands for the marimo processes", hidden=True)+ cls=ColoredGroup,+ help="Various commands for the marimo processes",+ hidden=True,+)def ps() -> None:pass@@ -371,7 +378,9 @@ def killall() -> None:@click.command(- help="Inline packages according to PEP 723", name="inline-packages"+ cls=ColoredCommand,+ help="Inline packages according to PEP 723",+ name="inline-packages",)@click.argument("name",@@ -450,7 +459,7 @@ def inline_packages(name: Path) -> None:)[email protected](help="Print all routes")[email protected](cls=ColoredCommand, help="Print all routes")def print_routes() -> None:from starlette.applications import Starlettefrom starlette.routing import Mount, Route, Router@@ -478,7 +487,7 @@ def print_routes() -> None:return[email protected](help="Preview a marimo file as static HTML")[email protected](cls=ColoredCommand, help="Preview a marimo file as static HTML")@click.argument("file_path",required=True,diff --git a/marimo/_cli/export/commands.py b/marimo/_cli/export/commands.pyindex 5d119e4a76..37d8007a9a 100644--- a/marimo/_cli/export/commands.py+++ b/marimo/_cli/export/commands.py@@ -8,8 +8,12 @@ from typing import Callable, Literal, Optionalimport clickfrom marimo._cli.export.cloudflare import create_cloudflare_files+from marimo._cli.help_formatter import ColoredCommand, ColoredGroupfrom marimo._cli.parse_args import parse_args-from marimo._cli.print import echo, green+from marimo._cli.print import (+ echo,+ green,+)from marimo._cli.tools.thumbnails import thumbnailfrom marimo._cli.utils import prompt_to_overwritefrom marimo._dependencies.dependencies import DependencyManager@@ -43,7 +47,9 @@ _sandbox_message = ()[email protected](help="""Export a notebook to various formats.""")+ cls=ColoredGroup, help="""Export a notebook to various formats."""+)def export() -> None:pass@@ -137,6 +143,7 @@ def watch_and_export(@click.command(+ cls=ColoredCommand,help="""Run a notebook and export it as an HTML file.Example:@@ -146,7 +153,7 @@ Example:Optionally pass CLI args to the notebook:marimo export html notebook.py -o notebook.html -- -arg1 foo -arg2 bar-"""+""",)@click.option("--include-code/--no-include-code",@@ -235,6 +242,7 @@ def html(@click.command(+ cls=ColoredCommand,help="""Export a marimo notebook as a flat script, in topological order.@@ -245,7 +253,7 @@ Example:Watch for changes and regenerate the script on modification:marimo export script notebook.py -o notebook.script.py --watch-"""+""",)@click.option("--watch/--no-watch",@@ -313,6 +321,7 @@ def script(@click.command(+ cls=ColoredCommand,help="""Export a marimo notebook as a code fenced Markdown file.@@ -323,7 +332,7 @@ Example:Watch for changes and regenerate the script on modification:marimo export md notebook.py -o notebook.md --watch-"""+""",)@click.option("--watch/--no-watch",@@ -391,6 +400,7 @@ def md(@click.command(+ cls=ColoredCommand,help="""Export a marimo notebook as a Jupyter notebook in topological order.@@ -403,7 +413,7 @@ Watch for changes and regenerate the script on modification:marimo export ipynb notebook.py -o notebook.ipynb --watchRequires nbformat to be installed.-"""+""",)@click.option("--sort",@@ -509,6 +519,7 @@ def ipynb(@click.command(+ cls=ColoredCommand,help="""Export a marimo notebook as a PDF file.Example:@@ -520,7 +531,7 @@ Optionally pass CLI args to the notebook:marimo export pdf notebook.py -o notebook.pdf -- -arg1 foo -arg2 barRequires nbformat and nbconvert to be installed.-"""+""",)@click.option("--include-outputs/--no-include-outputs",@@ -673,6 +684,7 @@ def pdf(@click.command(+ cls=ColoredCommand,help="""Export a notebook as a WASM-powered standalone HTML file.Example:@@ -690,7 +702,7 @@ documentation.In order for this file to be able to run, it must be served over HTTP,and cannot be opened directly from the file system (e.g. file://).-"""+""",)@click.option("-o",diff --git a/marimo/_cli/help_formatter.py b/marimo/_cli/help_formatter.pynew file mode 100644index 0000000000..0e3df3312a--- /dev/null+++ b/marimo/_cli/help_formatter.py@@ -0,0 +1,98 @@+# Copyright 2026 Marimo. All rights reserved.+#+# Colored Click classes for CLI help formatting.+#+# These follow cargo's color conventions:+# - Bold bright green for section headers (Usage:, Options:, Commands:)+# - Bold bright cyan for command/option names++from __future__ import annotations++import click++from marimo._cli.print import bright_green, light_blue+++class ColoredCommand(click.Command):+ """Click Command with colored help output (cargo-style)."""++ def format_usage(+ self, ctx: click.Context, formatter: click.HelpFormatter+ ) -> None:+ pieces = self.collect_usage_pieces(ctx)+ formatter.write_usage(+ ctx.command_path,+ " ".join(pieces),+ bright_green("Usage: ", bold=True),+ )++ def format_options(+ self, ctx: click.Context, formatter: click.HelpFormatter+ ) -> None:+ opts = []+ for param in self.get_params(ctx):+ rv = param.get_help_record(ctx)+ if rv is not None:+ opts.append(rv)++ if opts:+ rows = [(light_blue(opt, bold=True), desc) for opt, desc in opts]+ with formatter.section(bright_green("Options", bold=True)):+ formatter.write_dl(rows)+++class ColoredGroup(click.Group):+ """Click Group with colored help output (cargo-style)."""++ command_class = ColoredCommand++ def format_usage(+ self, ctx: click.Context, formatter: click.HelpFormatter+ ) -> None:+ pieces = self.collect_usage_pieces(ctx)+ formatter.write_usage(+ ctx.command_path,+ " ".join(pieces),+ bright_green("Usage: ", bold=True),+ )++ def format_options(+ self, ctx: click.Context, formatter: click.HelpFormatter+ ) -> None:+ opts = []+ for param in self.get_params(ctx):+ rv = param.get_help_record(ctx)+ if rv is not None:+ opts.append(rv)++ if opts:+ rows = [(light_blue(opt, bold=True), desc) for opt, desc in opts]+ with formatter.section(bright_green("Options", bold=True)):+ formatter.write_dl(rows)++ # Click's MultiCommand.format_options calls format_commands+ # internally, so we must do the same since we're overriding+ # the method completely+ self.format_commands(ctx, formatter)++ def format_commands(+ self, ctx: click.Context, formatter: click.HelpFormatter+ ) -> None:+ """Write all commands with colored names."""+ commands = []+ for subcommand in self.list_commands(ctx):+ cmd = self.get_command(ctx, subcommand)+ if cmd is None or cmd.hidden:+ continue+ commands.append((subcommand, cmd))++ if commands:+ rows = [+ (+ light_blue(subcommand, bold=True),+ cmd.get_short_help_str(),+ )+ for subcommand, cmd in commands+ ]+ with formatter.section(bright_green("Commands", bold=True)):+ formatter.write_dl(rows)diff --git a/marimo/_cli/print.py b/marimo/_cli/print.pyindex 3a2d3097c3..c3e63f1994 100644--- a/marimo/_cli/print.py+++ b/marimo/_cli/print.py@@ -1,10 +1,13 @@# Copyright 2026 Marimo. All rights reserved.+#+# NB: Do not import click top-level. This module is imported in WASM, which+# does not have access to click.from __future__ import annotationsimport osimport sys-from typing import Any, cast+from typing import Any, Protocol, castfrom marimo._config.settings import GLOBAL_SETTINGS@@ -39,55 +42,116 @@ def _supports_color() -> bool:_USE_COLOR = _supports_color()+_ANSI_COLORS = {+ "black": 30,+ "red": 31,+ "green": 32,+ "yellow": 33,+ "blue": 34,+ "magenta": 35,+ "cyan": 36,+ "white": 37,+ "bright_black": 90,+ "bright_red": 91,+ "bright_green": 92,+ "bright_yellow": 93,+ "bright_blue": 94,+ "bright_magenta": 95,+ "bright_cyan": 96,+ "bright_white": 97,+}+++class _StyleFn(Protocol):+ def __call__(+ self,+ text: str,+ *,+ fg: str | None = ...,+ bold: bool = ...,+ dim: bool = ...,+ ) -> str: ...+++def _ansi_style(+ text: str,+ *,+ fg: str | 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:+ codes.append(_ANSI_COLORS[fg])+ if bold:+ codes.append(1)+ if dim:+ codes.append(2)+ if not codes:+ return text+ return f"\033[{';'.join(str(c) for c in codes)}m{text}\033[0m"+++def _noop_style(+ text: str,+ *,+ fg: str | None = None,+ bold: bool = False,+ dim: bool = False,+) -> str:+ del fg, bold, dim+ return text+++def _resolve_style() -> _StyleFn:+ if not _USE_COLOR:+ return _noop_style+ try:+ import click++ return click.style+ except ModuleNotFoundError:+ return _ansi_style+++_style: _StyleFn = _resolve_style()++def bold(text: str) -> str:- return "\033[1m" + text + "\033[0m" if _USE_COLOR else text+ return _style(text, bold=True)def green(text: str, bold: bool = False) -> str:- if not _USE_COLOR:- return text- prefix = "\033[32m" if not bold else "\033[1;32m"- return prefix + text + "\033[0m"+ return _style(text, fg="green", bold=bold)+++def bright_green(text: str, bold: bool = False) -> str:+ return _style(text, fg="bright_green", bold=bold)def yellow(text: str, bold: bool = False) -> str:- if not _USE_COLOR:- return text- prefix = "\033[33m" if not bold else "\033[1;33m"- return prefix + text + "\033[0m"+ return _style(text, fg="yellow", bold=bold)def orange(text: str, bold: bool = False) -> str:- if not _USE_COLOR:- return text- prefix = "\033[33m" if not bold else "\033[1;33m"- return prefix + text + "\033[0m"+ return _style(text, fg="yellow", bold=bold)def red(text: str, bold: bool = False) -> str:- if not _USE_COLOR:- return text- prefix = "\033[31m" if not bold else "\033[1;31m"- return prefix + text + "\033[0m"+ return _style(text, fg="red", bold=bold)def cyan(text: str, bold: bool = False) -> str:- if not _USE_COLOR:- return text- prefix = "\033[94m" if not bold else "\033[1;94m"- return prefix + text + "\033[0m"+ return _style(text, fg="bright_blue", bold=bold)def light_blue(text: str, bold: bool = False) -> str:- if not _USE_COLOR:- return text- prefix = "\033[96m" if not bold else "\033[1;96m"- return prefix + text + "\033[0m"+ return _style(text, fg="bright_cyan", bold=bold)def muted(text: str) -> str:- # Use dark gray (37 is white, 2 is dim) which is more widely supported than 90- return "\033[37;2m" + text + "\033[0m" if _USE_COLOR else text+ return _style(text, fg="white", dim=True)def _echo_or_print(*args: Any, **kwargs: Any) -> None:diff --git a/tests/_cli/test_cli.py b/tests/_cli/test_cli.pyindex 2ee249436c..8d7444fd23 100644--- a/tests/_cli/test_cli.py+++ b/tests/_cli/test_cli.py@@ -258,6 +258,45 @@ def test_cli_help_exit_code() -> None:assert p.returncode == 0+def test_cli_help_colored_output() -> None:+ """Test that help output renders correctly with colored classes."""+ from click.testing import CliRunner++ from marimo._cli.cli import main++ runner = CliRunner()+ result = runner.invoke(main, ["--help"])+ assert result.exit_code == 0+ # Verify key sections appear in output+ assert "Usage:" in result.output or "Usage" in result.output+ assert "Options" in result.output+ assert "Commands" in result.output++ # Test subcommand help as well+ result = runner.invoke(main, ["export", "--help"])+ assert result.exit_code == 0+ assert "Usage" in result.output+ assert "Options" in result.output++ # Test with colors enabled by re-resolving _style to a color-aware+ # implementation. _style is bound once at import time based on+ # _USE_COLOR, so we need to swap it directly.+ import marimo._cli.print as print_module++ original_style = print_module._style+ try:+ print_module._style = print_module._ansi_style+ result_color = runner.invoke(main, ["--help"], color=True)+ assert result_color.exit_code == 0+ # Verify ANSI escape codes are present when colors are enabled+ # \033[ is the ANSI escape sequence prefix+ assert "\033[" in result_color.output, (+ "Expected ANSI color codes in help output"+ )+ finally:+ print_module._style = original_style++def test_cli_edit_none() -> None:# smoke test: makes sure CLI starts and has basic things we expect# helpful for catching issues related to