From 4d6767bc9bd4048dd4d41b4a28fe165dc43d5f85 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 9 Jul 2026 17:10:09 +0000
Subject: [PATCH 1/5] Unify shell/run into a single `plain python` command
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Collapse `plain shell` (interactive REPL + `-c` + piped stdin) and
`plain run <script>` into one command that mirrors the `python`
interpreter, but always runs `plain.runtime.setup()` first:

    plain python              # interactive REPL (banner + SHELL_IMPORT)
    plain python -c "..."     # execute a string, then exit
    plain python script.py    # run a file as __main__
    plain python -            # execute stdin, then exit
    echo ... | plain python   # execute piped input

Enrichment (banner + SHELL_IMPORT auto-imports) stays confined to the
interactive REPL via PYTHONSTARTUP, matching how the interpreter only
honors PYTHONSTARTUP for interactive sessions — `-c`, file, and stdin
modes run code as-is. Args are a flat positional vector like the
interpreter's own argv, so `plain python script.py -c foo` forwards
`-c foo` to the script rather than capturing plain's own option, and
Plain's startup file wins over any user-exported PYTHONSTARTUP. All
interpreter modes run under `sys.executable`.

`plain shell` is kept as a thin shortcut to the interactive REPL (and,
like `plain python`, runs piped stdin with the app configured).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014Ln7AFVxkkJTY78DfRfqWV
---
 .claude/rules/plain.md                        |   5 +-
 plain-oauthserver/tests/conformance/README.md |   2 +-
 plain/plain/agents/.claude/rules/plain.md     |   5 +-
 plain/plain/cli/README.md                     |  41 +++--
 plain/plain/cli/core.py                       |   4 +-
 plain/plain/cli/python.py                     | 154 ++++++++++++++++++
 plain/plain/cli/shell.py                      |  85 ----------
 plain/tests/internal/test_python_cli.py       | 110 +++++++++++++
 8 files changed, 295 insertions(+), 111 deletions(-)
 create mode 100644 plain/plain/cli/python.py
 delete mode 100644 plain/plain/cli/shell.py
 create mode 100644 plain/tests/internal/test_python_cli.py

diff --git a/.claude/rules/plain.md b/.claude/rules/plain.md
index 2c95384e7a..8e023dd089 100644
--- a/.claude/rules/plain.md
+++ b/.claude/rules/plain.md
@@ -114,8 +114,7 @@ Online docs URL pattern: `https://plainframework.com/docs/<pip-name>/<module/pat
 
 - `uv run plain check` — run linting, preflight, migration, and test checks (add `--skip-test` for faster iteration)
 - `uv run plain pre-commit` — `check` plus commit-specific steps (custom commands, uv lock, build)
-- `uv run plain shell` — interactive Python shell with Plain configured (`-c "..."` for one-off commands)
-- `uv run plain run script.py` — run a script with Plain configured
+- `uv run plain python` — Python with Plain configured; like the `python` interpreter (`-c "..."` for one-off commands, `plain python script.py` to run a file, stdin for piped input). `uv run plain shell` is a shortcut to the interactive REPL.
 - `uv run plain request /path` — test HTTP request against the dev database (`--user`, `--method`, `--data`, `--header`, `--status`, `--contains`, `--not-contains`). Add `--json` for context-frugal output — response metadata and trace analysis (query counts, N+1s, span tree), no response body.
 
 ## Debugging and verifying changes
@@ -124,6 +123,6 @@ Don't guess at errors — reproduce them first, read the traceback, then fix wha
 
 - `uv run plain check` — lint, preflight, migration, and test checks in one shot (add `--skip-test` for faster iteration)
 - `uv run plain request /path` — hit a view and see the full error/stacktrace (`--user`, `--status`, `--contains`, `--not-contains`)
-- `uv run plain shell -c "..."` — run a quick snippet to test behavior in isolation
+- `uv run plain python -c "..."` — run a quick snippet to test behavior in isolation
 - `uv run plain test -x -k test_name` — run a specific failing test, stop on first failure
 - `print()` statements — add them, run the code, read the output, then remove before committing
diff --git a/plain-oauthserver/tests/conformance/README.md b/plain-oauthserver/tests/conformance/README.md
index f5f2a5971f..60bad6387e 100644
--- a/plain-oauthserver/tests/conformance/README.md
+++ b/plain-oauthserver/tests/conformance/README.md
@@ -29,7 +29,7 @@ This server only issues **public** clients (PKCE, no secret), so create one
 without a secret:
 
 ```bash
