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.

feat: display startup tips in CLI (#8836)

Péter Gyarmati5b9d2f039951
diff --git a/marimo/_cli/cli.py b/marimo/_cli/cli.py
index 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, red
from marimo._cli.run_docker import (
prompt_run_in_docker_container,
)
+from marimo._cli.tips import choose_startup_tip
from marimo._cli.upgrade import check_for_updates, print_latest_version
from 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.py
new file mode 100644
index 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 options
diff --git a/marimo/_server/api/deps.py b/marimo/_server/api/deps.py
index 0591814ee1..84999c2f17 100644
--- a/marimo/_server/api/deps.py
+++ b/marimo/_server/api/deps.py
@@ -4,6 +4,7 @@ from __future__ import annotations
from typing import TYPE_CHECKING, Any, Optional, Union, cast
from marimo import _loggers as loggers
+from marimo._cli.tips import CliTip
from marimo._config.manager import MarimoConfigManager, ScriptConfigManager
from marimo._server.config import StarletteServerState
from marimo._server.session_manager import SessionManager
@@ -110,6 +111,11 @@ class AppStateBase:
return self.state.enable_auth
return True
+ @property
+ def startup_tip(self) -> CliTip | None:
+ startup_tip = getattr(self.state, "startup_tip", None)
+ return cast(CliTip | None, startup_tip)
+
@property
def html_head(self) -> Optional[str]:
if hasattr(self.state, "html_head"):
diff --git a/marimo/_server/api/lifespans.py b/marimo/_server/api/lifespans.py
index 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.py
index e16a326c87..8c173f64dc 100644
--- a/marimo/_server/config.py
+++ b/marimo/_server/config.py
@@ -8,6 +8,7 @@ if TYPE_CHECKING:
from starlette.datastructures import State
from uvicorn import Server
+ from marimo._cli.tips import CliTip
from marimo._config.manager import MarimoConfigManager
from marimo._server.session_manager import SessionManager
@@ -31,6 +32,7 @@ class StarletteServerStateInit:
mcp_server_enabled: bool
skew_protection: bool
enable_auth: bool
+ startup_tip: CliTip | None = None
def apply(self, state: State) -> None:
for field, value in self.__dict__.items():
diff --git a/marimo/_server/print.py b/marimo/_server/print.py
index 99d87284b1..51a6a2f914 100644
--- a/marimo/_server/print.py
+++ b/marimo/_server/print.py
@@ -5,7 +5,8 @@ import os
import sys
from 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 CliTip
from marimo._config.config import MarimoConfig, MCPConfig
from 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 it
pass
+ 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:
return
diff --git a/marimo/_server/start.py b/marimo/_server/start.py
index 541dca0052..19a358ae51 100644
--- a/marimo/_server/start.py
+++ b/marimo/_server/start.py
@@ -5,7 +5,7 @@ import os
import re
import subprocess
import threading
-from typing import Optional
+from typing import TYPE_CHECKING, Optional
import uvicorn
@@ -39,6 +39,9 @@ from marimo._tracer import LOGGER
from marimo._utils.lifespans import Lifespans
from marimo._utils.net import find_free_port
+if TYPE_CHECKING:
+ from marimo._cli.tips import CliTip
+
DEFAULT_PORT = 2718
PROXY_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.py
new file mode 100644
index 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.py
index ba0f2299df..8c5123bf9e 100644
--- a/tests/_server/test_print.py
+++ b/tests/_server/test_print.py
@@ -5,9 +5,14 @@ import io
from contextlib import redirect_stdout
from unittest.mock import patch
+import pytest
+
+import marimo._cli.print as cli_print
+from marimo._cli.tips import CliTip
from marimo._config.config import merge_default_config
from 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):