nullgate 1.2.0__tar.gz → 1.2.1__tar.gz

{nullgate-1.2.0/src/nullgate.egg-info → nullgate-1.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nullgate
-Version: 1.2.0
+Version: 1.2.1
 Summary: Disposable SSH gateway into confined directory workspaces
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
@@ -14,6 +14,32 @@ Dynamic: license-file
 
 Disposable SSH gateway into confined directory workspaces for remote containers, ephemeral developer boxes, CI nodes, and cloud instances.
 
+## Quick start
+
+Run Nullgate directly from PyPI without installing it first:
+
+```bash
+# Share the current directory over the default Upterm provider
+uvx nullgate start
+
+# Share a specific workspace
+uvx nullgate start /workspace
+
+# Compact form: workspace, SSH port, srv.us slot, provider
+uvx nullgate start /workspace 8022 1 -t srvus
+```
+
+Then check the endpoint and print the SSH connection setup:
+
+```bash
+uvx nullgate status
+uvx nullgate connect
+```
+
+Nullgate uses authorized SSH keys by default. Upterm needs a key in
+`~/.ssh/authorized_keys`; use `--public-access` only for an intentionally public
+temporary endpoint.
+
 ## Features
 
 - **Ingress Transports**: Publish endpoints via Upterm WebSocket relays (default), srv.us reverse tunnels, Cloudflare Worker relays, or Cloudflare Argo (`cloudflared`) tunnels.
@@ -55,6 +81,9 @@ nullgate start
 # Custom path, port, and slot
 nullgate start /workspace --ssh-port 4822 --tunnel-slot 1
 
+# The same values in compact positional form
+nullgate start /workspace 4822 1
+
 # Select specific transport provider
 nullgate start . --provider upterm
 nullgate start . --provider srvus
@@ -63,9 +92,11 @@ nullgate start . --provider cloudflared --public-hostname workspace.example.com
 ```
 
 Options:
-- `--provider`: Public connection provider (`upterm`, `srvus`, `cloudflare`, or `cloudflared`). Defaults to `upterm`.
-- `--relay-url`: WebSocket relay URL used with `upterm` or `cloudflare`.
-- `--public-hostname`: Public hostname used with `cloudflared`.
+- `-p`, `--ssh-port`: Local SSH server port.
+- `-s`, `--tunnel-slot`: srv.us tunnel slot.
+- `-t`, `--provider`: Public connection provider (`upterm`, `srvus`, `cloudflare`, or `cloudflared`). Defaults to `upterm`.
+- `-e`, `--relay-url`: WebSocket relay URL used with `upterm` or `cloudflare`.
+- `-H`, `--public-hostname`: Public hostname used with `cloudflared`.
 - `--cloudflare-token`: Cloudflare tunnel credential, or set `NULLGATE_CLOUDFLARED_TOKEN`.
 - `--public-access`: Allow connections without credentials. This is unsafe on public endpoints.
 - `--no-public-access`: Require authentication.
@@ -126,9 +157,10 @@ nullgate upgrade
 nullgate upgrade --version 1.0.1
 ```
 
-The earlier command names `open`, `shut`, `inspect`, `enter`, `trace`, and
-`cycle` remain available as compatibility aliases. Their earlier option names
-also remain accepted, but new scripts should use the names documented above.
+Short command aliases are `up`, `down`, `ps`, `ssh`, `log`, and `reload`.
+The earlier names `open`, `shut`, `inspect`, `enter`, `trace`, and `cycle`
+remain available as compatibility aliases. Their earlier option names also
+remain accepted, but new scripts should use the names documented above.
 
 ## Authentication and Security Boundaries
 

{nullgate-1.2.0 → nullgate-1.2.1}/README.md

@@ -2,6 +2,32 @@
 
 Disposable SSH gateway into confined directory workspaces for remote containers, ephemeral developer boxes, CI nodes, and cloud instances.
 
+## Quick start
+
+Run Nullgate directly from PyPI without installing it first:
+
+```bash
+# Share the current directory over the default Upterm provider
+uvx nullgate start
+
+# Share a specific workspace
+uvx nullgate start /workspace
+
+# Compact form: workspace, SSH port, srv.us slot, provider
+uvx nullgate start /workspace 8022 1 -t srvus
+```
+
+Then check the endpoint and print the SSH connection setup:
+
+```bash
+uvx nullgate status
+uvx nullgate connect
+```
+
+Nullgate uses authorized SSH keys by default. Upterm needs a key in
+`~/.ssh/authorized_keys`; use `--public-access` only for an intentionally public
+temporary endpoint.
+
 ## Features
 
 - **Ingress Transports**: Publish endpoints via Upterm WebSocket relays (default), srv.us reverse tunnels, Cloudflare Worker relays, or Cloudflare Argo (`cloudflared`) tunnels.
@@ -43,6 +69,9 @@ nullgate start
 # Custom path, port, and slot
 nullgate start /workspace --ssh-port 4822 --tunnel-slot 1
 
+# The same values in compact positional form
+nullgate start /workspace 4822 1
+
 # Select specific transport provider
 nullgate start . --provider upterm
 nullgate start . --provider srvus
@@ -51,9 +80,11 @@ nullgate start . --provider cloudflared --public-hostname workspace.example.com
 ```
 
 Options:
-- `--provider`: Public connection provider (`upterm`, `srvus`, `cloudflare`, or `cloudflared`). Defaults to `upterm`.
-- `--relay-url`: WebSocket relay URL used with `upterm` or `cloudflare`.
-- `--public-hostname`: Public hostname used with `cloudflared`.
+- `-p`, `--ssh-port`: Local SSH server port.
+- `-s`, `--tunnel-slot`: srv.us tunnel slot.
+- `-t`, `--provider`: Public connection provider (`upterm`, `srvus`, `cloudflare`, or `cloudflared`). Defaults to `upterm`.
+- `-e`, `--relay-url`: WebSocket relay URL used with `upterm` or `cloudflare`.
+- `-H`, `--public-hostname`: Public hostname used with `cloudflared`.
 - `--cloudflare-token`: Cloudflare tunnel credential, or set `NULLGATE_CLOUDFLARED_TOKEN`.
 - `--public-access`: Allow connections without credentials. This is unsafe on public endpoints.
 - `--no-public-access`: Require authentication.
@@ -114,9 +145,10 @@ nullgate upgrade
 nullgate upgrade --version 1.0.1
 ```
 
-The earlier command names `open`, `shut`, `inspect`, `enter`, `trace`, and
-`cycle` remain available as compatibility aliases. Their earlier option names
-also remain accepted, but new scripts should use the names documented above.
+Short command aliases are `up`, `down`, `ps`, `ssh`, `log`, and `reload`.
+The earlier names `open`, `shut`, `inspect`, `enter`, `trace`, and `cycle`
+remain available as compatibility aliases. Their earlier option names also
+remain accepted, but new scripts should use the names documented above.
 
 ## Authentication and Security Boundaries
 

nullgate-1.2.1/src/nullgate/__init__.py

@@ -0,0 +1 @@
+__version__ = "1.2.1"

{nullgate-1.2.0 → nullgate-1.2.1}/src/nullgate/commands.py

@@ -10,11 +10,17 @@ from nullgate import session, transports
 
 SUBCOMMANDS = (
     "start",
+    "up",
     "stop",
+    "down",
     "status",
+    "ps",
     "connect",
+    "ssh",
     "logs",
+    "log",
     "restart",
+    "reload",
     "upgrade",
     "open",
     "shut",
@@ -40,9 +46,9 @@ def build_parser() -> argparse.ArgumentParser:
 
     start_parser = sub.add_parser(
         "start",
-        aliases=["open"],
+        aliases=["up", "open"],
         description="Start SSH access to a workspace.",
-        help="Start SSH access to a workspace (alias: open).",
+        help="Start SSH access to a workspace (aliases: up, open).",
     )
     start_parser.add_argument(
         "workspace",
@@ -50,6 +56,19 @@ def build_parser() -> argparse.ArgumentParser:
         help="Directory to make available (default: current directory).",
     )
     start_parser.add_argument(
+        "port_arg",
+        nargs="?",
+        type=int,
+        help="Local SSH server port (shorthand positional).",
+    )
+    start_parser.add_argument(
+        "slot_arg",
+        nargs="?",
+        type=int,
+        help="srv.us tunnel slot (shorthand positional).",
+    )
+    start_parser.add_argument(
+        "-p",
         "--ssh-port",
         dest="port",
         type=int,
@@ -58,6 +77,7 @@ def build_parser() -> argparse.ArgumentParser:
     )
     start_parser.add_argument("--port", dest="port", type=int, help=argparse.SUPPRESS)
     start_parser.add_argument(
+        "-s",
         "--tunnel-slot",
         dest="slot",
         type=int,
@@ -66,6 +86,7 @@ def build_parser() -> argparse.ArgumentParser:
     )
     start_parser.add_argument("--slot", dest="slot", type=int, help=argparse.SUPPRESS)
     start_parser.add_argument(
+        "-t",
         "--provider",
         dest="transport",
         choices=transports.VALID_TRANSPORTS,
@@ -121,12 +142,14 @@ def build_parser() -> argparse.ArgumentParser:
         help=argparse.SUPPRESS,
     )
     start_parser.add_argument(
+        "-e",
         "--relay-url",
         dest="endpoint",
         help="WebSocket relay URL (for upterm or cloudflare providers).",
     )
     start_parser.add_argument("--endpoint", dest="endpoint", help=argparse.SUPPRESS)
     start_parser.add_argument(
+        "-H",
         "--public-hostname",
         dest="hostname",
         help="Public hostname (for the cloudflared provider).",
@@ -141,30 +164,30 @@ def build_parser() -> argparse.ArgumentParser:
 
     sub.add_parser(
         "stop",
-        aliases=["shut"],
+        aliases=["down", "shut"],
         description="Stop SSH access and its connection provider.",
-        help="Stop SSH access (alias: shut).",
+        help="Stop SSH access (aliases: down, shut).",
     )
 
     sub.add_parser(
         "status",
-        aliases=["inspect"],
+        aliases=["ps", "inspect"],
         description="Show service health, connection details, and security settings.",
-        help="Show current status (alias: inspect).",
+        help="Show current status (aliases: ps, inspect).",
     )
 
     sub.add_parser(
         "connect",
-        aliases=["enter"],
+        aliases=["ssh", "enter"],
         description="Show how to connect with SSH.",
-        help="Show SSH connection instructions (alias: enter).",
+        help="Show SSH connection instructions (aliases: ssh, enter).",
     )
 
     logs_parser = sub.add_parser(
         "logs",
-        aliases=["trace"],
+        aliases=["log", "trace"],
         description="View or follow service logs.",
-        help="View or follow service logs (alias: trace).",
+        help="View or follow service logs (aliases: log, trace).",
     )
     logs_parser.add_argument(
         "target",
@@ -183,9 +206,9 @@ def build_parser() -> argparse.ArgumentParser:
 
     sub.add_parser(
         "restart",
-        aliases=["cycle"],
+        aliases=["reload", "cycle"],
         description="Restart SSH access using the saved settings.",
-        help="Restart using saved settings (alias: cycle).",
+        help="Restart using saved settings (aliases: reload, cycle).",
     )
 
     upgrade_parser = sub.add_parser(
@@ -219,16 +242,22 @@ def main(argv: Sequence[str] | None = None) -> int:
 
     handlers = {
         "start": session.cmd_open,
+        "up": session.cmd_open,
         "open": session.cmd_open,
         "stop": session.cmd_shut,
+        "down": session.cmd_shut,
         "shut": session.cmd_shut,
         "status": session.cmd_inspect,
+        "ps": session.cmd_inspect,
         "inspect": session.cmd_inspect,
         "connect": session.cmd_enter,
+        "ssh": session.cmd_enter,
         "enter": session.cmd_enter,
         "logs": session.cmd_trace,
+        "log": session.cmd_trace,
         "trace": session.cmd_trace,
         "restart": session.cmd_cycle,
+        "reload": session.cmd_cycle,
         "cycle": session.cmd_cycle,
         "upgrade": session.cmd_upgrade,
         "proxy": transports.cmd_proxy,

{nullgate-1.2.0 → nullgate-1.2.1}/src/nullgate/session.py

@@ -41,8 +41,17 @@ def _resolve_launch_settings(
 ) -> tuple[Path, int, int]:
     saved = saved or {}
     root_arg = getattr(args, "workspace", None) or saved.get("root") or "."
-    port_arg = getattr(args, "port", None) or saved.get("port") or DEFAULT_PORT
-    slot_arg = getattr(args, "slot", None) or saved.get("slot") or DEFAULT_SLOT
+    port_arg = getattr(args, "port", None)
+    if port_arg is None:
+        port_arg = getattr(args, "port_arg", None)
+    if port_arg is None:
+        port_arg = saved.get("port") or DEFAULT_PORT
+
+    slot_arg = getattr(args, "slot", None)
+    if slot_arg is None:
+        slot_arg = getattr(args, "slot_arg", None)
+    if slot_arg is None:
+        slot_arg = saved.get("slot") or DEFAULT_SLOT
 
     port_text = str(port_arg)
     if not port_text.isdigit() or not 1 <= int(port_text) <= 65535:

{nullgate-1.2.0 → nullgate-1.2.1/src/nullgate.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nullgate
-Version: 1.2.0
+Version: 1.2.1
 Summary: Disposable SSH gateway into confined directory workspaces
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
@@ -14,6 +14,32 @@ Dynamic: license-file
 
 Disposable SSH gateway into confined directory workspaces for remote containers, ephemeral developer boxes, CI nodes, and cloud instances.
 
+## Quick start
+
+Run Nullgate directly from PyPI without installing it first:
+
+```bash
+# Share the current directory over the default Upterm provider
+uvx nullgate start
+
+# Share a specific workspace
+uvx nullgate start /workspace
+
+# Compact form: workspace, SSH port, srv.us slot, provider
+uvx nullgate start /workspace 8022 1 -t srvus
+```
+
+Then check the endpoint and print the SSH connection setup:
+
+```bash
+uvx nullgate status
+uvx nullgate connect
+```
+
+Nullgate uses authorized SSH keys by default. Upterm needs a key in
+`~/.ssh/authorized_keys`; use `--public-access` only for an intentionally public
+temporary endpoint.
+
 ## Features
 
 - **Ingress Transports**: Publish endpoints via Upterm WebSocket relays (default), srv.us reverse tunnels, Cloudflare Worker relays, or Cloudflare Argo (`cloudflared`) tunnels.
@@ -55,6 +81,9 @@ nullgate start
 # Custom path, port, and slot
 nullgate start /workspace --ssh-port 4822 --tunnel-slot 1
 
+# The same values in compact positional form
+nullgate start /workspace 4822 1
+
 # Select specific transport provider
 nullgate start . --provider upterm
 nullgate start . --provider srvus
@@ -63,9 +92,11 @@ nullgate start . --provider cloudflared --public-hostname workspace.example.com
 ```
 
 Options:
-- `--provider`: Public connection provider (`upterm`, `srvus`, `cloudflare`, or `cloudflared`). Defaults to `upterm`.
-- `--relay-url`: WebSocket relay URL used with `upterm` or `cloudflare`.
-- `--public-hostname`: Public hostname used with `cloudflared`.
+- `-p`, `--ssh-port`: Local SSH server port.
+- `-s`, `--tunnel-slot`: srv.us tunnel slot.
+- `-t`, `--provider`: Public connection provider (`upterm`, `srvus`, `cloudflare`, or `cloudflared`). Defaults to `upterm`.
+- `-e`, `--relay-url`: WebSocket relay URL used with `upterm` or `cloudflare`.
+- `-H`, `--public-hostname`: Public hostname used with `cloudflared`.
 - `--cloudflare-token`: Cloudflare tunnel credential, or set `NULLGATE_CLOUDFLARED_TOKEN`.
 - `--public-access`: Allow connections without credentials. This is unsafe on public endpoints.
 - `--no-public-access`: Require authentication.
@@ -126,9 +157,10 @@ nullgate upgrade
 nullgate upgrade --version 1.0.1
 ```
 
-The earlier command names `open`, `shut`, `inspect`, `enter`, `trace`, and
-`cycle` remain available as compatibility aliases. Their earlier option names
-also remain accepted, but new scripts should use the names documented above.
+Short command aliases are `up`, `down`, `ps`, `ssh`, `log`, and `reload`.
+The earlier names `open`, `shut`, `inspect`, `enter`, `trace`, and `cycle`
+remain available as compatibility aliases. Their earlier option names also
+remain accepted, but new scripts should use the names documented above.
 
 ## Authentication and Security Boundaries
 

{nullgate-1.2.0 → nullgate-1.2.1}/tests/test_commands.py

@@ -126,6 +126,8 @@ class CLILifecycleTests(unittest.TestCase):
         self.assertEqual(session.DEFAULT_PORT, 4822)
         self.assertEqual(transports.DEFAULT_TRANSPORT, "upterm")
         self.assertIsNone(defaults.workspace)
+        self.assertIsNone(defaults.port_arg)
+        self.assertIsNone(defaults.slot_arg)
         self.assertIsNone(defaults.port)
         self.assertIsNone(defaults.slot)
         self.assertIsNone(defaults.accept)
@@ -158,6 +160,31 @@ class CLILifecycleTests(unittest.TestCase):
         self.assertEqual(clearer.transport, "upterm")
         self.assertEqual(clearer.endpoint, "wss://relay.example")
 
+        shorthand = parser.parse_args(
+            ["up", "/workspace", "2222", "2", "-t", "srvus"]
+        )
+        self.assertEqual(shorthand.command, "up")
+        self.assertEqual(shorthand.workspace, "/workspace")
+        self.assertEqual(shorthand.port_arg, 2222)
+        self.assertEqual(shorthand.slot_arg, 2)
+        self.assertEqual(shorthand.transport, "srvus")
+
+        short_options = parser.parse_args(
+            [
+                "start",
+                "-p", "2223",
+                "-s", "3",
+                "-t", "cloudflare",
+                "-e", "wss://relay.example",
+                "-H", "workspace.example.com",
+            ]
+        )
+        self.assertEqual(short_options.port, 2223)
+        self.assertEqual(short_options.slot, 3)
+        self.assertEqual(short_options.transport, "cloudflare")
+        self.assertEqual(short_options.endpoint, "wss://relay.example")
+        self.assertEqual(short_options.hostname, "workspace.example.com")
+
         legacy = parser.parse_args(
             ["open", "--no-accept", "--no-allow-tcp-forwarding", "--confine-sftp"]
         )
@@ -165,6 +192,28 @@ class CLILifecycleTests(unittest.TestCase):
         self.assertFalse(legacy.allow_tcp_forwarding)
         self.assertTrue(legacy.confine_sftp)
 
+        for alias, expected in (
+            ("down", "down"),
+            ("ps", "ps"),
+            ("ssh", "ssh"),
+            ("log", "log"),
+            ("reload", "reload"),
+        ):
+            self.assertEqual(parser.parse_args([alias]).command, expected)
+
+    def test_positional_start_values_and_options_resolve(self):
+        parser = commands.build_parser()
+        positional = parser.parse_args(["start", ".", "2222", "3"])
+        root, port, slot = session._resolve_launch_settings(positional)
+        self.assertEqual(root, Path.cwd())
+        self.assertEqual((port, slot), (2222, 3))
+
+        overridden = parser.parse_args(
+            ["start", ".", "2222", "3", "-p", "4444", "-s", "5"]
+        )
+        _, port, slot = session._resolve_launch_settings(overridden)
+        self.assertEqual((port, slot), (4444, 5))
+
         upgrade = parser.parse_args(["upgrade"])
         self.assertIsNone(upgrade.version)
         pinned = parser.parse_args(["upgrade", "--version", "1.2.3"])

nullgate-1.2.0/src/nullgate/__init__.py

@@ -1 +0,0 @@
-__version__ = "1.2.0"