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.

cli: format help message with colors, bold (#8141)

Akshay Agrawalb276cd50b262
diff --git a/marimo/_cli/cli.py b/marimo/_cli/cli.py
index 68fe89f095..aa7d39cbe9 100644
--- a/marimo/_cli/cli.py
+++ b/marimo/_cli/cli.py
@@ -23,8 +23,9 @@ from marimo._cli.development.commands import development
from marimo._cli.envinfo import get_system_info
from marimo._cli.export.commands import export
from marimo._cli.file_path import validate_name
+from marimo._cli.help_formatter import ColoredGroup
from marimo._cli.parse_args import parse_args
-from marimo._cli.print import red
+from marimo._cli.print import bright_green, light_blue, red
from 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.py
index ad93319210..dfb7cf5f1c 100644
--- a/marimo/_cli/config/commands.py
+++ b/marimo/_cli/config/commands.py
@@ -6,6 +6,7 @@ import os
import click
from marimo._cli.config.utils import highlight_toml_headers
+from marimo._cli.help_formatter import ColoredCommand, ColoredGroup
from marimo._cli.print import echo, green
from 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 inspect
diff --git a/marimo/_cli/development/commands.py b/marimo/_cli/development/commands.py
index a0897aeab9..606b7ca7b4 100644
--- a/marimo/_cli/development/commands.py
+++ b/marimo/_cli/development/commands.py
@@ -10,6 +10,7 @@ from typing import TYPE_CHECKING, Any
import click
+from marimo._cli.help_formatter import ColoredCommand, ColoredGroup
from marimo._data.models import DataType
from marimo._messaging.errors import Error as MarimoError
from 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 Starlette
from 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.py
index 5d119e4a76..37d8007a9a 100644
--- a/marimo/_cli/export/commands.py
+++ b/marimo/_cli/export/commands.py
@@ -8,8 +8,12 @@ from typing import Callable, Literal, Optional
import click
from marimo._cli.export.cloudflare import create_cloudflare_files
+from marimo._cli.help_formatter import ColoredCommand, ColoredGroup
from 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 thumbnail
from marimo._cli.utils import prompt_to_overwrite
from 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 --watch
Requires 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 bar
Requires 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.py
new file mode 100644
index 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.py
index 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 annotations
import os
import sys
-from typing import Any, cast
+from typing import Any, Protocol, cast
from 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.py
index 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