fix: Explain how with-connect works in --help and reject invalid --port by cgraham-rs · Pull Request #63 · posit-dev/with-connect

cgraham-rs · 2026-10-08T19:41:12Z

Agents running with-connect --help only saw a list of flags. They guessed a start subcommand and flags that don't exist, like --json, --name and --data-dir, and their runs failed. See posit-dev/connect#44594.

The help now says what with-connect prints, that the container keeps running, how to stop it, and what -- COMMAND does. The --stop help also says CONTAINER_ID must be exported when no ID is given. Unknown arguments like start or --json still get argparse's standard error.

--port now rejects values outside 1 to 65535 right away. Before, --port 0 was accepted and then failed with a misleading timeout error.

The README eval example did not export the variables, so with-connect --stop could not see CONTAINER_ID in a clean shell. It now exports them.

Fixes #62. Follow-up work is tracked in #61, #64 and #65.

… someone types a subcommand like start.

tdstein · 2026-10-08T22:45:36Z

+        parser.error(f"unrecognized arguments: {' '.join(unknown)}")
+    if unknown:
+        parser.error(
+            f"unexpected argument '{unknown[0]}', with-connect has no subcommands. "


The new 'no subcommands' error fires for any stray positional value, including word-split values from this repo's own action.yml, so users get a misleading diagnosis.

action.yml builds ARGS="$ARGS -e $line" and expands with-connect $ARGS without quotes. An env input like FOO=bar baz (or a config-file/image path containing a space) becomes -e FOO=bar baz. argparse leaves baz unknown, and the user sees "unexpected argument 'baz', with-connect has no subcommands". The real cause is a quoting/value problem. Before this change the plain "unrecognized arguments: baz" was at least neutral. The same happens with with-connect --license a.lic b.lic. Consider limiting the subcommand hint to known verb-like words (start/run/stop/up/down), or wording it as "unexpected positional argument" without claiming the user tried a subcommand.

Removed the custom error. Unknown arguments now get argparse's standard message, so nothing guesses at a subcommand.

tdstein · 2026-10-08T22:45:43Z

    assert "CONTAINER_ID" in result.stdout


+def run_cli(*args):


The new run_cli helper isn't reused by the existing subprocess-based tests, and the pure argument-parsing tests spawn a full interpreter when the in-process parse_with_argv helper would do.

test_custom_port, test_stop_argument_in_help, test_stop_nonexistent_container and others still inline the same subprocess.run([sys.executable, 'main.py', ...], capture_output=True, text=True). The four new error-message tests each start a new Python process that imports docker and rsconnect just to exercise argparse. Using parse_with_argv with pytest.raises(SystemExit) and capsys (as the last two new tests already do for the happy path) avoids the process startup cost, and migrating the old call sites to run_cli removes the duplication.

The four subprocess error tests went away with the custom error, along with run_cli. The new port and help tests run in-process. pytest isn't a dependency here and CI runs test_main.py directly, so they catch SystemExit and capture output with contextlib instead of pytest.raises and capsys. Moving the older subprocess tests to a shared helper would be a separate cleanup.

tdstein

Posted some Claude generated review comments. Overall, I'm wondering if we should be using parser.print_help(); parser.exit() from argparse instead of using a custom error message.

…port right away. Add how to stop the container to --help.

cgraham-rs · 2026-10-13T19:48:42Z

Posted some Claude generated review comments. Overall, I'm wondering if we should be using parser.print_help(); parser.exit() from argparse instead of using a custom error message.

I sampled what other popular CLIs do with a bad argument. Most print a short error instead of the whole help so we followed that simpler implementation here. Happy to discuss further.

tdstein · 2026-10-14T14:14:04Z

+def port_number(value: str) -> int:
+    """Parse --port. Docker can only map a fixed host port from 1 to 65535."""
+    try:
+        port = int(value)
+    except ValueError:
+        raise argparse.ArgumentTypeError(f"invalid port value: '{value}'")
+    if not 1 <= port <= 65535:
+        raise argparse.ArgumentTypeError(f"{port} is not a valid port. Use a free port from 1 to 65535.")
+    return port


cgraham-rs · 2026-10-14T14:51:38Z

$ with-connect --help
usage: with-connect [-h] [--version VERSION] [--license LICENSE] [--image IMAGE] [--config CONFIG] [-e ENV_VARS] [--quiet] [--port PORT]
                    [--stop [CONTAINER_ID]]

Starts Posit Connect in Docker and waits until it is ready.

With no command, prints CONNECT_API_KEY, CONNECT_SERVER and CONTAINER_ID
as KEY=value lines on stdout and leaves the container running.
Stop it later with: with-connect --stop CONTAINER_ID
Progress and errors go to stderr.

With "-- COMMAND", runs COMMAND with CONNECT_API_KEY and CONNECT_SERVER
set, then stops the container and exits with the command's exit code.

options:
  -h, --help            show this help message and exit
  --version VERSION     Posit Connect version (default: release, the latest stable release)
  --license LICENSE     Path to Posit Connect license file (default: ./rstudio-connect.lic)
  --image IMAGE         Container image to use, including tag (use instead of --version)
  --config CONFIG       Path to rstudio-connect.gcfg configuration file
  -e, --env ENV_VARS    Environment variables to pass to Docker container (format: KEY=VALUE)
  --quiet               Suppress progress indicators during image pull
  --port PORT           Port to map the Connect container to (default: 3939)
  --stop [CONTAINER_ID]
                        Stop a running Connect container by ID (uses the exported CONTAINER_ID env var if not specified)

examples:
  with-connect --license ./rstudio-connect.lic
  with-connect --license ./rstudio-connect.lic -- bash -c 'curl -H "Authorization: Key $CONNECT_API_KEY" $CONNECT_SERVER/__api__/v1/content'

Make --help explain how with-connect works. Give a clearer error when…

5587b6d

… someone types a subcommand like start.

cgraham-rs requested review from a team and tdstein October 8, 2026 19:44