feat: CLI error UX improvements

[peter-gy]

📝 Summary

Improves CLI error UX so error output is easier to scan, easier to act on, and more consistent across entry points.

Parser errors now do not include full help dump, typo paths suggest likely commands/flags, and dependency failures show pkg manager aware install commands with clear fallback guidance. Runtime/setup failures that were previously surfaced as usage errors were also normalized to runtime-style CLI errors.

🔍 Description of Changes

I used https://github.com/marimo-team/marimo/compare/ms/cli-errors?expand=1 as the starting direction for CLI error normalization and carried over the core idea of moving non-usage failures to structured runtime/dependency errors through shared abstractions.

From there, this PR extends the scope by:

• compact parser UX so parse failures show: error, usage, and --help hint, instead of full command help.
• typo suggestions for unknown commands/subcommands and short-flag mistakes.
• declarative, manager-aware install/follow-up command generation and wires it through dependency-heavy CLI paths (export, thumbnail, convert, sandbox, mcp, upgrade).

Examples

Top-level typo suggestion

# Before
$ marimo xport
Error: No such command 'xport'.
...full help output...

# After
$ marimo xport
error: unrecognized command 'xport'

  tip: a similar command exists: 'export'

Usage: marimo [OPTIONS] COMMAND [ARGS]...
For more information, try '--help'.

Nested command typo suggestion

# Before
$ marimo export hxml
Error: No such command 'hxml'.
...full export help output...

# After
$ marimo export hxml
error: unrecognized command 'hxml'

  tip: a similar command exists: 'html'

Usage: marimo export [OPTIONS] COMMAND [ARGS]...
For more information, try '--help'.

Flag typo handling

# Before
$ marimo edit --hedlss
Error: No such option: --hedlss (Possible options: --headless, --help)
...full edit help output...

# After
$ marimo edit --hedlss
error: unexpected argument '--hedlss' found

  tip: some similar arguments exist: '--headless', '--help'

Usage: marimo edit [OPTIONS] [NAME] [ARGS]...
For more information, try '--help'.

Runtime vs usage error semantics

# Before
$ SHELL= marimo shell-completion
...usage-style failure + help dump...
# exit 2

# After
$ SHELL= marimo shell-completion
Error: Could not determine shell. Please set $SHELL environment variable.
# exit 1

Dependency hints (manager-aware + fallback)

# Before (example: export pdf missing deps)
Error: ... required ...
  Tip: Install with:
    pip install ...

# After
Error: ... required ...

  Tip: Install with:
    <manager-aware command>

  Or with pip:
    python -m pip install ...

  Tip: Alternative:
    marimo export pdf ... --sandbox

MCP / sandbox dependency paths

# Before
single hard-coded install guidance, often usage-error style

# After
structured dependency error with:
- manager-aware install command
- pip fallback
- consistent runtime/dependency error semantics

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
marimo-docs	Ready	Preview, Comment	Feb 22, 2026 11:57am

[peter-gy]

@akshayka while this is not an API change, it is a very close-to-the-user modification, so your feedback would be appreciated!

[dmadisetti]

Nice !

[dmadisetti]

🤔 @peter-gy I think we need to rename that test. Not sure if you are online so I'll do it

[peter-gy]

🤔 @peter-gy I think we need to rename that test. Not sure if you are online so I'll do it

thanks!

[dmadisetti]

Weird. I cannot replicate this failure locally.

[akshayka]

This is quite nice, @peter-gy. I have a couple comments.

1. When is the upgrade message shown? Is it deliberate for it to only show on error?

Right now, I only see the upgrade message on command error:

$ marimo edit --sandbox
Update available 0.19.11 → 0.20.0
Run pixi upgrade marimo to upgrade.
Or run python -m pip install --upgrade marimo.

Error: pyzmq is required when running the marimo edit server on a directory with --sandbox.

  Tip: Install with:

    pixi add 'marimo[sandbox]' pyzmq

  Or with pip:

    python -m pip install 'marimo[sandbox]' pyzmq

2. Error legibility.

When an upgrade is available it takes time for my eyes to scan and find the error message. Could this be improved by putting "Error" in bold red?

3. pyzmq suggested install.

The suggested install for pyzmq looks incorrect. Installing marimo[sandbox] and pyzmq is redundant.`

Instead of

python -m pip install 'marimo[sandbox]' pyzmq

Shouldn't it be

python -m pip install marimo[sandbox] # or python -m pip install pyzmq

[peter-gy]

Thanks for the input @akshayka.

1. When is the upgrade message shown? Is it deliberate for it to only show on error?

Good catch. I changed the order so check_for_updates(...) runs only after edit preflight succeeds (sandbox deps + shared-memory checks), right before start(...). So on setup failures like missing pyzmq, we no longer print the upgrade banner first.

2. Error legibility.

Great point, just made the Error prefix bold red.

3. pyzmq suggested install.

Mm, yes, makes sense. Got rid of redundant pyzmq suggestion.

[akshayka]

@peter-gy thanks for the changes, the messages feel much better now.

One nit:

Instead of splitting the upgrade messages over two sentences, i.e. instead of

Run pixi upgrade marimo to upgrade.
Or run python -m pip install --upgrade marimo.

could we instead have a single sentence

Run pixi upgrade marimo or python -m pip install --upgrade marimo to upgrade.

[peter-gy]

@peter-gy thanks for the changes, the messages feel much better now.

One nit:

Instead of splitting the upgrade messages over two sentences, i.e. instead of

Run pixi upgrade marimo to upgrade.
Or run python -m pip install --upgrade marimo.

could we instead have a single sentence

Run pixi upgrade marimo or python -m pip install --upgrade marimo to upgrade.

The idea of the list-like design was to let each command sit on its own copy-pasteable line, similarly to the suggestions we display for missing dependencies.
I can see the value of the single sentence approach as well though.