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
feat: display startup tips in CLI (#8836)
Péter Gyarmati5b9d2f039951
diff --git a/marimo/_cli/cli.py b/marimo/_cli/cli.pyindex 4c5c54cf6e..7688c2205d 100644--- a/marimo/_cli/cli.py+++ b/marimo/_cli/cli.py@@ -34,6 +34,7 @@ from marimo._cli.print import bright_green, light_blue, redfrom marimo._cli.run_docker import (prompt_run_in_docker_container,)+from marimo._cli.tips import choose_startup_tipfrom marimo._cli.upgrade import check_for_updates, print_latest_versionfrom marimo._cli.utils import (check_app_correctness,@@ -607,6 +608,7 @@ def edit(asset_url=asset_url,timeout=timeout,sandbox_mode=sandbox_mode,+ startup_tip=choose_startup_tip(click.get_current_context()),)@@ -806,6 +808,7 @@ def new(redirect_console_to_browser=True,ttl_seconds=None,timeout=timeout,+ startup_tip=choose_startup_tip(click.get_current_context()),)@@ -1226,6 +1229,7 @@ def run(server_startup_command=server_startup_command,asset_url=asset_url,sandbox_mode=sandbox_mode,+ startup_tip=choose_startup_tip(click.get_current_context()),)@@ -1348,6 +1352,7 @@ def tutorial(),redirect_console_to_browser=False,ttl_seconds=None,+ startup_tip=choose_startup_tip(click.get_current_context()),)diff --git a/marimo/_cli/tips.py b/marimo/_cli/tips.pynew file mode 100644index 0000000000..e61674d189--- /dev/null+++ b/marimo/_cli/tips.py@@ -0,0 +1,199 @@+# Copyright 2026 Marimo. All rights reserved.+from __future__ import annotations++import random+import shlex+import sys+from dataclasses import dataclass+from typing import Final++import click+from click.core import ParameterSource+++@dataclass(frozen=True)+class CliTip:+ text: str+ command: str | None = None+ link: str | None = None+++CLI_STARTUP_TIPS: Final[tuple[CliTip, ...]] = (+ CliTip(+ text="Run a notebook as a web app",+ command="marimo run notebook.py",+ ),+ CliTip(+ text="Reload the editor when the notebook file is edited externally",+ command="marimo edit notebook.py --watch",+ ),+ CliTip(+ text="Run a notebook in an isolated virtual environment",+ command="marimo edit --sandbox notebook.py",+ ),+ CliTip(+ text="Open the intro tutorial",+ command="marimo tutorial intro",+ ),+ CliTip(+ text="Convert a Jupyter notebook to a marimo notebook",+ command="marimo convert notebook.ipynb -o notebook.py",+ ),+ CliTip(+ text="Install shell completions",+ command="marimo shell-completion",+ ),+ CliTip(+ text="Lint and format notebooks",+ command="marimo check --fix .",+ ),+ CliTip(+ text="Generate thumbnails for a folder",+ command="marimo export thumbnail folder/",+ ),+ CliTip(+ text="Coming from Jupyter?",+ link="https://docs.marimo.io/guides/coming_from/jupyter/",+ ),+)+++@dataclass(frozen=True)+class InvocationSignature:+ command_path: tuple[str, ...]+ enabled_options: frozenset[str]+++def choose_startup_tip(+ ctx: click.Context,+ tips: tuple[CliTip, ...] | None = None,+) -> CliTip | None:+ if not sys.stdout.isatty():+ return None++ tips = tips or CLI_STARTUP_TIPS+ current = signature_from_click_context(ctx)+ root = ctx.find_root().command+ if not isinstance(root, click.Group):+ return random.choice(tips)+ relevant = get_relevant_startup_tips(+ tips=tips,+ current=current,+ root=root,+ )+ return random.choice(relevant)+++def get_relevant_startup_tips(+ tips: tuple[CliTip, ...],+ current: InvocationSignature,+ root: click.Group,+) -> tuple[CliTip, ...]:+ relevant = tuple(+ tip for tip in tips if _is_relevant_startup_tip(tip, current, root)+ )++ # If nothing matches, still show a tip instead of showing nothing.+ return relevant or tips+++def signature_from_click_context(ctx: click.Context) -> InvocationSignature:+ contexts = _context_chain(ctx)+ command_path = tuple(+ _context_command_name(context) for context in contexts[1:]+ )+ enabled_options = frozenset(+ option_name+ for context in contexts+ for option_name in _explicitly_set_option_names(context)+ )+ return InvocationSignature(+ command_path=command_path,+ enabled_options=enabled_options,+ )+++def signature_from_command_example(+ root: click.Group,+ command: str,+) -> InvocationSignature | None:+ try:+ tokens = shlex.split(command)+ except ValueError:+ return None++ if tokens and tokens[0] == "marimo":+ tokens = tokens[1:]++ if not tokens:+ return None++ try:+ root_ctx = root.make_context(+ "marimo",+ list(tokens),+ resilient_parsing=True,+ )+ cmd_name, cmd, args = root.resolve_command(root_ctx, list(tokens))+ if cmd is None:+ return None+ sub_ctx = cmd.make_context(+ cmd_name,+ args,+ parent=root_ctx,+ resilient_parsing=True,+ )+ except click.ClickException:+ return None+ except Exception:+ return None++ return signature_from_click_context(sub_ctx)+++def _is_relevant_startup_tip(+ tip: CliTip,+ current: InvocationSignature,+ root: click.Group,+) -> bool:+ if tip.command is None:+ return True++ tip_signature = signature_from_command_example(root, tip.command)+ if tip_signature is None:+ return True++ if tip_signature.command_path != current.command_path:+ return True++ return not tip_signature.enabled_options.issubset(current.enabled_options)+++def _context_chain(ctx: click.Context) -> list[click.Context]:+ chain: list[click.Context] = []+ current: click.Context | None = ctx+ while current is not None:+ chain.append(current)+ current = current.parent+ return list(reversed(chain))+++def _context_command_name(ctx: click.Context) -> str:+ return ctx.command.name or ctx.info_name or ""+++def _explicitly_set_option_names(ctx: click.Context) -> list[str]:+ options: list[str] = []+ for param in ctx.command.params:+ if not isinstance(param, click.Option):+ continue+ if param.name is None:+ continue+ source = ctx.get_parameter_source(param.name)+ if source is None or source == ParameterSource.DEFAULT:+ continue+ value = ctx.params.get(param.name)+ if isinstance(value, bool) and not value:+ continue+ options.append(param.name)+ return optionsdiff --git a/marimo/_server/api/deps.py b/marimo/_server/api/deps.pyindex 0591814ee1..84999c2f17 100644--- a/marimo/_server/api/deps.py+++ b/marimo/_server/api/deps.py@@ -4,6 +4,7 @@ from __future__ import annotationsfrom typing import TYPE_CHECKING, Any, Optional, Union, castfrom marimo import _loggers as loggers+from marimo._cli.tips import CliTipfrom marimo._config.manager import MarimoConfigManager, ScriptConfigManagerfrom marimo._server.config import StarletteServerStatefrom marimo._server.session_manager import SessionManager@@ -110,6 +111,11 @@ class AppStateBase:return self.state.enable_authreturn True+ @property+ def startup_tip(self) -> CliTip | None:+ startup_tip = getattr(self.state, "startup_tip", None)+ return cast(CliTip | None, startup_tip)+@propertydef html_head(self) -> Optional[str]:if hasattr(self.state, "html_head"):diff --git a/marimo/_server/api/lifespans.py b/marimo/_server/api/lifespans.pyindex cd469280bb..7ec81054ee 100644--- a/marimo/_server/api/lifespans.py+++ b/marimo/_server/api/lifespans.py@@ -171,6 +171,7 @@ async def logging(app: Starlette) -> AsyncIterator[None]:run=manager.mode == SessionMode.RUN,new=file_router.get_unique_file_key() == AppFileRouter.NEW_FILE,network=state.host == "0.0.0.0",+ startup_tip=state.startup_tip,)print_experimental_features(state.config_manager.get_config())diff --git a/marimo/_server/config.py b/marimo/_server/config.pyindex e16a326c87..8c173f64dc 100644--- a/marimo/_server/config.py+++ b/marimo/_server/config.py@@ -8,6 +8,7 @@ if TYPE_CHECKING:from starlette.datastructures import Statefrom uvicorn import Server+ from marimo._cli.tips import CliTipfrom marimo._config.manager import MarimoConfigManagerfrom marimo._server.session_manager import SessionManager@@ -31,6 +32,7 @@ class StarletteServerStateInit:mcp_server_enabled: boolskew_protection: boolenable_auth: bool+ startup_tip: CliTip | None = Nonedef apply(self, state: State) -> None:for field, value in self.__dict__.items():diff --git a/marimo/_server/print.py b/marimo/_server/print.pyindex 99d87284b1..51a6a2f914 100644--- a/marimo/_server/print.py+++ b/marimo/_server/print.py@@ -5,7 +5,8 @@ import osimport sysfrom typing import Optional-from marimo._cli.print import bold, green, muted+from marimo._cli.print import bold, green, light_blue, muted, yellow+from marimo._cli.tips import CliTipfrom marimo._config.config import MarimoConfig, MCPConfigfrom marimo._utils.print import print_, print_tabbed@@ -19,7 +20,13 @@ except Exception:def print_startup(- *, file_name: Optional[str], url: str, run: bool, new: bool, network: bool+ *,+ file_name: Optional[str],+ url: str,+ run: bool,+ new: bool,+ network: bool,+ startup_tip: CliTip | None = None,) -> None:print_()if file_name is not None and not run:@@ -48,6 +55,12 @@ def print_startup(except Exception:# If we can't get the network URL, just skip itpass+ if startup_tip is not None:+ print_()+ summary, action = _format_startup_tip(startup_tip)+ print_tabbed(summary)+ if action is not None:+ print_tabbed(action, n_tabs=2)print_()@@ -130,6 +143,21 @@ def _utf8(msg: str) -> str:return msg if UTF8_SUPPORTED else ""+def _format_startup_tip(tip: CliTip) -> tuple[str, str | None]:+ emoji = _utf8("💡")+ label = (+ f"{emoji} {yellow('Tip:', bold=True)}"+ if emoji+ else yellow("Tip:", bold=True)+ )+ summary = f"{label} {tip.text}"+ if tip.command is not None:+ return summary, f"{muted('$')} {light_blue(tip.command)}"+ if tip.link is not None:+ return summary, f"{muted('Guide:')} {light_blue(tip.link)}"+ return summary, None++def print_experimental_features(config: MarimoConfig) -> None:if "experimental" not in config:returndiff --git a/marimo/_server/start.py b/marimo/_server/start.pyindex 541dca0052..19a358ae51 100644--- a/marimo/_server/start.py+++ b/marimo/_server/start.py@@ -5,7 +5,7 @@ import osimport reimport subprocessimport threading-from typing import Optional+from typing import TYPE_CHECKING, Optionalimport uvicorn@@ -39,6 +39,9 @@ from marimo._tracer import LOGGERfrom marimo._utils.lifespans import Lifespansfrom marimo._utils.net import find_free_port+if TYPE_CHECKING:+ from marimo._cli.tips import CliTip+DEFAULT_PORT = 2718PROXY_REGEX = re.compile(r"^(.*):(\d+)$")@@ -183,6 +186,7 @@ def start(asset_url: Optional[str] = None,timeout: Optional[float] = None,sandbox_mode: SandboxMode | None = None,+ startup_tip: CliTip | None = None,) -> None:"""Start the server.@@ -322,6 +326,7 @@ def start(mcp_server_enabled=mcp_enabled,skew_protection=skew_protection,enable_auth=enable_auth,+ startup_tip=startup_tip,)init_state.apply(app.state)diff --git a/tests/_cli/test_tips.py b/tests/_cli/test_tips.pynew file mode 100644index 0000000000..f2436ef1b7--- /dev/null+++ b/tests/_cli/test_tips.py@@ -0,0 +1,141 @@+# Copyright 2026 Marimo. All rights reserved.+from __future__ import annotations++import io+from unittest.mock import patch++import marimo._cli.cli as cli+from marimo._cli.tips import (+ CLI_STARTUP_TIPS,+ CliTip,+ choose_startup_tip,+ get_relevant_startup_tips,+ signature_from_click_context,+ signature_from_command_example,+)+++def _make_subcommand_context(args: list[str]):+ root = cli.main.make_context("marimo", args, resilient_parsing=True)+ cmd_name, cmd, rest = cli.main.resolve_command(root, list(args))+ return cmd.make_context(+ cmd_name, rest, parent=root, resilient_parsing=True+ )+++def test_signature_from_click_context_edit_watch() -> None:+ ctx = _make_subcommand_context(["edit", "notebook.py", "--watch"])+ signature = signature_from_click_context(ctx)+ assert signature.command_path == ("edit",)+ assert signature.enabled_options == frozenset({"watch"})+++def test_signature_from_click_context_root_option_with_value() -> None:+ ctx = _make_subcommand_context(+ ["--log-level", "INFO", "edit", "notebook.py", "--watch"]+ )+ signature = signature_from_click_context(ctx)+ assert signature.command_path == ("edit",)+ assert signature.enabled_options == frozenset({"log_level", "watch"})+++def test_signature_from_click_context_ignores_negated_boolean_flag() -> None:+ ctx = _make_subcommand_context(["edit", "notebook.py", "--no-sandbox"])+ signature = signature_from_click_context(ctx)+ assert signature.command_path == ("edit",)+ assert signature.enabled_options == frozenset()+++def test_signature_from_command_example_edit_watch() -> None:+ signature = signature_from_command_example(+ cli.main, "marimo edit notebook.py --watch"+ )+ assert signature is not None+ assert signature.command_path == ("edit",)+ assert signature.enabled_options == frozenset({"watch"})+++def test_signature_from_command_example_edit_sandbox() -> None:+ signature = signature_from_command_example(+ cli.main, "marimo edit --sandbox notebook.py"+ )+ assert signature is not None+ assert signature.command_path == ("edit",)+ assert signature.enabled_options == frozenset({"sandbox"})+++def test_signature_from_command_example_run() -> None:+ signature = signature_from_command_example(+ cli.main, "marimo run notebook.py"+ )+ assert signature is not None+ assert signature.command_path == ("run",)+ assert signature.enabled_options == frozenset()+++def test_signature_from_command_example_fails_open() -> None:+ assert (+ signature_from_command_example(cli.main, 'marimo run "unterminated')+ is None+ )+++def test_get_relevant_startup_tips_skips_redundant_watch_tip() -> None:+ current = signature_from_click_context(+ _make_subcommand_context(["edit", "notebook.py", "--watch"])+ )+ filtered = get_relevant_startup_tips(CLI_STARTUP_TIPS, current, cli.main)+ assert all(+ tip.command != "marimo edit notebook.py --watch" for tip in filtered+ )+++def test_get_relevant_startup_tips_keeps_watch_tip_without_watch() -> None:+ current = signature_from_click_context(+ _make_subcommand_context(["edit", "notebook.py"])+ )+ filtered = get_relevant_startup_tips(CLI_STARTUP_TIPS, current, cli.main)+ assert any(+ tip.command == "marimo edit notebook.py --watch" for tip in filtered+ )+++def test_get_relevant_startup_tips_keeps_sandbox_tip_with_no_sandbox() -> None:+ current = signature_from_click_context(+ _make_subcommand_context(["edit", "notebook.py", "--no-sandbox"])+ )+ filtered = get_relevant_startup_tips(CLI_STARTUP_TIPS, current, cli.main)+ assert any(+ tip.command == "marimo edit --sandbox notebook.py" for tip in filtered+ )+++def test_get_relevant_startup_tips_skips_redundant_run_tip() -> None:+ current = signature_from_click_context(+ _make_subcommand_context(["run", "notebook.py"])+ )+ filtered = get_relevant_startup_tips(CLI_STARTUP_TIPS, current, cli.main)+ assert all(tip.command != "marimo run notebook.py" for tip in filtered)+++def test_choose_startup_tip_tty_only() -> None:+ ctx = _make_subcommand_context(["edit", "notebook.py"])+ with patch("marimo._cli.tips.sys.stdout", new=io.StringIO()):+ assert choose_startup_tip(ctx) is None+++def test_choose_startup_tip_uses_filtered_pool() -> None:+ class TTYStringIO(io.StringIO):+ def isatty(self) -> bool:+ return True++ ctx = _make_subcommand_context(["edit", "notebook.py", "--watch"])+ with patch("marimo._cli.tips.sys.stdout", new=TTYStringIO()):+ with patch("marimo._cli.tips.random.choice") as mock_choice:+ mock_choice.return_value = CliTip(text="x")+ choose_startup_tip(ctx)+ pool = mock_choice.call_args.args[0]+ assert all(+ tip.command != "marimo edit notebook.py --watch"+ for tip in pool+ )diff --git a/tests/_server/test_print.py b/tests/_server/test_print.pyindex ba0f2299df..8c5123bf9e 100644--- a/tests/_server/test_print.py+++ b/tests/_server/test_print.py@@ -5,9 +5,14 @@ import iofrom contextlib import redirect_stdoutfrom unittest.mock import patch+import pytest++import marimo._cli.print as cli_print+from marimo._cli.tips import CliTipfrom marimo._config.config import merge_default_configfrom marimo._server.print import (_colorized_url,+ _format_startup_tip,_get_network_url,_utf8,print_experimental_features,@@ -16,6 +21,12 @@ from marimo._server.print import ()[email protected](autouse=True)+def _disable_cli_style() -> None:+ with patch.object(cli_print, "_style", cli_print._noop_style):+ yield++def test_utf8() -> None:"""Test the _utf8 function."""# Test with UTF8 supported@@ -93,6 +104,28 @@ def test_get_network_url() -> None:assert result == "http://test-host:8000"+def test_format_startup_tip_with_command() -> None:+ tip = CliTip(+ text="Install shell completions",+ command="marimo shell-completion",+ )+ summary, action = _format_startup_tip(tip)+ assert "Tip: Install shell completions" in summary+ assert action == "$ marimo shell-completion"+++def test_format_startup_tip_with_link() -> None:+ tip = CliTip(+ text="Coming from Jupyter?",+ link="https://docs.marimo.io/guides/coming_from/jupyter/",+ )+ summary, action = _format_startup_tip(tip)+ assert "Tip: Coming from Jupyter?" in summary+ assert action == (+ "Guide: https://docs.marimo.io/guides/coming_from/jupyter/"+ )++def test_print_startup() -> None:"""Test the print_startup function."""# Test with file_name and not run@@ -197,6 +230,95 @@ def test_print_startup() -> None:)+def test_print_startup_prints_tip_after_url() -> None:+ tip = CliTip(+ text="Open the intro tutorial",+ command="marimo tutorial intro",+ )+ with io.StringIO() as buf, redirect_stdout(buf):+ print_startup(+ file_name=None,+ url="http://localhost:8000",+ run=False,+ new=False,+ network=False,+ startup_tip=tip,+ )+ output = buf.getvalue()+ assert "Tip: Open the intro tutorial" in output+ assert "$ marimo tutorial intro" in output+ assert "localhost:8000\n\n " in output+ assert output.index("URL") < output.index(+ "Tip: Open the intro tutorial"+ )+ assert output.index("Tip: Open the intro tutorial") < output.index(+ "$ marimo tutorial intro"+ )+++def test_print_startup_prints_tip_after_network() -> None:+ tip = CliTip(+ text="Run a notebook as a web app",+ command="marimo run notebook.py",+ )+ with io.StringIO() as buf, redirect_stdout(buf):+ with patch(+ "marimo._server.print._get_network_url"+ ) as mock_get_network_url:+ mock_get_network_url.return_value = "http://192.168.1.100:8000"+ print_startup(+ file_name=None,+ url="http://localhost:8000",+ run=False,+ new=False,+ network=True,+ startup_tip=tip,+ )+ output = buf.getvalue()+ assert "Tip: Run a notebook as a web app" in output+ assert "$ marimo run notebook.py" in output+ assert "192.168.1.100:8000\n\n " in output+ assert output.index("URL") < output.index("Network")+ assert output.index("Network") < output.index(+ "Tip: Run a notebook as a web app"+ )+++def test_print_startup_omits_tip_when_none() -> None:+ with io.StringIO() as buf, redirect_stdout(buf):+ print_startup(+ file_name=None,+ url="http://localhost:8000",+ run=False,+ new=False,+ network=False,+ startup_tip=None,+ )+ output = buf.getvalue()+ assert "Tip:" not in output+++def test_print_startup_utf8_tip_fallback_omits_emoji() -> None:+ tip = CliTip(+ text="Install shell completions",+ command="marimo shell-completion",+ )+ with io.StringIO() as buf, redirect_stdout(buf):+ with patch("marimo._server.print.UTF8_SUPPORTED", False):+ print_startup(+ file_name=None,+ url="http://localhost:8000",+ run=False,+ new=False,+ network=False,+ startup_tip=tip,+ )+ output = buf.getvalue()+ assert "Tip: Install shell completions" in output+ assert "$ marimo shell-completion" in output+ assert "💡" not in output++def test_print_shutdown() -> None:"""Test the print_shutdown function."""with io.StringIO() as buf, redirect_stdout(buf):