-uv run plain shell -c "
+uv run plain python -c "
 from plain.oauthserver.models import OAuthApplication
 app = OAuthApplication(
     name='Conformance Suite',
diff --git a/plain/plain/agents/.claude/rules/plain.md b/plain/plain/agents/.claude/rules/plain.md
index 2c95384e7a..8e023dd089 100644
--- a/plain/plain/agents/.claude/rules/plain.md
+++ b/plain/plain/agents/.claude/rules/plain.md
@@ -114,8 +114,7 @@ Online docs URL pattern: `https://plainframework.com/docs/<pip-name>/<module/pat
 
 - `uv run plain check` — run linting, preflight, migration, and test checks (add `--skip-test` for faster iteration)
 - `uv run plain pre-commit` — `check` plus commit-specific steps (custom commands, uv lock, build)
-- `uv run plain shell` — interactive Python shell with Plain configured (`-c "..."` for one-off commands)
-- `uv run plain run script.py` — run a script with Plain configured
+- `uv run plain python` — Python with Plain configured; like the `python` interpreter (`-c "..."` for one-off commands, `plain python script.py` to run a file, stdin for piped input). `uv run plain shell` is a shortcut to the interactive REPL.
 - `uv run plain request /path` — test HTTP request against the dev database (`--user`, `--method`, `--data`, `--header`, `--status`, `--contains`, `--not-contains`). Add `--json` for context-frugal output — response metadata and trace analysis (query counts, N+1s, span tree), no response body.
 
 ## Debugging and verifying changes
@@ -124,6 +123,6 @@ Don't guess at errors — reproduce them first, read the traceback, then fix wha
 
 - `uv run plain check` — lint, preflight, migration, and test checks in one shot (add `--skip-test` for faster iteration)
 - `uv run plain request /path` — hit a view and see the full error/stacktrace (`--user`, `--status`, `--contains`, `--not-contains`)
-- `uv run plain shell -c "..."` — run a quick snippet to test behavior in isolation
+- `uv run plain python -c "..."` — run a quick snippet to test behavior in isolation
 - `uv run plain test -x -k test_name` — run a specific failing test, stop on first failure
 - `print()` statements — add them, run the code, read the output, then remove before committing
diff --git a/plain/plain/cli/README.md b/plain/plain/cli/README.md
index cea4cb4887..9675bda7cc 100644
--- a/plain/plain/cli/README.md
+++ b/plain/plain/cli/README.md
@@ -137,41 +137,48 @@ Pass `cls=SettingOption` and `setting="SETTING_NAME"` to any `@click.option`. Th
 
 `SettingOption` cannot be combined with `envvar=` or `default=` — the setting is the single source of truth for both the default value and environment variable resolution.
 
-## Shell
+## Python
 
-The `plain shell` command starts an interactive Python shell with your Plain app already loaded.
+The `plain python` command behaves like the `python` interpreter, but always runs `plain.runtime.setup()` first so your settings, models, and packages are ready. It covers every mode the interpreter does:
 
 ```bash
-$ plain shell
+$ plain python                  # interactive REPL
+$ plain python -c "..."         # execute a string, then exit
+$ plain python script.py        # run a file as __main__
+$ plain python -                # execute stdin, then exit
+$ echo "..." | plain python     # execute piped input
 ```
 
-If you have IPython installed, it will be used automatically. You can also specify an interface explicitly:
+For one-off commands, use the `-c` flag; for scripts, pass the file:
 
 ```bash
-$ plain shell --interface ipython
-$ plain shell --interface bpython
-$ plain shell --interface python
+$ plain python -c "from app.users.models import User; print(User.query.count())"
+$ plain python scripts/import_data.py
 ```
 
-For one-off commands, use the `-c` flag:
+Arguments after the script are passed through as `sys.argv`, just like `python script.py arg1 arg2`.
+
+If you have IPython installed, the REPL uses it automatically. You can also specify an interface explicitly:
 
 ```bash
-$ plain shell -c "from app.users.models import User; print(User.query.count())"
+$ plain python --interface ipython
+$ plain python --interface bpython
+$ plain python --interface python
 ```
 
-### Run a script with app context
+### Shell
 
-The `plain run` command executes a Python script with your app context already set up:
+`plain shell` is a shortcut to the interactive REPL — the same thing as running `plain python` with no arguments. Use it if that name is more familiar:
 
 ```bash
-$ plain run scripts/import_data.py
+$ plain shell
 ```
 
-This is useful for one-off scripts that need access to your models and settings.
+Only the interactive REPL is enriched (see `SHELL_IMPORT` below). The `-c`, file, and stdin modes run your code as-is with nothing auto-imported, matching how `python` only honors `PYTHONSTARTUP` for interactive sessions.
 
 ### SHELL_IMPORT
 
-Customize what gets imported automatically when the shell starts by setting `SHELL_IMPORT` in your settings:
+Customize what gets imported automatically when the interactive REPL starts by setting `SHELL_IMPORT` in your settings:
 
 ```python
 # app/settings.py
@@ -188,7 +195,7 @@ from app.users.models import User
 __all__ = ["Project", "User"]
 ```
 
-Now when you run `plain shell`, those objects will be automatically imported and available.
+Now when you run `plain python` (or `plain shell`), those objects will be automatically imported and available in the interactive REPL.
 
 ## Built-in commands
 
@@ -197,8 +204,8 @@ Plain includes several built-in commands:
 | Command               | Description                              |
 | --------------------- | ---------------------------------------- |
 | `plain check`         | Run core validation checks               |
-| `plain shell`         | Interactive Python shell                 |
-| `plain run <script>`  | Execute a Python script with app context |
+| `plain python`        | Run Python with the app configured       |
+| `plain shell`         | Interactive Python shell (REPL shortcut) |
 | `plain server`        | Production-ready HTTP server             |
 | `plain preflight`     | Validation checks before deployment      |
 | `plain create <name>` | Create a new local package               |
diff --git a/plain/plain/cli/core.py b/plain/plain/cli/core.py
index b5e0c35d01..a35d175d5d 100644
--- a/plain/plain/cli/core.py
+++ b/plain/plain/cli/core.py
@@ -20,12 +20,12 @@
 from .install import install
 from .memory import memory
 from .preflight import preflight_cli
+from .python import python, shell
 from .registry import cli_registry
 from .request import request
 from .scaffold import create
 from .server import server
 from .settings import settings
-from .shell import run, shell
 from .upgrade import upgrade
 from .urls import urls
 from .utils import utils
@@ -57,8 +57,8 @@ def plain_cli() -> None:
 plain_cli.add_command(urls)
 plain_cli.add_command(changelog)
 plain_cli.add_command(settings)
+plain_cli.add_command(python)
 plain_cli.add_command(shell)
-plain_cli.add_command(run)
 plain_cli.add_command(install)
 plain_cli.add_command(upgrade)
 plain_cli.add_command(server)
diff --git a/plain/plain/cli/python.py b/plain/plain/cli/python.py
new file mode 100644
index 0000000000..f67560cc3e
--- /dev/null
+++ b/plain/plain/cli/python.py
@@ -0,0 +1,154 @@
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+
+import click
+
+from plain.cli.runtime import common_command
+
+# Runs in the child interpreter before any user code, so the app is fully
+# configured (settings, packages, etc.) for the -c, file, and stdin modes.
+_SETUP = "import plain.runtime; plain.runtime.setup()"
+
+_STARTUP = os.path.join(os.path.dirname(__file__), "startup.py")
+
+
+def _exit_with(result: subprocess.CompletedProcess) -> None:
+    if result.returncode:
+        sys.exit(result.returncode)
+
+
+def _run_child(body: str, *, argv: list[str]) -> None:
+    """Run setup + `body` in a child interpreter with sys.argv set to `argv`.
+
+    The child inherits our stdin, so `plain python -` and piped input work.
+    """
+    code = f"{_SETUP}; import sys; sys.argv = {argv!r}; {body}"
+    _exit_with(subprocess.run([sys.executable, "-c", code]))
+
+
+def _run_command(command: str, args: list[str]) -> None:
+    """`plain python -c "..."` — execute a string, then exit."""
+    _run_child(
+        f"exec(compile({command!r}, '<string>', 'exec'))",
+        argv=["-c", *args],
+    )
+
+
+def _run_file(script: str, args: list[str]) -> None:
+    """`plain python script.py` — run a file as __main__."""
+    _run_child(
+        f"import runpy; runpy.run_path({script!r}, run_name='__main__')",
+        argv=[script, *args],
+    )
+
+
+def _run_stdin(args: list[str]) -> None:
+    """`plain python -` or piped input — execute stdin, then exit."""
+    _run_child(
+        "exec(compile(sys.stdin.read(), '<stdin>', 'exec'))",
+        argv=["-", *args],
+    )
+
+
+# Each interface runs under the same interpreter (`sys.executable`) that the
+# CLI itself uses, so the REPL sees the project's installed packages.
+_INTERFACES = {
+    "ipython": [sys.executable, "-m", "IPython"],
+    "bpython": [sys.executable, "-m", "bpython"],
+    "python": [sys.executable],
+}
+
+
+def _default_interface() -> list[str]:
+    try:
+        import IPython  # noqa: F401  # ty: ignore[unresolved-import]
+
+        return _INTERFACES["ipython"]
+    except ImportError:
+        return _INTERFACES["python"]
+
+
+def _run_repl(interface: str | None) -> None:
+    """Enriched interactive REPL: banner + SHELL_IMPORT via PYTHONSTARTUP."""
+    interface_list = _INTERFACES[interface] if interface else _default_interface()
+    # Plain's startup file must win over any PYTHONSTARTUP the user has exported,
+    # otherwise the banner + SHELL_IMPORT enrichment is silently replaced.
+    _exit_with(
+        subprocess.run(
+            interface_list,
+            env={**os.environ, "PYTHONSTARTUP": _STARTUP},
+        )
+    )
+
+
+def _repl_or_stdin(interface: str | None) -> None:
+    """Interactive REPL on a tty, else execute piped stdin — both app-configured.
+
+    Piped input can't go through the REPL: PYTHONSTARTUP (and thus the app
+    setup + enrichment) is only honored interactively, so non-tty stdin must
+    run through `_run_stdin`, which sets the app up explicitly.
+    """
+    if sys.stdin.isatty():
+        _run_repl(interface)
+    else:
+        _run_stdin([])
+
+
+_INTERFACE_OPTION = click.option(
+    "-i",
+    "--interface",
+    type=click.Choice(["ipython", "bpython", "python"]),
+    help="Specify an interactive interpreter interface.",
+)
+
+
+@common_command
+@click.command(
+    context_settings={"ignore_unknown_options": True, "allow_interspersed_args": False}
+)
+@_INTERFACE_OPTION
+@click.option(
+    "-c",
+    "--command",
+    help="Program passed in as a string, then exit.",
+)
+@click.argument("args", nargs=-1)
+def python(
+    interface: str | None,
+    command: str | None,
+    args: tuple[str, ...],
+) -> None:
+    """Run Python with the app configured.
+
+    Behaves like the `python` interpreter, but always runs
+    `plain.runtime.setup()` first:
+
+      plain python              # interactive REPL (banner + SHELL_IMPORT)
+      plain python -c "..."     # execute a string, then exit
+      plain python script.py    # run a file as __main__
+      plain python -            # execute stdin, then exit
+    """
+    # `args` is a flat positional vector, like the interpreter's own argv:
+    # the first element names the file (or `-` for stdin), the rest pass through.
+    if command is not None:
+        _run_command(command, list(args))
+    elif args and args[0] == "-":
+        _run_stdin(list(args[1:]))
+    elif args:
+        _run_file(args[0], list(args[1:]))
+    else:
+        _repl_or_stdin(interface)
+
+
+@click.command()
+@_INTERFACE_OPTION
+def shell(interface: str | None) -> None:
+    """Interactive Python shell with your app's objects preloaded.
+
+    Alias for the interactive REPL from `plain python`. Use `plain python`
+    directly for -c, file, and stdin execution.
+    """
+    _repl_or_stdin(interface)
diff --git a/plain/plain/cli/shell.py b/plain/plain/cli/shell.py
deleted file mode 100644
index f54fc37489..0000000000
--- a/plain/plain/cli/shell.py
+++ /dev/null
@@ -1,85 +0,0 @@
-from __future__ import annotations
-
-import os
-import subprocess
-import sys
-
-import click
-
-from plain.cli.runtime import common_command
-
-
-@common_command
-@click.command()
-@click.option(
-    "-i",
-    "--interface",
-    type=click.Choice(["ipython", "bpython", "python"]),
-    help="Specify an interactive interpreter interface.",
-)
-@click.option(
-    "-c",
-    "--command",
-    help="Execute the given command and exit.",
-)
-def shell(interface: str | None, command: str | None) -> None:
-    """Interactive Python shell"""
-
-    if command:
-        # Execute the command and exit
-        before_script = "import plain.runtime; plain.runtime.setup()"
-        full_command = f"{before_script}; {command}"
-        result = subprocess.run(["python", "-c", full_command])
-        if result.returncode:
-            sys.exit(result.returncode)
-        return
-
-    if not sys.stdin.isatty():
-        # Piped/redirected stdin: PYTHONSTARTUP is only honored for interactive
-        # sessions, so call plain.runtime.setup() ourselves before exec'ing the
-        # script piped on stdin. The subprocess inherits stdin from us.
-        wrapper = (
-            "import plain.runtime, sys; plain.runtime.setup(); exec(sys.stdin.read())"
-        )
-        result = subprocess.run(["python", "-c", wrapper])
-        if result.returncode:
-            sys.exit(result.returncode)
-        return
-
-    interface_list: list[str]
-    if interface:
-        interface_list = [interface]
-    else:
-
-        def get_default_interface() -> list[str]:
-            try:
-                import IPython  # noqa: F401  # ty: ignore[unresolved-import]
-
-                return ["python", "-m", "IPython"]
-            except ImportError:
-                pass
-
-            return ["python"]
-
-        interface_list = get_default_interface()
-
-    result = subprocess.run(
-        interface_list,
-        env={
-            "PYTHONSTARTUP": os.path.join(os.path.dirname(__file__), "startup.py"),
-            **os.environ,
-        },
-    )
-    if result.returncode:
-        sys.exit(result.returncode)
-
-
-@click.command()
-@click.argument("script", nargs=1, type=click.Path(exists=True))
-def run(script: str) -> None:
-    """Execute Python scripts with app context"""
-    before_script = "import plain.runtime; plain.runtime.setup()"
-    command = f"{before_script}; exec(open('{script}').read())"
-    result = subprocess.run(["python", "-c", command])
-    if result.returncode:
-        sys.exit(result.returncode)
diff --git a/plain/tests/internal/test_python_cli.py b/plain/tests/internal/test_python_cli.py
new file mode 100644
index 0000000000..c2db696ccb
--- /dev/null
+++ b/plain/tests/internal/test_python_cli.py
@@ -0,0 +1,110 @@
+from __future__ import annotations
+
+import subprocess
+import sys
+from unittest import mock
+
+from click.testing import CliRunner
+
+from plain.cli.python import python, shell
+
+
+def _invoke(command, args):
+    """Invoke a CLI command with subprocess.run stubbed out.
+
+    Returns the list of (cmd, kwargs) passed to subprocess.run so tests can
+    assert which execution path the dispatcher took without spawning a real
+    interpreter.
+    """
+    calls = []
+
+    def fake_run(cmd, **kwargs):
+        calls.append((cmd, kwargs))
+        return subprocess.CompletedProcess(cmd, 0)
+
+    with mock.patch("plain.cli.python.subprocess.run", side_effect=fake_run):
+        result = CliRunner().invoke(command, args, prog_name="plain")
+
+    assert result.exit_code == 0, result.output
+    return calls
+
+
+def _child_body(calls):
+    """The generated `python -c <body>` string for a non-interactive path."""
+    (cmd, _kwargs) = calls[0]
+    assert cmd[:2] == [sys.executable, "-c"]
+    return cmd[2]
+
+
+def test_dash_c_executes_string():
+    body = _child_body(_invoke(python, ["-c", "print(1)"]))
+    assert "plain.runtime.setup()" in body
+    assert "exec(compile('print(1)'" in body
+    assert "sys.argv = ['-c']" in body
+
+
+def test_dash_c_forwards_trailing_args():
+    # `python -c CMD a b` → sys.argv = ['-c', 'a', 'b']; the first positional
+    # must not be swallowed by the `script` argument.
+    body = _child_body(_invoke(python, ["-c", "print(1)", "a", "b"]))
+    assert "sys.argv = ['-c', 'a', 'b']" in body
+
+
+def test_file_runs_as_main_with_args():
+    body = _child_body(_invoke(python, ["script.py", "a", "b"]))
+    assert "plain.runtime.setup()" in body
+    assert "runpy.run_path('script.py', run_name='__main__')" in body
+    assert "sys.argv = ['script.py', 'a', 'b']" in body
+
+
+def test_script_args_colliding_with_options_pass_through():
+    # `plain python script.py -c foo` must forward `-c foo` to the script as
+    # sys.argv, not let click capture `-c` as plain's own --command option.
+    body = _child_body(_invoke(python, ["script.py", "-c", "foo"]))
+    assert "sys.argv = ['script.py', '-c', 'foo']" in body
+
+
+def test_dash_reads_stdin():
+    body = _child_body(_invoke(python, ["-"]))
+    assert "sys.stdin.read()" in body
+    assert "sys.argv = ['-']" in body
+
+
+def test_no_args_non_tty_reads_stdin():
+    # CliRunner provides a non-tty stdin, so bare `plain python` execs stdin
+    # rather than opening a REPL.
+    body = _child_body(_invoke(python, []))
+    assert "sys.stdin.read()" in body
+
+
+def test_shell_tty_launches_enriched_repl():
+    # On a tty, `shell` opens the enriched REPL. Enrichment (banner +
+    # SHELL_IMPORT) is delivered via PYTHONSTARTUP, which only the interactive
+    # interpreter honors — so no `-c` payload.
+    calls = []
+
+    def fake_run(cmd, **kwargs):
+        calls.append((cmd, kwargs))
+        return subprocess.CompletedProcess(cmd, 0)
+
+    fake_stdin = mock.Mock()
+    fake_stdin.isatty.return_value = True
+    assert shell.callback is not None
+    with (
+        mock.patch("plain.cli.python.subprocess.run", side_effect=fake_run),
+        mock.patch("plain.cli.python.sys.stdin", fake_stdin),
+    ):
+        shell.callback(interface=None)
+
+    (cmd, kwargs) = calls[0]
+    assert kwargs["env"]["PYTHONSTARTUP"].endswith("startup.py")
+    assert "-c" not in cmd
+
+
+def test_shell_piped_stdin_runs_setup():
+    # Regression guard (#66): piped input into `shell` must run
+    # plain.runtime.setup() explicitly, since PYTHONSTARTUP is skipped for
+    # non-interactive stdin. CliRunner provides a non-tty stdin.
+    body = _child_body(_invoke(shell, []))
+    assert "plain.runtime.setup()" in body
+    assert "sys.stdin.read()" in body

From 2d18ce85f6015d1cae4dd3e0f83d3cf7ee708a11 Mon Sep 17 00:00:00 2001
From: Dave Gaeddert <dave.gaeddert@gmail.com>
Date: Tue, 14 Jul 2026 22:14:08 -0500
Subject: [PATCH 2/5] Fix plain python argv handling and add -m module mode

Hand-parse the interpreter-style argv instead of using click's option
parser, which kept matching option-shaped tokens after the -c payload
(`plain python -c '...' --interface python` silently consumed both
tokens instead of forwarding them as sys.argv).

Also:
- Add `plain python -m module` via runpy.run_module
- Execute -c/stdin code in a fresh namespace so wrapper imports
  (plain.runtime, sys) don't leak into user globals
- Put the script's directory on sys.path for file mode, like
  `python script.py`
- Clean error + exit 2 for a nonexistent script file instead of a
  runpy traceback
- Set sys.argv before plain.runtime.setup() in the child so setup
  sees the real argv
- Document the supported modes explicitly rather than claiming full
  interpreter parity

Claude-Session: https://claude.ai/code/session_014CgGYyfFCV32412TkQW3x7
---
 .claude/rules/plain.md                    |   2 +-
 plain/plain/agents/.claude/rules/plain.md |   2 +-
 plain/plain/cli/README.md                 |   7 +-
 plain/plain/cli/python.py                 | 129 +++++++++++++++-------
 plain/tests/internal/test_python_cli.py   |  59 ++++++++--
 5 files changed, 148 insertions(+), 51 deletions(-)

diff --git a/.claude/rules/plain.md b/.claude/rules/plain.md
index 8e023dd089..6970118020 100644
--- a/.claude/rules/plain.md
+++ b/.claude/rules/plain.md
@@ -114,7 +114,7 @@ Online docs URL pattern: `https://plainframework.com/docs/<pip-name>/<module/pat
 
 - `uv run plain check` — run linting, preflight, migration, and test checks (add `--skip-test` for faster iteration)
 - `uv run plain pre-commit` — `check` plus commit-specific steps (custom commands, uv lock, build)
-- `uv run plain python` — Python with Plain configured; like the `python` interpreter (`-c "..."` for one-off commands, `plain python script.py` to run a file, stdin for piped input). `uv run plain shell` is a shortcut to the interactive REPL.
+- `uv run plain python` — Python with Plain configured; like the `python` interpreter (`-c "..."` for one-off commands, `-m` for modules, `plain python script.py` to run a file, stdin for piped input). `uv run plain shell` is a shortcut to the interactive REPL.
 - `uv run plain request /path` — test HTTP request against the dev database (`--user`, `--method`, `--data`, `--header`, `--status`, `--contains`, `--not-contains`). Add `--json` for context-frugal output — response metadata and trace analysis (query counts, N+1s, span tree), no response body.
 
 ## Debugging and verifying changes
diff --git a/plain/plain/agents/.claude/rules/plain.md b/plain/plain/agents/.claude/rules/plain.md
index 8e023dd089..6970118020 100644
--- a/plain/plain/agents/.claude/rules/plain.md
+++ b/plain/plain/agents/.claude/rules/plain.md
@@ -114,7 +114,7 @@ Online docs URL pattern: `https://plainframework.com/docs/<pip-name>/<module/pat
 
 - `uv run plain check` — run linting, preflight, migration, and test checks (add `--skip-test` for faster iteration)
 - `uv run plain pre-commit` — `check` plus commit-specific steps (custom commands, uv lock, build)
-- `uv run plain python` — Python with Plain configured; like the `python` interpreter (`-c "..."` for one-off commands, `plain python script.py` to run a file, stdin for piped input). `uv run plain shell` is a shortcut to the interactive REPL.
+- `uv run plain python` — Python with Plain configured; like the `python` interpreter (`-c "..."` for one-off commands, `-m` for modules, `plain python script.py` to run a file, stdin for piped input). `uv run plain shell` is a shortcut to the interactive REPL.
 - `uv run plain request /path` — test HTTP request against the dev database (`--user`, `--method`, `--data`, `--header`, `--status`, `--contains`, `--not-contains`). Add `--json` for context-frugal output — response metadata and trace analysis (query counts, N+1s, span tree), no response body.
 
 ## Debugging and verifying changes
diff --git a/plain/plain/cli/README.md b/plain/plain/cli/README.md
index 9675bda7cc..167e682d27 100644
--- a/plain/plain/cli/README.md
+++ b/plain/plain/cli/README.md
@@ -139,16 +139,19 @@ Pass `cls=SettingOption` and `setting="SETTING_NAME"` to any `@click.option`. Th
 
 ## Python
 
-The `plain python` command behaves like the `python` interpreter, but always runs `plain.runtime.setup()` first so your settings, models, and packages are ready. It covers every mode the interpreter does:
+The `plain python` command supports the common execution modes of the `python` interpreter, but always runs `plain.runtime.setup()` first so your settings, models, and packages are ready:
 
 ```bash
 $ plain python                  # interactive REPL
 $ plain python -c "..."         # execute a string, then exit
+$ plain python -m module        # run a module as __main__
 $ plain python script.py        # run a file as __main__
 $ plain python -                # execute stdin, then exit
 $ echo "..." | plain python     # execute piped input
 ```
 
+These are the supported modes — other interpreter flags (`-O`, `-W`, etc.) aren't emulated and produce an error.
+
 For one-off commands, use the `-c` flag; for scripts, pass the file:
 
 ```bash
@@ -174,7 +177,7 @@ $ plain python --interface python
 $ plain shell
 ```
 
-Only the interactive REPL is enriched (see `SHELL_IMPORT` below). The `-c`, file, and stdin modes run your code as-is with nothing auto-imported, matching how `python` only honors `PYTHONSTARTUP` for interactive sessions.
+Only the interactive REPL is enriched (see `SHELL_IMPORT` below). The `-c`, `-m`, file, and stdin modes run your code as-is with nothing auto-imported, matching how `python` only honors `PYTHONSTARTUP` for interactive sessions.
 
 ### SHELL_IMPORT
 
diff --git a/plain/plain/cli/python.py b/plain/plain/cli/python.py
index f67560cc3e..f9bbe28ade 100644
--- a/plain/plain/cli/python.py
+++ b/plain/plain/cli/python.py
@@ -9,11 +9,15 @@
 from plain.cli.runtime import common_command
 
 # Runs in the child interpreter before any user code, so the app is fully
-# configured (settings, packages, etc.) for the -c, file, and stdin modes.
+# configured (settings, packages, etc.) for the -c, -m, file, and stdin modes.
 _SETUP = "import plain.runtime; plain.runtime.setup()"
 
 _STARTUP = os.path.join(os.path.dirname(__file__), "startup.py")
 
+# User code executes in a fresh namespace so the wrapper's own imports
+# (plain.runtime, sys) don't leak into it — matching `python -c`/stdin.
+_FRESH_GLOBALS = "{'__name__': '__main__'}"
+
 
 def _exit_with(result: subprocess.CompletedProcess) -> None:
     if result.returncode:
@@ -25,21 +29,41 @@ def _run_child(body: str, *, argv: list[str]) -> None:
 
     The child inherits our stdin, so `plain python -` and piped input work.
     """
-    code = f"{_SETUP}; import sys; sys.argv = {argv!r}; {body}"
+    code = f"import sys; sys.argv = {argv!r}; {_SETUP}; {body}"
     _exit_with(subprocess.run([sys.executable, "-c", code]))
 
 
 def _run_command(command: str, args: list[str]) -> None:
     """`plain python -c "..."` — execute a string, then exit."""
     _run_child(
-        f"exec(compile({command!r}, '<string>', 'exec'))",
+        f"exec(compile({command!r}, '<string>', 'exec'), {_FRESH_GLOBALS})",
         argv=["-c", *args],
     )
 
 
+def _run_module(module: str, args: list[str]) -> None:
+    """`plain python -m module` — run a module as __main__."""
+    # alter_sys=True makes runpy point sys.argv[0] at the module's own file,
+    # matching `python -m`.
+    _run_child(
+        f"import runpy; runpy.run_module({module!r}, run_name='__main__', alter_sys=True)",
+        argv=[module, *args],
+    )
+
+
 def _run_file(script: str, args: list[str]) -> None:
     """`plain python script.py` — run a file as __main__."""
+    if not os.path.exists(script):
+        click.echo(
+            f"plain python: can't open file {script!r}: No such file or directory",
+            err=True,
+        )
+        sys.exit(2)
+    # `python script.py` puts the script's directory at sys.path[0]. We prepend
+    # it rather than replace, keeping the cwd on the path for app imports.
+    script_dir = os.path.dirname(os.path.abspath(script))
     _run_child(
+        f"sys.path.insert(0, {script_dir!r}); "
         f"import runpy; runpy.run_path({script!r}, run_name='__main__')",
         argv=[script, *args],
     )
@@ -48,7 +72,7 @@ def _run_file(script: str, args: list[str]) -> None:
 def _run_stdin(args: list[str]) -> None:
     """`plain python -` or piped input — execute stdin, then exit."""
     _run_child(
-        "exec(compile(sys.stdin.read(), '<stdin>', 'exec'))",
+        f"exec(compile(sys.stdin.read(), '<stdin>', 'exec'), {_FRESH_GLOBALS})",
         argv=["-", *args],
     )
 
@@ -97,58 +121,85 @@ def _repl_or_stdin(interface: str | None) -> None:
         _run_stdin([])
 
 
-_INTERFACE_OPTION = click.option(
-    "-i",
-    "--interface",
-    type=click.Choice(["ipython", "bpython", "python"]),
-    help="Specify an interactive interpreter interface.",
-)
-
-
 @common_command
 @click.command(
-    context_settings={"ignore_unknown_options": True, "allow_interspersed_args": False}
-)
-@_INTERFACE_OPTION
-@click.option(
-    "-c",
-    "--command",
-    help="Program passed in as a string, then exit.",
+    add_help_option=False,
+    context_settings={"ignore_unknown_options": True},
 )
-@click.argument("args", nargs=-1)
-def python(
-    interface: str | None,
-    command: str | None,
-    args: tuple[str, ...],
-) -> None:
+@click.argument("args", nargs=-1, type=click.UNPROCESSED)
+@click.pass_context
+def python(ctx: click.Context, args: tuple[str, ...]) -> None:
     """Run Python with the app configured.
 
-    Behaves like the `python` interpreter, but always runs
-    `plain.runtime.setup()` first:
+    Supports the common execution modes of the `python` interpreter, always
+    running `plain.runtime.setup()` first:
 
+    \b
       plain python              # interactive REPL (banner + SHELL_IMPORT)
       plain python -c "..."     # execute a string, then exit
+      plain python -m module    # run a module as __main__
       plain python script.py    # run a file as __main__
       plain python -            # execute stdin, then exit
+
+    Use -i/--interface to pick the REPL (ipython, bpython, python).
     """
-    # `args` is a flat positional vector, like the interpreter's own argv:
-    # the first element names the file (or `-` for stdin), the rest pass through.
-    if command is not None:
-        _run_command(command, list(args))
-    elif args and args[0] == "-":
-        _run_stdin(list(args[1:]))
-    elif args:
-        _run_file(args[0], list(args[1:]))
-    else:
-        _repl_or_stdin(interface)
+    # Hand-parse the leading flags the way the interpreter does: the first
+    # token that names a payload (-c, -m, a file, or -) ends our parsing, and
+    # everything after it passes through untouched as the child's sys.argv.
+    # Click's own option parser can't do that — it keeps matching
+    # option-shaped tokens after the payload.
+    argv = list(args)
+    interface: str | None = None
+    while argv:
+        arg = argv[0]
+        if arg in ("-h", "--help"):
+            click.echo(ctx.get_help())
+            return
+        if arg in ("-i", "--interface") or arg.startswith("--interface="):
+            if "=" in arg:
+                interface = arg.split("=", 1)[1]
+                argv = argv[1:]
+            else:
+                if len(argv) < 2:
+                    ctx.fail(f"Argument expected for the {arg} option")
+                interface = argv[1]
+                argv = argv[2:]
+            if interface not in _INTERFACES:
+                ctx.fail(
+                    f"Invalid interface {interface!r} (choose from {', '.join(_INTERFACES)})"
+                )
+            continue
+        if arg == "-c":
+            if len(argv) < 2:
+                ctx.fail("Argument expected for the -c option")
+            _run_command(argv[1], argv[2:])
+            return
+        if arg == "-m":
+            if len(argv) < 2:
+                ctx.fail("Argument expected for the -m option")
+            _run_module(argv[1], argv[2:])
+            return
+        if arg == "-":
+            _run_stdin(argv[1:])
+            return
+        if arg.startswith("-"):
+            ctx.fail(f"Unknown option: {arg}")
+        _run_file(arg, argv[1:])
+        return
+    _repl_or_stdin(interface)
 
 
 @click.command()
-@_INTERFACE_OPTION
+@click.option(
+    "-i",
+    "--interface",
+    type=click.Choice(["ipython", "bpython", "python"]),
+    help="Specify an interactive interpreter interface.",
+)
 def shell(interface: str | None) -> None:
     """Interactive Python shell with your app's objects preloaded.
 
     Alias for the interactive REPL from `plain python`. Use `plain python`
-    directly for -c, file, and stdin execution.
+    directly for -c, -m, file, and stdin execution.
     """
     _repl_or_stdin(interface)
diff --git a/plain/tests/internal/test_python_cli.py b/plain/tests/internal/test_python_cli.py
index c2db696ccb..361db9eb46 100644
--- a/plain/tests/internal/test_python_cli.py
+++ b/plain/tests/internal/test_python_cli.py
@@ -41,6 +41,8 @@ def test_dash_c_executes_string():
     assert "plain.runtime.setup()" in body
     assert "exec(compile('print(1)'" in body
     assert "sys.argv = ['-c']" in body
+    # User code runs in a fresh namespace, not the wrapper's globals.
+    assert "{'__name__': '__main__'}" in body
 
 
 def test_dash_c_forwards_trailing_args():
@@ -50,18 +52,47 @@ def test_dash_c_forwards_trailing_args():
     assert "sys.argv = ['-c', 'a', 'b']" in body
 
 
-def test_file_runs_as_main_with_args():
-    body = _child_body(_invoke(python, ["script.py", "a", "b"]))
+def test_dash_c_forwards_option_shaped_args():
+    # Everything after the -c payload passes through verbatim, even tokens
+    # that look like plain's own options — matching the interpreter.
+    body = _child_body(
+        _invoke(python, ["-c", "print(1)", "--interface", "python", "-c", "x"])
+    )
+    assert "sys.argv = ['-c', '--interface', 'python', '-c', 'x']" in body
+    assert "exec(compile('print(1)'" in body
+
+
+def test_dash_m_runs_module_as_main():
+    body = _child_body(_invoke(python, ["-m", "app.tasks", "a", "b"]))
+    assert "plain.runtime.setup()" in body
+    assert "runpy.run_module('app.tasks', run_name='__main__', alter_sys=True)" in body
+    assert "sys.argv = ['app.tasks', 'a', 'b']" in body
+
+
+def test_file_runs_as_main_with_args(tmp_path):
+    script = tmp_path / "script.py"
+    script.write_text("print(1)")
+    body = _child_body(_invoke(python, [str(script), "a", "b"]))
     assert "plain.runtime.setup()" in body
-    assert "runpy.run_path('script.py', run_name='__main__')" in body
-    assert "sys.argv = ['script.py', 'a', 'b']" in body
+    assert f"runpy.run_path({str(script)!r}, run_name='__main__')" in body
+    assert f"sys.argv = [{str(script)!r}, 'a', 'b']" in body
+    # The script's directory goes on sys.path, like `python script.py`.
+    assert f"sys.path.insert(0, {str(tmp_path)!r})" in body
 
 
-def test_script_args_colliding_with_options_pass_through():
+def test_file_not_found_is_clean_error():
+    result = CliRunner().invoke(python, ["missing.py"], prog_name="plain")
+    assert result.exit_code == 2
+    assert "can't open file" in result.output
+
+
+def test_script_args_colliding_with_options_pass_through(tmp_path):
     # `plain python script.py -c foo` must forward `-c foo` to the script as
-    # sys.argv, not let click capture `-c` as plain's own --command option.
-    body = _child_body(_invoke(python, ["script.py", "-c", "foo"]))
-    assert "sys.argv = ['script.py', '-c', 'foo']" in body
+    # sys.argv, not treat `-c` as plain's own option.
+    script = tmp_path / "script.py"
+    script.write_text("print(1)")
+    body = _child_body(_invoke(python, [str(script), "-c", "foo"]))
+    assert f"sys.argv = [{str(script)!r}, '-c', 'foo']" in body
 
 
 def test_dash_reads_stdin():
@@ -77,6 +108,18 @@ def test_no_args_non_tty_reads_stdin():
     assert "sys.stdin.read()" in body
 
 
+def test_unknown_option_is_an_error():
+    result = CliRunner().invoke(python, ["-x"], prog_name="plain")
+    assert result.exit_code != 0
+    assert "Unknown option" in result.output
+
+
+def test_help_option():
+    result = CliRunner().invoke(python, ["--help"], prog_name="plain")
+    assert result.exit_code == 0
+    assert "plain python -m module" in result.output
+
+
 def test_shell_tty_launches_enriched_repl():
     # On a tty, `shell` opens the enriched REPL. Enrichment (banner +
     # SHELL_IMPORT) is delivered via PYTHONSTARTUP, which only the interactive

From 7fea2f25efe2251d169388b240d82d4b63eee267 Mon Sep 17 00:00:00 2001
From: Dave Gaeddert <dave.gaeddert@gmail.com>
Date: Tue, 14 Jul 2026 22:24:22 -0500
Subject: [PATCH 3/5] Drop plain python in favor of shell-only design
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Owning a python-interpreter-compatible command meant servicing an
open-ended parity contract (-m, argv grammar, sys.path semantics,
fresh globals) for little payoff: Plain's app setup is self-serve, so
a standalone script just starts with `import plain.runtime;
plain.runtime.setup()` and runs under the plain interpreter. The
wrapper command only saved those two lines.

`plain shell` is now the single command: interactive REPL (enriched
via SHELL_IMPORT), -c for one-off code, and piped stdin. The real
fixes from the python command are kept — sys.executable instead of
bare "python", Plain's PYTHONSTARTUP winning over the user's, fresh
globals for -c/stdin so wrapper imports don't leak, sys.argv set in
the child, and the #66 piped-stdin regression guard. The old
`plain run` stays deleted; scripts self-configure or graduate to
registered CLI commands, which the docs now describe.

Claude-Session: https://claude.ai/code/session_014CgGYyfFCV32412TkQW3x7
---
 .claude/rules/plain.md                        |   4 +-
 plain-oauthserver/tests/conformance/README.md |   2 +-
 plain/plain/agents/.claude/rules/plain.md     |   4 +-
 plain/plain/cli/README.md                     |  78 ++++---
 plain/plain/cli/core.py                       |   3 +-
 plain/plain/cli/python.py                     | 205 ------------------
 plain/plain/cli/shell.py                      | 109 ++++++++++
 plain/tests/internal/test_python_cli.py       | 153 -------------
 plain/tests/internal/test_shell_cli.py        |  81 +++++++
 9 files changed, 234 insertions(+), 405 deletions(-)
 delete mode 100644 plain/plain/cli/python.py
 create mode 100644 plain/plain/cli/shell.py
 delete mode 100644 plain/tests/internal/test_python_cli.py
 create mode 100644 plain/tests/internal/test_shell_cli.py

diff --git a/.claude/rules/plain.md b/.claude/rules/plain.md
index 6970118020..e5e65d1588 100644
--- a/.claude/rules/plain.md
+++ b/.claude/rules/plain.md
@@ -114,7 +114,7 @@ Online docs URL pattern: `https://plainframework.com/docs/<pip-name>/<module/pat
 
 - `uv run plain check` — run linting, preflight, migration, and test checks (add `--skip-test` for faster iteration)
 - `uv run plain pre-commit` — `check` plus commit-specific steps (custom commands, uv lock, build)
-- `uv run plain python` — Python with Plain configured; like the `python` interpreter (`-c "..."` for one-off commands, `-m` for modules, `plain python script.py` to run a file, stdin for piped input). `uv run plain shell` is a shortcut to the interactive REPL.
+- `uv run plain shell` — interactive Python REPL with the app configured (`-c "..."` for one-off code, piped stdin works). For standalone scripts, put `import plain.runtime; plain.runtime.setup()` at the top and run with `uv run python script.py`.
 - `uv run plain request /path` — test HTTP request against the dev database (`--user`, `--method`, `--data`, `--header`, `--status`, `--contains`, `--not-contains`). Add `--json` for context-frugal output — response metadata and trace analysis (query counts, N+1s, span tree), no response body.
 
 ## Debugging and verifying changes
@@ -123,6 +123,6 @@ Don't guess at errors — reproduce them first, read the traceback, then fix wha
 
 - `uv run plain check` — lint, preflight, migration, and test checks in one shot (add `--skip-test` for faster iteration)
 - `uv run plain request /path` — hit a view and see the full error/stacktrace (`--user`, `--status`, `--contains`, `--not-contains`)
-- `uv run plain python -c "..."` — run a quick snippet to test behavior in isolation
+- `uv run plain shell -c "..."` — run a quick snippet to test behavior in isolation
 - `uv run plain test -x -k test_name` — run a specific failing test, stop on first failure
 - `print()` statements — add them, run the code, read the output, then remove before committing
diff --git a/plain-oauthserver/tests/conformance/README.md b/plain-oauthserver/tests/conformance/README.md
index 60bad6387e..f5f2a5971f 100644
--- a/plain-oauthserver/tests/conformance/README.md
+++ b/plain-oauthserver/tests/conformance/README.md
@@ -29,7 +29,7 @@ This server only issues **public** clients (PKCE, no secret), so create one
 without a secret:
 
 ```bash
-uv run plain python -c "
+uv run plain shell -c "
 from plain.oauthserver.models import OAuthApplication
 app = OAuthApplication(
     name='Conformance Suite',
diff --git a/plain/plain/agents/.claude/rules/plain.md b/plain/plain/agents/.claude/rules/plain.md
index 6970118020..e5e65d1588 100644
--- a/plain/plain/agents/.claude/rules/plain.md
+++ b/plain/plain/agents/.claude/rules/plain.md
@@ -114,7 +114,7 @@ Online docs URL pattern: `https://plainframework.com/docs/<pip-name>/<module/pat
 
 - `uv run plain check` — run linting, preflight, migration, and test checks (add `--skip-test` for faster iteration)
 - `uv run plain pre-commit` — `check` plus commit-specific steps (custom commands, uv lock, build)
-- `uv run plain python` — Python with Plain configured; like the `python` interpreter (`-c "..."` for one-off commands, `-m` for modules, `plain python script.py` to run a file, stdin for piped input). `uv run plain shell` is a shortcut to the interactive REPL.
+- `uv run plain shell` — interactive Python REPL with the app configured (`-c "..."` for one-off code, piped stdin works). For standalone scripts, put `import plain.runtime; plain.runtime.setup()` at the top and run with `uv run python script.py`.
 - `uv run plain request /path` — test HTTP request against the dev database (`--user`, `--method`, `--data`, `--header`, `--status`, `--contains`, `--not-contains`). Add `--json` for context-frugal output — response metadata and trace analysis (query counts, N+1s, span tree), no response body.
 
 ## Debugging and verifying changes
@@ -123,6 +123,6 @@ Don't guess at errors — reproduce them first, read the traceback, then fix wha
 
 - `uv run plain check` — lint, preflight, migration, and test checks in one shot (add `--skip-test` for faster iteration)
 - `uv run plain request /path` — hit a view and see the full error/stacktrace (`--user`, `--status`, `--contains`, `--not-contains`)
-- `uv run plain python -c "..."` — run a quick snippet to test behavior in isolation
+- `uv run plain shell -c "..."` — run a quick snippet to test behavior in isolation
 - `uv run plain test -x -k test_name` — run a specific failing test, stop on first failure
 - `print()` statements — add them, run the code, read the output, then remove before committing
diff --git a/plain/plain/cli/README.md b/plain/plain/cli/README.md
index 167e682d27..bc215a6f6e 100644
--- a/plain/plain/cli/README.md
+++ b/plain/plain/cli/README.md
@@ -9,7 +9,7 @@
     - [Mark commands as common](#mark-commands-as-common)
     - [Bridge CLI options to settings](#bridge-cli-options-to-settings)
 - [Shell](#shell)
-    - [Run a script with app context](#run-a-script-with-app-context)
+    - [Standalone scripts](#standalone-scripts)
     - [SHELL_IMPORT](#shell_import)
 - [Built-in commands](#built-in-commands)
 - [FAQs](#faqs)
@@ -137,47 +137,46 @@ Pass `cls=SettingOption` and `setting="SETTING_NAME"` to any `@click.option`. Th
 
 `SettingOption` cannot be combined with `envvar=` or `default=` — the setting is the single source of truth for both the default value and environment variable resolution.
 
-## Python
+## Shell
 
-The `plain python` command supports the common execution modes of the `python` interpreter, but always runs `plain.runtime.setup()` first so your settings, models, and packages are ready:
+The `plain shell` command starts an interactive Python REPL with your app already configured — settings, models, and packages are ready to use:
 
 ```bash
-$ plain python                  # interactive REPL
-$ plain python -c "..."         # execute a string, then exit
-$ plain python -m module        # run a module as __main__
-$ plain python script.py        # run a file as __main__
-$ plain python -                # execute stdin, then exit
-$ echo "..." | plain python     # execute piped input
+$ plain shell
 ```
 
-These are the supported modes — other interpreter flags (`-O`, `-W`, etc.) aren't emulated and produce an error.
-
-For one-off commands, use the `-c` flag; for scripts, pass the file:
+If you have IPython installed, it will be used automatically. You can also specify an interface explicitly:
 
 ```bash
-$ plain python -c "from app.users.models import User; print(User.query.count())"
-$ plain python scripts/import_data.py
+$ plain shell --interface ipython
+$ plain shell --interface bpython
+$ plain shell --interface python
 ```
 
-Arguments after the script are passed through as `sys.argv`, just like `python script.py arg1 arg2`.
-
-If you have IPython installed, the REPL uses it automatically. You can also specify an interface explicitly:
+For one-off code, use the `-c` flag or pipe to stdin:
 
 ```bash
-$ plain python --interface ipython
-$ plain python --interface bpython
-$ plain python --interface python
+$ plain shell -c "from app.users.models import User; print(User.query.count())"
+$ echo "print(User.query.count())" | plain shell
 ```
 
-### Shell
+Only the interactive REPL is enriched (see `SHELL_IMPORT` below). The `-c` and stdin modes run your code as-is with nothing auto-imported, matching how `python` only honors `PYTHONSTARTUP` for interactive sessions.
 
-`plain shell` is a shortcut to the interactive REPL — the same thing as running `plain python` with no arguments. Use it if that name is more familiar:
+### Standalone scripts
 
-```bash
-$ plain shell
+There's no wrapper command for running script files — configure the app yourself at the top of the script:
+
+```python
+import plain.runtime
+
+plain.runtime.setup()
+
+from app.users.models import User
+
+print(User.query.count())
 ```
 
-Only the interactive REPL is enriched (see `SHELL_IMPORT` below). The `-c`, `-m`, file, and stdin modes run your code as-is with nothing auto-imported, matching how `python` only honors `PYTHONSTARTUP` for interactive sessions.
+Then run it like any other Python script (`python scripts/import_data.py`), with normal `sys.argv` behavior for arguments. If a script becomes a keeper, register it as a CLI command instead (see [Adding commands](#adding-commands)).
 
 ### SHELL_IMPORT
 
@@ -198,26 +197,25 @@ from app.users.models import User
 __all__ = ["Project", "User"]
 ```
 
-Now when you run `plain python` (or `plain shell`), those objects will be automatically imported and available in the interactive REPL.
+Now when you run `plain shell`, those objects will be automatically imported and available in the interactive REPL.
 
 ## Built-in commands
 
 Plain includes several built-in commands:
 
-| Command               | Description                              |
-| --------------------- | ---------------------------------------- |
-| `plain check`         | Run core validation checks               |
-| `plain python`        | Run Python with the app configured       |
-| `plain shell`         | Interactive Python shell (REPL shortcut) |
-| `plain server`        | Production-ready HTTP server             |
-| `plain preflight`     | Validation checks before deployment      |
-| `plain create <name>` | Create a new local package               |
-| `plain settings`      | View current settings                    |
-| `plain urls`          | List all URL patterns                    |
-| `plain docs`          | View package documentation               |
-| `plain install`       | Install package dependencies             |
-| `plain upgrade`       | Upgrade Plain packages                   |
-| `plain memory`        | Memory profiling tools                   |
+| Command               | Description                         |
+| --------------------- | ----------------------------------- |
+| `plain check`         | Run core validation checks          |
+| `plain shell`         | Interactive Python shell            |
+| `plain server`        | Production-ready HTTP server        |
+| `plain preflight`     | Validation checks before deployment |
+| `plain create <name>` | Create a new local package          |
+| `plain settings`      | View current settings               |
+| `plain urls`          | List all URL patterns               |
+| `plain docs`          | View package documentation          |
+| `plain install`       | Install package dependencies        |
+| `plain upgrade`       | Upgrade Plain packages              |
+| `plain memory`        | Memory profiling tools              |
 
 Additional commands are added by installed packages (like `plain migrations apply` from plain.postgres).
 
diff --git a/plain/plain/cli/core.py b/plain/plain/cli/core.py
index a35d175d5d..f21278bf88 100644
--- a/plain/plain/cli/core.py
+++ b/plain/plain/cli/core.py
@@ -20,12 +20,12 @@
 from .install import install
 from .memory import memory
 from .preflight import preflight_cli
-from .python import python, shell
 from .registry import cli_registry
 from .request import request
 from .scaffold import create
 from .server import server
 from .settings import settings
+from .shell import shell
 from .upgrade import upgrade
 from .urls import urls
 from .utils import utils
@@ -57,7 +57,6 @@ def plain_cli() -> None:
 plain_cli.add_command(urls)
 plain_cli.add_command(changelog)
 plain_cli.add_command(settings)
-plain_cli.add_command(python)
 plain_cli.add_command(shell)
 plain_cli.add_command(install)
 plain_cli.add_command(upgrade)
diff --git a/plain/plain/cli/python.py b/plain/plain/cli/python.py
deleted file mode 100644
index f9bbe28ade..0000000000
--- a/plain/plain/cli/python.py
+++ /dev/null
@@ -1,205 +0,0 @@
-from __future__ import annotations
-
-import os
-import subprocess
-import sys
-
-import click
-
-from plain.cli.runtime import common_command
-
-# Runs in the child interpreter before any user code, so the app is fully
-# configured (settings, packages, etc.) for the -c, -m, file, and stdin modes.
-_SETUP = "import plain.runtime; plain.runtime.setup()"
-
-_STARTUP = os.path.join(os.path.dirname(__file__), "startup.py")
-
-# User code executes in a fresh namespace so the wrapper's own imports
-# (plain.runtime, sys) don't leak into it — matching `python -c`/stdin.
-_FRESH_GLOBALS = "{'__name__': '__main__'}"
-
-
-def _exit_with(result: subprocess.CompletedProcess) -> None:
-    if result.returncode:
-        sys.exit(result.returncode)
-
-
-def _run_child(body: str, *, argv: list[str]) -> None:
-    """Run setup + `body` in a child interpreter with sys.argv set to `argv`.
-
-    The child inherits our stdin, so `plain python -` and piped input work.
-    """
-    code = f"import sys; sys.argv = {argv!r}; {_SETUP}; {body}"
-    _exit_with(subprocess.run([sys.executable, "-c", code]))
-
-
-def _run_command(command: str, args: list[str]) -> None:
-    """`plain python -c "..."` — execute a string, then exit."""
-    _run_child(
-        f"exec(compile({command!r}, '<string>', 'exec'), {_FRESH_GLOBALS})",
-        argv=["-c", *args],
-    )
-
-
-def _run_module(module: str, args: list[str]) -> None:
-    """`plain python -m module` — run a module as __main__."""
-    # alter_sys=True makes runpy point sys.argv[0] at the module's own file,
-    # matching `python -m`.
-    _run_child(
-        f"import runpy; runpy.run_module({module!r}, run_name='__main__', alter_sys=True)",
-        argv=[module, *args],
-    )
-
-
-def _run_file(script: str, args: list[str]) -> None:
-    """`plain python script.py` — run a file as __main__."""
-    if not os.path.exists(script):
-        click.echo(
-            f"plain python: can't open file {script!r}: No such file or directory",
-            err=True,
-        )
-        sys.exit(2)
-    # `python script.py` puts the script's directory at sys.path[0]. We prepend
-    # it rather than replace, keeping the cwd on the path for app imports.
-    script_dir = os.path.dirname(os.path.abspath(script))
-    _run_child(
-        f"sys.path.insert(0, {script_dir!r}); "
-        f"import runpy; runpy.run_path({script!r}, run_name='__main__')",
-        argv=[script, *args],
-    )
-
-
-def _run_stdin(args: list[str]) -> None:
-    """`plain python -` or piped input — execute stdin, then exit."""
-    _run_child(
-        f"exec(compile(sys.stdin.read(), '<stdin>', 'exec'), {_FRESH_GLOBALS})",
-        argv=["-", *args],
-    )
-
-
-# Each interface runs under the same interpreter (`sys.executable`) that the
-# CLI itself uses, so the REPL sees the project's installed packages.
-_INTERFACES = {
-    "ipython": [sys.executable, "-m", "IPython"],
-    "bpython": [sys.executable, "-m", "bpython"],
-    "python": [sys.executable],
-}
-
-
-def _default_interface() -> list[str]:
-    try:
-        import IPython  # noqa: F401  # ty: ignore[unresolved-import]
-
-        return _INTERFACES["ipython"]
-    except ImportError:
-        return _INTERFACES["python"]
-
-
-def _run_repl(interface: str | None) -> None:
-    """Enriched interactive REPL: banner + SHELL_IMPORT via PYTHONSTARTUP."""
-    interface_list = _INTERFACES[interface] if interface else _default_interface()
-    # Plain's startup file must win over any PYTHONSTARTUP the user has exported,
-    # otherwise the banner + SHELL_IMPORT enrichment is silently replaced.
-    _exit_with(
-        subprocess.run(
-            interface_list,
-            env={**os.environ, "PYTHONSTARTUP": _STARTUP},
-        )
-    )
-
-
-def _repl_or_stdin(interface: str | None) -> None:
-    """Interactive REPL on a tty, else execute piped stdin — both app-configured.
-
-    Piped input can't go through the REPL: PYTHONSTARTUP (and thus the app
-    setup + enrichment) is only honored interactively, so non-tty stdin must
-    run through `_run_stdin`, which sets the app up explicitly.
-    """
-    if sys.stdin.isatty():
-        _run_repl(interface)
-    else:
-        _run_stdin([])
-
-
-@common_command
-@click.command(
-    add_help_option=False,
-    context_settings={"ignore_unknown_options": True},
-)
-@click.argument("args", nargs=-1, type=click.UNPROCESSED)
-@click.pass_context
-def python(ctx: click.Context, args: tuple[str, ...]) -> None:
-    """Run Python with the app configured.
-
-    Supports the common execution modes of the `python` interpreter, always
-    running `plain.runtime.setup()` first:
-
-    \b
-      plain python              # interactive REPL (banner + SHELL_IMPORT)
-      plain python -c "..."     # execute a string, then exit
-      plain python -m module    # run a module as __main__
-      plain python script.py    # run a file as __main__
-      plain python -            # execute stdin, then exit
-
-    Use -i/--interface to pick the REPL (ipython, bpython, python).
-    """
-    # Hand-parse the leading flags the way the interpreter does: the first
-    # token that names a payload (-c, -m, a file, or -) ends our parsing, and
-    # everything after it passes through untouched as the child's sys.argv.
-    # Click's own option parser can't do that — it keeps matching
-    # option-shaped tokens after the payload.
-    argv = list(args)
-    interface: str | None = None
-    while argv:
-        arg = argv[0]
-        if arg in ("-h", "--help"):
-            click.echo(ctx.get_help())
-            return
-        if arg in ("-i", "--interface") or arg.startswith("--interface="):
-            if "=" in arg:
-                interface = arg.split("=", 1)[1]
-                argv = argv[1:]
-            else:
-                if len(argv) < 2:
-                    ctx.fail(f"Argument expected for the {arg} option")
-                interface = argv[1]
-                argv = argv[2:]
-            if interface not in _INTERFACES:
-                ctx.fail(
-                    f"Invalid interface {interface!r} (choose from {', '.join(_INTERFACES)})"
-                )
-            continue
-        if arg == "-c":
-            if len(argv) < 2:
-                ctx.fail("Argument expected for the -c option")
-            _run_command(argv[1], argv[2:])
-            return
-        if arg == "-m":
-            if len(argv) < 2:
-                ctx.fail("Argument expected for the -m option")
-            _run_module(argv[1], argv[2:])
-            return
-        if arg == "-":
-            _run_stdin(argv[1:])
-            return
-        if arg.startswith("-"):
-            ctx.fail(f"Unknown option: {arg}")
-        _run_file(arg, argv[1:])
-        return
-    _repl_or_stdin(interface)
-
-
-@click.command()
-@click.option(
-    "-i",
-    "--interface",
-    type=click.Choice(["ipython", "bpython", "python"]),
-    help="Specify an interactive interpreter interface.",
-)
-def shell(interface: str | None) -> None:
-    """Interactive Python shell with your app's objects preloaded.
-
-    Alias for the interactive REPL from `plain python`. Use `plain python`
-    directly for -c, -m, file, and stdin execution.
-    """
-    _repl_or_stdin(interface)
diff --git a/plain/plain/cli/shell.py b/plain/plain/cli/shell.py
new file mode 100644
index 0000000000..534de3b0c7
--- /dev/null
+++ b/plain/plain/cli/shell.py
@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+
+import click
+
+from plain.cli.runtime import common_command
+
+# Runs in the child interpreter before any user code, so the app is fully
+# configured (settings, packages, etc.) for the -c and stdin modes.
+_SETUP = "import plain.runtime; plain.runtime.setup()"
+
+_STARTUP = os.path.join(os.path.dirname(__file__), "startup.py")
+
+# User code executes in a fresh namespace so the wrapper's own imports
+# (plain.runtime, sys) don't leak into it.
+_FRESH_GLOBALS = "{'__name__': '__main__'}"
+
+
+def _exit_with(result: subprocess.CompletedProcess) -> None:
+    if result.returncode:
+        sys.exit(result.returncode)
+
+
+def _run_child(body: str, *, argv: list[str]) -> None:
+    """Run setup + `body` in a child interpreter with sys.argv set to `argv`.
+
+    The child inherits our stdin, so piped input works.
+    """
+    code = f"import sys; sys.argv = {argv!r}; {_SETUP}; {body}"
+    _exit_with(subprocess.run([sys.executable, "-c", code]))
+
+
+def _run_command(command: str) -> None:
+    """`plain shell -c "..."` — execute a string, then exit."""
+    _run_child(
+        f"exec(compile({command!r}, '<string>', 'exec'), {_FRESH_GLOBALS})",
+        argv=["-c"],
+    )
+
+
+def _run_stdin() -> None:
+    """Piped input — execute stdin, then exit."""
+    _run_child(
+        f"exec(compile(sys.stdin.read(), '<stdin>', 'exec'), {_FRESH_GLOBALS})",
+        argv=["-"],
+    )
+
+
+# Each interface runs under the same interpreter (`sys.executable`) that the
+# CLI itself uses, so the REPL sees the project's installed packages.
+_INTERFACES = {
+    "ipython": [sys.executable, "-m", "IPython"],
+    "bpython": [sys.executable, "-m", "bpython"],
+    "python": [sys.executable],
+}
+
+
+def _default_interface() -> list[str]:
+    try:
+        import IPython  # noqa: F401  # ty: ignore[unresolved-import]
+
+        return _INTERFACES["ipython"]
+    except ImportError:
+        return _INTERFACES["python"]
+
+
+def _run_repl(interface: str | None) -> None:
+    """Enriched interactive REPL: banner + SHELL_IMPORT via PYTHONSTARTUP."""
+    interface_list = _INTERFACES[interface] if interface else _default_interface()
+    # Plain's startup file must win over any PYTHONSTARTUP the user has exported,
+    # otherwise the banner + SHELL_IMPORT enrichment is silently replaced.
+    _exit_with(
+        subprocess.run(
+            interface_list,
+            env={**os.environ, "PYTHONSTARTUP": _STARTUP},
+        )
+    )
+
+
+@common_command
+@click.command()
+@click.option(
+    "-i",
+    "--interface",
+    type=click.Choice(["ipython", "bpython", "python"]),
+    help="Specify an interactive interpreter interface.",
+)
+@click.option(
+    "-c",
+    "--command",
+    help="Execute the given code and exit.",
+)
+def shell(interface: str | None, command: str | None) -> None:
+    """Interactive Python shell with the app configured.
+
+    Also runs one-off code and exits: `-c "..."` or piped stdin.
+    """
+    if command is not None:
+        _run_command(command)
+    elif not sys.stdin.isatty():
+        # Piped input can't go through the REPL: PYTHONSTARTUP (and thus the
+        # app setup + enrichment) is only honored interactively, so non-tty
+        # stdin runs through a child that sets the app up explicitly.
+        _run_stdin()
+    else:
+        _run_repl(interface)
diff --git a/plain/tests/internal/test_python_cli.py b/plain/tests/internal/test_python_cli.py
deleted file mode 100644
index 361db9eb46..0000000000
--- a/plain/tests/internal/test_python_cli.py
+++ /dev/null
@@ -1,153 +0,0 @@
-from __future__ import annotations
-
-import subprocess
-import sys
-from unittest import mock
-
-from click.testing import CliRunner
-
-from plain.cli.python import python, shell
-
-
-def _invoke(command, args):
-    """Invoke a CLI command with subprocess.run stubbed out.
-
-    Returns the list of (cmd, kwargs) passed to subprocess.run so tests can
-    assert which execution path the dispatcher took without spawning a real
-    interpreter.
-    """
-    calls = []
-
-    def fake_run(cmd, **kwargs):
-        calls.append((cmd, kwargs))
-        return subprocess.CompletedProcess(cmd, 0)
-
-    with mock.patch("plain.cli.python.subprocess.run", side_effect=fake_run):
-        result = CliRunner().invoke(command, args, prog_name="plain")
-
-    assert result.exit_code == 0, result.output
-    return calls
-
-
-def _child_body(calls):
-    """The generated `python -c <body>` string for a non-interactive path."""
-    (cmd, _kwargs) = calls[0]
-    assert cmd[:2] == [sys.executable, "-c"]
-    return cmd[2]
-
-
-def test_dash_c_executes_string():
-    body = _child_body(_invoke(python, ["-c", "print(1)"]))
-    assert "plain.runtime.setup()" in body
-    assert "exec(compile('print(1)'" in body
-    assert "sys.argv = ['-c']" in body
-    # User code runs in a fresh namespace, not the wrapper's globals.
-    assert "{'__name__': '__main__'}" in body
-
-
-def test_dash_c_forwards_trailing_args():
-    # `python -c CMD a b` → sys.argv = ['-c', 'a', 'b']; the first positional
-    # must not be swallowed by the `script` argument.
-    body = _child_body(_invoke(python, ["-c", "print(1)", "a", "b"]))
-    assert "sys.argv = ['-c', 'a', 'b']" in body
-
-
-def test_dash_c_forwards_option_shaped_args():
-    # Everything after the -c payload passes through verbatim, even tokens
-    # that look like plain's own options — matching the interpreter.
-    body = _child_body(
-        _invoke(python, ["-c", "print(1)", "--interface", "python", "-c", "x"])
-    )
-    assert "sys.argv = ['-c', '--interface', 'python', '-c', 'x']" in body
-    assert "exec(compile('print(1)'" in body
-
-
-def test_dash_m_runs_module_as_main():
-    body = _child_body(_invoke(python, ["-m", "app.tasks", "a", "b"]))
-    assert "plain.runtime.setup()" in body
-    assert "runpy.run_module('app.tasks', run_name='__main__', alter_sys=True)" in body
-    assert "sys.argv = ['app.tasks', 'a', 'b']" in body
-
-
-def test_file_runs_as_main_with_args(tmp_path):
-    script = tmp_path / "script.py"
-    script.write_text("print(1)")
-    body = _child_body(_invoke(python, [str(script), "a", "b"]))
-    assert "plain.runtime.setup()" in body
-    assert f"runpy.run_path({str(script)!r}, run_name='__main__')" in body
-    assert f"sys.argv = [{str(script)!r}, 'a', 'b']" in body
-    # The script's directory goes on sys.path, like `python script.py`.
-    assert f"sys.path.insert(0, {str(tmp_path)!r})" in body
-
-
-def test_file_not_found_is_clean_error():
-    result = CliRunner().invoke(python, ["missing.py"], prog_name="plain")
-    assert result.exit_code == 2
-    assert "can't open file" in result.output
-
-
-def test_script_args_colliding_with_options_pass_through(tmp_path):
-    # `plain python script.py -c foo` must forward `-c foo` to the script as
-    # sys.argv, not treat `-c` as plain's own option.
-    script = tmp_path / "script.py"
-    script.write_text("print(1)")
-    body = _child_body(_invoke(python, [str(script), "-c", "foo"]))
-    assert f"sys.argv = [{str(script)!r}, '-c', 'foo']" in body
-
-
-def test_dash_reads_stdin():
-    body = _child_body(_invoke(python, ["-"]))
-    assert "sys.stdin.read()" in body
-    assert "sys.argv = ['-']" in body
-
-
-def test_no_args_non_tty_reads_stdin():
-    # CliRunner provides a non-tty stdin, so bare `plain python` execs stdin
-    # rather than opening a REPL.
-    body = _child_body(_invoke(python, []))
-    assert "sys.stdin.read()" in body
-
-
-def test_unknown_option_is_an_error():
-    result = CliRunner().invoke(python, ["-x"], prog_name="plain")
-    assert result.exit_code != 0
-    assert "Unknown option" in result.output
-
-
-def test_help_option():
-    result = CliRunner().invoke(python, ["--help"], prog_name="plain")
-    assert result.exit_code == 0
-    assert "plain python -m module" in result.output
-
-
-def test_shell_tty_launches_enriched_repl():
-    # On a tty, `shell` opens the enriched REPL. Enrichment (banner +
-    # SHELL_IMPORT) is delivered via PYTHONSTARTUP, which only the interactive
-    # interpreter honors — so no `-c` payload.
-    calls = []
-
-    def fake_run(cmd, **kwargs):
-        calls.append((cmd, kwargs))
-        return subprocess.CompletedProcess(cmd, 0)
-
-    fake_stdin = mock.Mock()
-    fake_stdin.isatty.return_value = True
-    assert shell.callback is not None
-    with (
-        mock.patch("plain.cli.python.subprocess.run", side_effect=fake_run),
-        mock.patch("plain.cli.python.sys.stdin", fake_stdin),
-    ):
-        shell.callback(interface=None)
-
-    (cmd, kwargs) = calls[0]
-    assert kwargs["env"]["PYTHONSTARTUP"].endswith("startup.py")
-    assert "-c" not in cmd
-
-
-def test_shell_piped_stdin_runs_setup():
-    # Regression guard (#66): piped input into `shell` must run
-    # plain.runtime.setup() explicitly, since PYTHONSTARTUP is skipped for
-    # non-interactive stdin. CliRunner provides a non-tty stdin.
-    body = _child_body(_invoke(shell, []))
-    assert "plain.runtime.setup()" in body
-    assert "sys.stdin.read()" in body
diff --git a/plain/tests/internal/test_shell_cli.py b/plain/tests/internal/test_shell_cli.py
new file mode 100644
index 0000000000..813c96bdaf
--- /dev/null
+++ b/plain/tests/internal/test_shell_cli.py
@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+import subprocess
+import sys
+from unittest import mock
+
+from click.testing import CliRunner
+
+from plain.cli.shell import shell
+
+
+def _invoke(args):
+    """Invoke the shell command with subprocess.run stubbed out.
+
+    Returns the list of (cmd, kwargs) passed to subprocess.run so tests can
+    assert which execution path was taken without spawning a real interpreter.
+    """
+    calls = []
+
+    def fake_run(cmd, **kwargs):
+        calls.append((cmd, kwargs))
+        return subprocess.CompletedProcess(cmd, 0)
+
+    with mock.patch("plain.cli.shell.subprocess.run", side_effect=fake_run):
+        result = CliRunner().invoke(shell, args, prog_name="plain")
+
+    assert result.exit_code == 0, result.output
+    return calls
+
+
+def _child_body(calls):
+    """The generated `python -c <body>` string for a non-interactive path."""
+    (cmd, _kwargs) = calls[0]
+    assert cmd[:2] == [sys.executable, "-c"]
+    return cmd[2]
+
+
+def test_dash_c_executes_string():
+    body = _child_body(_invoke(["-c", "print(1)"]))
+    assert "plain.runtime.setup()" in body
+    assert "exec(compile('print(1)'" in body
+    assert "sys.argv = ['-c']" in body
+    # User code runs in a fresh namespace, not the wrapper's globals.
+    assert "{'__name__': '__main__'}" in body
+
+
+def test_piped_stdin_runs_setup():
+    # Regression guard (#66): piped input must run plain.runtime.setup()
+    # explicitly, since PYTHONSTARTUP is skipped for non-interactive stdin.
+    # CliRunner provides a non-tty stdin.
+    body = _child_body(_invoke([]))
+    assert "plain.runtime.setup()" in body
+    assert "sys.stdin.read()" in body
+    assert "sys.argv = ['-']" in body
+
+
+def test_tty_launches_enriched_repl():
+    # On a tty, `shell` opens the enriched REPL. Enrichment (banner +
+    # SHELL_IMPORT) is delivered via PYTHONSTARTUP, which only the interactive
+    # interpreter honors — so no `-c` payload, and Plain's startup file must
+    # win over any PYTHONSTARTUP the user has exported.
+    calls = []
+
+    def fake_run(cmd, **kwargs):
+        calls.append((cmd, kwargs))
+        return subprocess.CompletedProcess(cmd, 0)
+
+    fake_stdin = mock.Mock()
+    fake_stdin.isatty.return_value = True
+    assert shell.callback is not None
+    with (
+        mock.patch("plain.cli.shell.subprocess.run", side_effect=fake_run),
+        mock.patch("plain.cli.shell.sys.stdin", fake_stdin),
+        mock.patch.dict("os.environ", {"PYTHONSTARTUP": "/home/user/.pythonrc"}),
+    ):
+        shell.callback(interface=None, command=None)
+
+    (cmd, kwargs) = calls[0]
+    assert cmd[0] == sys.executable
+    assert kwargs["env"]["PYTHONSTARTUP"].endswith("startup.py")
+    assert "-c" not in cmd

From e2845643c078626ead407aa9446826fd3474487e Mon Sep 17 00:00:00 2001
From: Dave Gaeddert <dave.gaeddert@gmail.com>
Date: Tue, 14 Jul 2026 22:37:15 -0500
Subject: [PATCH 4/5] Run shell -c and stdin code in-process as a real __main__
 module
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Executing one-off code in a detached globals dict broke __main__
identity: objects defined in -c/stdin code got __module__ ==
'__main__' without being resolvable through sys.modules['__main__'],
so pickle (and multiprocessing spawn) raised PicklingError for code
that works under python -c.

The subprocess + generated-code-string layer existed only to run
plain.runtime.setup() in a child — but the CLI already runs setup in
this process before any command executes. So execute -c/stdin code
in-process instead: compile it, register a fresh module as
sys.modules['__main__'], and exec into that module's namespace. That
keeps the namespace clean (no wrapper imports to leak), makes pickle
and __main__ semantics match python -c, sets sys.argv the same way,
and drops a whole interpreter start + duplicate setup from every -c
invocation. Tracebacks are trimmed to start at the user's code, like
python -c. The REPL keeps its subprocess since PYTHONSTARTUP is only
honored interactively.

Claude-Session: https://claude.ai/code/session_014CgGYyfFCV32412TkQW3x7
---
 plain/plain/cli/shell.py               | 73 ++++++++++--------------
 plain/tests/internal/test_shell_cli.py | 78 ++++++++++++++------------
 2 files changed, 72 insertions(+), 79 deletions(-)

diff --git a/plain/plain/cli/shell.py b/plain/plain/cli/shell.py
index 534de3b0c7..231a895401 100644
--- a/plain/plain/cli/shell.py
+++ b/plain/plain/cli/shell.py
@@ -3,50 +3,36 @@
 import os
 import subprocess
 import sys
+import traceback
+import types
 
 import click
 
 from plain.cli.runtime import common_command
 
-# Runs in the child interpreter before any user code, so the app is fully
-# configured (settings, packages, etc.) for the -c and stdin modes.
-_SETUP = "import plain.runtime; plain.runtime.setup()"
-
 _STARTUP = os.path.join(os.path.dirname(__file__), "startup.py")
 
-# User code executes in a fresh namespace so the wrapper's own imports
-# (plain.runtime, sys) don't leak into it.
-_FRESH_GLOBALS = "{'__name__': '__main__'}"
-
-
-def _exit_with(result: subprocess.CompletedProcess) -> None:
-    if result.returncode:
-        sys.exit(result.returncode)
-
 
-def _run_child(body: str, *, argv: list[str]) -> None:
-    """Run setup + `body` in a child interpreter with sys.argv set to `argv`.
+def _run_source(source: str, filename: str, argv0: str) -> None:
+    """Execute one-off code in this process, as the `__main__` module.
 
-    The child inherits our stdin, so piped input works.
+    The CLI has already run plain.runtime.setup() before any command executes,
+    so the app is configured. Registering a real module as
+    sys.modules["__main__"] keeps `python -c` semantics: user code gets a
+    clean namespace, and objects it defines can be resolved through their
+    module (pickle, multiprocessing).
     """
-    code = f"import sys; sys.argv = {argv!r}; {_SETUP}; {body}"
-    _exit_with(subprocess.run([sys.executable, "-c", code]))
-
-
-def _run_command(command: str) -> None:
-    """`plain shell -c "..."` — execute a string, then exit."""
-    _run_child(
-        f"exec(compile({command!r}, '<string>', 'exec'), {_FRESH_GLOBALS})",
-        argv=["-c"],
-    )
-
-
-def _run_stdin() -> None:
-    """Piped input — execute stdin, then exit."""
-    _run_child(
-        f"exec(compile(sys.stdin.read(), '<stdin>', 'exec'), {_FRESH_GLOBALS})",
-        argv=["-"],
-    )
+    sys.argv = [argv0]
+    module = types.ModuleType("__main__")
+    sys.modules["__main__"] = module
+    try:
+        exec(compile(source, filename, "exec"), module.__dict__)
+    except Exception as e:
+        # Drop this function's frame so the traceback starts at the user's
+        # code, like `python -c`.
+        e.__traceback__ = e.__traceback__.tb_next if e.__traceback__ else None
+        traceback.print_exception(e)
+        sys.exit(1)
 
 
 # Each interface runs under the same interpreter (`sys.executable`) that the
@@ -72,12 +58,12 @@ def _run_repl(interface: str | None) -> None:
     interface_list = _INTERFACES[interface] if interface else _default_interface()
     # Plain's startup file must win over any PYTHONSTARTUP the user has exported,
     # otherwise the banner + SHELL_IMPORT enrichment is silently replaced.
-    _exit_with(
-        subprocess.run(
-            interface_list,
-            env={**os.environ, "PYTHONSTARTUP": _STARTUP},
-        )
+    result = subprocess.run(
+        interface_list,
+        env={**os.environ, "PYTHONSTARTUP": _STARTUP},
     )
+    if result.returncode:
+        sys.exit(result.returncode)
 
 
 @common_command
@@ -99,11 +85,10 @@ def shell(interface: str | None, command: str | None) -> None:
     Also runs one-off code and exits: `-c "..."` or piped stdin.
     """
     if command is not None:
-        _run_command(command)
+        _run_source(command, "<string>", argv0="-c")
     elif not sys.stdin.isatty():
-        # Piped input can't go through the REPL: PYTHONSTARTUP (and thus the
-        # app setup + enrichment) is only honored interactively, so non-tty
-        # stdin runs through a child that sets the app up explicitly.
-        _run_stdin()
+        # Piped input can't go through the REPL — PYTHONSTARTUP (and thus the
+        # enrichment) is only honored for interactive sessions.
+        _run_source(sys.stdin.read(), "<stdin>", argv0="-")
     else:
         _run_repl(interface)
diff --git a/plain/tests/internal/test_shell_cli.py b/plain/tests/internal/test_shell_cli.py
index 813c96bdaf..3a016e35b3 100644
--- a/plain/tests/internal/test_shell_cli.py
+++ b/plain/tests/internal/test_shell_cli.py
@@ -9,56 +9,65 @@
 from plain.cli.shell import shell
 
 
-def _invoke(args):
-    """Invoke the shell command with subprocess.run stubbed out.
+def _invoke(args, input=None):
+    """Invoke the shell command, restoring what one-off execution mutates.
 
-    Returns the list of (cmd, kwargs) passed to subprocess.run so tests can
-    assert which execution path was taken without spawning a real interpreter.
+    `-c` and stdin code run in-process as a fresh `__main__` module with
+    sys.argv reset, so put both back afterward for the rest of the suite.
     """
-    calls = []
+    saved_main = sys.modules["__main__"]
+    saved_argv = sys.argv
+    try:
+        return CliRunner().invoke(shell, args, input=input, prog_name="plain")
+    finally:
+        sys.modules["__main__"] = saved_main
+        sys.argv = saved_argv
 
-    def fake_run(cmd, **kwargs):
-        calls.append((cmd, kwargs))
-        return subprocess.CompletedProcess(cmd, 0)
 
-    with mock.patch("plain.cli.shell.subprocess.run", side_effect=fake_run):
-        result = CliRunner().invoke(shell, args, prog_name="plain")
+def test_dash_c_executes_string():
+    result = _invoke(["-c", "print(1 + 1)"])
+    assert result.exit_code == 0, result.output
+    assert "2" in result.output
+
 
+def test_dash_c_runs_in_clean_main_namespace():
+    # No wrapper imports leak in, and sys.argv matches `python -c`.
+    result = _invoke(["-c", "import sys; print(sys.argv, 'plain' in dir())"])
     assert result.exit_code == 0, result.output
-    return calls
+    assert "['-c'] False" in result.output
 
 
-def _child_body(calls):
-    """The generated `python -c <body>` string for a non-interactive path."""
-    (cmd, _kwargs) = calls[0]
-    assert cmd[:2] == [sys.executable, "-c"]
-    return cmd[2]
+def test_dash_c_defines_picklable_objects():
+    # Classes defined in one-off code must resolve through
+    # sys.modules["__main__"], like `python -c` — pickle enforces this.
+    code = "import pickle\nclass A: pass\nprint(len(pickle.dumps(A())))"
+    result = _invoke(["-c", code])
+    assert result.exit_code == 0, result.output
+    assert int(result.output.strip()) > 0
 
 
-def test_dash_c_executes_string():
-    body = _child_body(_invoke(["-c", "print(1)"]))
-    assert "plain.runtime.setup()" in body
-    assert "exec(compile('print(1)'" in body
-    assert "sys.argv = ['-c']" in body
-    # User code runs in a fresh namespace, not the wrapper's globals.
-    assert "{'__name__': '__main__'}" in body
+def test_dash_c_error_traceback_starts_at_user_code():
+    result = _invoke(["-c", "1/0"])
+    assert result.exit_code == 1
+    assert 'File "<string>"' in result.output
+    assert "ZeroDivisionError" in result.output
+    assert "shell.py" not in result.output
 
 
-def test_piped_stdin_runs_setup():
-    # Regression guard (#66): piped input must run plain.runtime.setup()
-    # explicitly, since PYTHONSTARTUP is skipped for non-interactive stdin.
+def test_piped_stdin_executes():
+    # Regression guard (#66): piped input must run with the app configured.
+    # It executes in-process, where the CLI has already done setup.
     # CliRunner provides a non-tty stdin.
-    body = _child_body(_invoke([]))
-    assert "plain.runtime.setup()" in body
-    assert "sys.stdin.read()" in body
-    assert "sys.argv = ['-']" in body
+    result = _invoke([], input="import sys; print(sys.argv)")
+    assert result.exit_code == 0, result.output
+    assert "['-']" in result.output
 
 
 def test_tty_launches_enriched_repl():
-    # On a tty, `shell` opens the enriched REPL. Enrichment (banner +
-    # SHELL_IMPORT) is delivered via PYTHONSTARTUP, which only the interactive
-    # interpreter honors — so no `-c` payload, and Plain's startup file must
-    # win over any PYTHONSTARTUP the user has exported.
+    # On a tty, `shell` opens the enriched REPL in a subprocess. Enrichment
+    # (banner + SHELL_IMPORT) is delivered via PYTHONSTARTUP, which only the
+    # interactive interpreter honors — and Plain's startup file must win over
+    # any PYTHONSTARTUP the user has exported.
     calls = []
 
     def fake_run(cmd, **kwargs):
@@ -78,4 +87,3 @@ def fake_run(cmd, **kwargs):
     (cmd, kwargs) = calls[0]
     assert cmd[0] == sys.executable
     assert kwargs["env"]["PYTHONSTARTUP"].endswith("startup.py")
-    assert "-c" not in cmd

From 49d7a279f76d2762a5af777138f6aeb2262cfcc3 Mon Sep 17 00:00:00 2001
From: Dave Gaeddert <dave.gaeddert@gmail.com>
Date: Tue, 14 Jul 2026 22:50:06 -0500
Subject: [PATCH 5/5] Apply review cleanups to shell command
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Inline the single-caller _default_interface helper, derive the -i
choices from _INTERFACES instead of a duplicate list, and drop the
docstring's multiprocessing claim (spawn can't reimport a synthetic
__main__ — same limitation as python -c).

Claude-Session: https://claude.ai/code/session_014CgGYyfFCV32412TkQW3x7
---
 plain/plain/cli/shell.py | 23 ++++++++++-------------
 1 file changed, 10 insertions(+), 13 deletions(-)

diff --git a/plain/plain/cli/shell.py b/plain/plain/cli/shell.py
index 231a895401..2bebb090e9 100644
--- a/plain/plain/cli/shell.py
+++ b/plain/plain/cli/shell.py
@@ -20,7 +20,7 @@ def _run_source(source: str, filename: str, argv0: str) -> None:
     so the app is configured. Registering a real module as
     sys.modules["__main__"] keeps `python -c` semantics: user code gets a
     clean namespace, and objects it defines can be resolved through their
-    module (pickle, multiprocessing).
+    module (pickle).
     """
     sys.argv = [argv0]
     module = types.ModuleType("__main__")
@@ -44,22 +44,19 @@ def _run_source(source: str, filename: str, argv0: str) -> None:
 }
 
 
-def _default_interface() -> list[str]:
-    try:
-        import IPython  # noqa: F401  # ty: ignore[unresolved-import]
-
-        return _INTERFACES["ipython"]
-    except ImportError:
-        return _INTERFACES["python"]
-
-
 def _run_repl(interface: str | None) -> None:
     """Enriched interactive REPL: banner + SHELL_IMPORT via PYTHONSTARTUP."""
-    interface_list = _INTERFACES[interface] if interface else _default_interface()
+    if interface is None:
+        try:
+            import IPython  # noqa: F401  # ty: ignore[unresolved-import]
+
+            interface = "ipython"
+        except ImportError:
+            interface = "python"
     # Plain's startup file must win over any PYTHONSTARTUP the user has exported,
     # otherwise the banner + SHELL_IMPORT enrichment is silently replaced.
     result = subprocess.run(
-        interface_list,
+        _INTERFACES[interface],
         env={**os.environ, "PYTHONSTARTUP": _STARTUP},
     )
     if result.returncode:
@@ -71,7 +68,7 @@ def _run_repl(interface: str | None) -> None:
 @click.option(
     "-i",
     "--interface",
-    type=click.Choice(["ipython", "bpython", "python"]),
+    type=click.Choice(list(_INTERFACES)),
     help="Specify an interactive interpreter interface.",
 )
 @click.option(