nullgate 1.2.2__tar.gz → 1.2.5__tar.gz

{nullgate-1.2.2/src/nullgate.egg-info → nullgate-1.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nullgate
-Version: 1.2.2
+Version: 1.2.5
 Summary: Disposable SSH gateway into confined directory workspaces
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
@@ -19,7 +19,7 @@ Disposable SSH gateway into confined directory workspaces for remote containers,
 Run Nullgate directly from PyPI without installing it first:
 
 ```bash
-# Share the current directory over the default Upterm provider
+# Share the current directory over the default srv.us provider
 uvx nullgate start
 
 # Share a specific workspace
@@ -36,13 +36,13 @@ 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.
+Nullgate requires authentication by default (an authorized SSH key and/or a
+generated password). Pass `--public-access` to allow connections without
+credentials (unsafe on public endpoints).
 
 ## Features
 
-- **Ingress Transports**: Publish endpoints via Upterm WebSocket relays (default), srv.us reverse tunnels, Cloudflare Worker relays, or Cloudflare Argo (`cloudflared`) tunnels.
+- **Ingress Transports**: Publish endpoints via srv.us reverse tunnels (default), Upterm WebSocket relays, Cloudflare Worker relays, or Cloudflare Argo (`cloudflared`) tunnels.
 - **Confinement**: SFTP and SCP workloads are restricted to the designated workspace root; parent traversals and out-of-root symlinks are blocked.
 - **Host file visibility**: Relative transfer paths begin in the workspace root while absolute paths address host locations, matching shell behavior; add `--restrict-file-transfer` for strict workspace-only transfers.
 - **Direct Shell Access**: Authenticated PTY sessions run interactively under the local user credentials.
@@ -72,10 +72,12 @@ pip install nullgate
 
 ### Start
 
-Launch the gateway service and ingress transport in the background:
+Start the gateway service and ingress transport, then report readiness once the
+gateway listens, the transport stays alive, and srv.us has announced a
+hostname (for that provider):
 
 ```bash
-# Default Upterm transport on port 4822 sharing current directory
+# Default srv.us transport on port 4822 sharing current directory
 nullgate start
 
 # Custom path, port, and slot
@@ -94,16 +96,26 @@ nullgate start . --provider cloudflared --public-hostname workspace.example.com
 Options:
 - `-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`.
+- `-t`, `--provider`: Public connection provider (`upterm`, `srvus`, `cloudflare`, or `cloudflared`). Defaults to `srvus`.
 - `-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.
+- `--identity-seed VALUE`: srv.us identity seed value (visible in argv and shell history; flag overrides seed file and `NULLGATE_IDENTITY_SEED`; other providers ignore it). Prefer `--identity-seed-file PATH` to avoid history exposure. The direct value is never printed or saved; `restart` cannot reuse it because only the seed-file path is persisted. The seed only matters when the identity key does not yet exist.
+- `--identity-seed-file PATH`: Read the srv.us identity seed from a file (overrides `NULLGATE_IDENTITY_SEED`; other providers ignore it). The file must hold nonempty UTF-8 text; only the path is saved for `restart`, never the seed value. `restart` revalidates the saved file before stopping the running session. The seed only matters when the identity key does not yet exist.
+- `--public-access`: Allow connections without credentials (unsafe on public endpoints). Off by default; only `restart` reuses a saved setting, a fresh `start` always defaults to authenticated access.
 - `--no-public-access`: Require authentication.
-- `--tcp-forwarding`: Enable SSH TCP tunneling (`ssh -L`).
-- `--no-tcp-forwarding`: Disable SSH TCP tunneling.
+- `--tcp-forwarding`: Allow SSH TCP tunneling (`ssh -L`; enabled by default on fresh `start`).
+- `--no-tcp-forwarding`: Disable SSH TCP tunneling. `restart` reuses the saved effective setting.
 - `--restrict-file-transfer`: Keep SFTP and SCP inside the workspace.
 - `--no-restrict-file-transfer`: Allow host-visible file transfers.
+- `--foreground`: Stay in the foreground and supervise gateway and transport instead of exiting after readiness. The parent handles SIGINT and SIGTERM and stops both children, exiting nonzero with recent log tails if either child dies.
+- `--json`: Emit machine-readable JSON on stdout (the only stdout in JSON mode). `start --foreground --json` prints one readiness object, flushes it, then supervises.
+
+A fresh `start` uses documented defaults and the current directory when no
+workspace is given; only `restart` reuses saved workspace, provider, port,
+and security settings. Only the hidden external-launcher flags `--notte-api`
+(boolean) and `--notte-user VALUE` are accepted for compatibility; any other
+unknown flag fails normally.
 
 ### Status
 
@@ -111,16 +123,26 @@ Display operational status, running PIDs, connection URLs, and security settings
 
 ```bash
 nullgate status
+nullgate status --json
 ```
 
+When stdout is not a TTY, `status` emits only a directly usable SSH fallback
+command plus a `password: VALUE` line when a generated password exists; with no
+live target it prints `stopped` or `pending`. `--json` is the stable full
+machine interface.
+
 ### Connect
 
 Print client connection strings and OpenSSH client configuration directives:
 
 ```bash
 nullgate connect
+nullgate connect --json
 ```
 
+On an interactive TTY `connect` keeps the setup instructions; piped output
+emits only the directly usable fallback command.
+
 ### Logs
 
 Stream or print daemon logs:
@@ -142,7 +164,10 @@ nullgate stop
 
 ### Restart
 
-Restart daemon instances reusing active or saved workspace settings:
+Restart daemon instances reusing the saved workspace, provider, port, and
+security settings from the previous start. A direct `--identity-seed` value
+from the original start is intentionally not persisted, so `restart` cannot
+reuse it; only the seed-file path is saved and revalidated.
 
 ```bash
 nullgate restart
@@ -161,10 +186,12 @@ 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.
+Unknown flags fail normally; only the hidden external-launcher flags
+`--notte-api` (boolean) and `--notte-user VALUE` are accepted as no-ops.
 
 ## Authentication and Security Boundaries
 
-- **Authentication Baseline**: Access requires authorized SSH keys in `~/.ssh/authorized_keys` or a high-entropy secret created in the runtime directory.
+- **Authentication Baseline**: Authenticated access is the default. Pass `--public-access` to allow connections without credentials (unsafe on public endpoints). Without it, srv.us secure startup uses authorized SSH keys from `~/.ssh/authorized_keys` and/or a generated high-entropy password stored in the runtime directory.
 - **Public access (`--public-access`)**: Bypasses authentication checks entirely; any incoming connection with network access is accepted.
 - **Upterm Transport**: Relies on authorized SSH public keys or `--public-access` (Upterm does not support password authentication). The relay itself is trusted for inbound multiplexing.
 - **Filesystem Confinement**: SFTP and SCP access cannot escape the designated workspace directory.
@@ -178,7 +205,7 @@ remain accepted, but new scripts should use the names documented above.
 |---|---|
 | `NULLGATE_PASSWORD` | Gateway-process credential; normally managed internally by `nullgate start` |
 | `NULLGATE_STATE_DIR` | Directory holding runtime state and logs (defaults to `~/.local/state/nullgate`) |
-| `NULLGATE_IDENTITY_SEED` | Seed value used for deterministic Ed25519 key derivation |
+| `NULLGATE_IDENTITY_SEED` | Seed for deterministic Ed25519 key derivation; only used when creating the identity file, never when it already exists |
 | `NULLGATE_TUNNEL_HOST` | Host address for srv.us ingress (default: `srv.us`) |
 | `NULLGATE_TUNNEL_PORT` | Port for srv.us ingress (default: `22`) |
 | `NULLGATE_CLOUDFLARED_TOKEN` | Credential token for `cloudflared` tunnels |
@@ -186,6 +213,42 @@ remain accepted, but new scripts should use the names documented above.
 | `NULLGATE_VERSION` | Install a specific published version instead of the stable release; accepts `1.0.1` or `v1.0.1` |
 | `NULLGATE_DIST_URL` | Override the public release channel used by `install.sh` |
 | `NULLGATE_INSTALL_URL` | Override the installer URL used by `nullgate upgrade` |
+| `NO_COLOR` | Set to any value to disable ANSI color output (non-TTY output never uses color) |
+
+## Automation/CI
+
+- Noninteractive runs never prompt: with stdin closed or piped, `start` skips
+  the key prompt and generates the password for srv.us secure mode. Upterm
+  secure mode without authorized keys fails immediately instead of hanging.
+- Readiness is decisive: `start` returns success only after the gateway
+  listens, the transport stays alive, and (for srv.us) a hostname is
+  announced. On timeout or failure both processes are stopped, recent
+  transport logs go to stderr, and the exit code is nonzero.
+- `start --foreground` keeps the parent alive supervising both children,
+  handles SIGINT/SIGTERM by stopping them, and exits nonzero with recent log tails if
+  either child dies. Background start remains the default.
+- `start`, `status`, and `connect` accept `--json` for machine-readable
+  output. JSON is the only stdout in JSON mode and carries the operational
+  fields agents need: version, provider, running state and PIDs, port,
+  workspace, URL, host, user, proxy command, auth mode, TCP forwarding, and
+  file-transfer mode. `--json` is the stable agent contract; human output may
+  change. `start --foreground --json` prints one readiness object,
+  flushes it, then supervises.
+- Piped output is compact: successful `start`, `status`, and `connect` with a
+  target emit only a directly usable SSH fallback command plus one
+  `password: VALUE` line when a generated password exists. With no live
+  usable target, `status` prints `stopped` or `pending`.
+- Identity seeds: `--identity-seed-file PATH` keeps the value out of argv
+and history (flag overrides `NULLGATE_IDENTITY_SEED`); `--identity-seed
+VALUE` is also accepted but is visible in argv and shell history. Both apply
+only to the srv.us provider, fail before launch when absent, unreadable, or
+empty (direct value: nonempty after stripping), pass the seed only to the
+srv.us child environment (every other child gets a seed-free environment even
+when the parent exported one), and never print or persist the value. Only the
+seed-file path is saved for `restart`, which revalidates the saved srv.us seed
+file before stopping anything; a direct `--identity-seed` from the original
+start is intentionally not persisted, so `restart` cannot reuse it. The seed
+only takes effect when the identity key does not yet exist.
 
 ## Development
 

{nullgate-1.2.2 → nullgate-1.2.5}/README.md

@@ -7,7 +7,7 @@ Disposable SSH gateway into confined directory workspaces for remote containers,
 Run Nullgate directly from PyPI without installing it first:
 
 ```bash
-# Share the current directory over the default Upterm provider
+# Share the current directory over the default srv.us provider
 uvx nullgate start
 
 # Share a specific workspace
@@ -24,13 +24,13 @@ 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.
+Nullgate requires authentication by default (an authorized SSH key and/or a
+generated password). Pass `--public-access` to allow connections without
+credentials (unsafe on public endpoints).
 
 ## Features
 
-- **Ingress Transports**: Publish endpoints via Upterm WebSocket relays (default), srv.us reverse tunnels, Cloudflare Worker relays, or Cloudflare Argo (`cloudflared`) tunnels.
+- **Ingress Transports**: Publish endpoints via srv.us reverse tunnels (default), Upterm WebSocket relays, Cloudflare Worker relays, or Cloudflare Argo (`cloudflared`) tunnels.
 - **Confinement**: SFTP and SCP workloads are restricted to the designated workspace root; parent traversals and out-of-root symlinks are blocked.
 - **Host file visibility**: Relative transfer paths begin in the workspace root while absolute paths address host locations, matching shell behavior; add `--restrict-file-transfer` for strict workspace-only transfers.
 - **Direct Shell Access**: Authenticated PTY sessions run interactively under the local user credentials.
@@ -60,10 +60,12 @@ pip install nullgate
 
 ### Start
 
-Launch the gateway service and ingress transport in the background:
+Start the gateway service and ingress transport, then report readiness once the
+gateway listens, the transport stays alive, and srv.us has announced a
+hostname (for that provider):
 
 ```bash
-# Default Upterm transport on port 4822 sharing current directory
+# Default srv.us transport on port 4822 sharing current directory
 nullgate start
 
 # Custom path, port, and slot
@@ -82,16 +84,26 @@ nullgate start . --provider cloudflared --public-hostname workspace.example.com
 Options:
 - `-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`.
+- `-t`, `--provider`: Public connection provider (`upterm`, `srvus`, `cloudflare`, or `cloudflared`). Defaults to `srvus`.
 - `-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.
+- `--identity-seed VALUE`: srv.us identity seed value (visible in argv and shell history; flag overrides seed file and `NULLGATE_IDENTITY_SEED`; other providers ignore it). Prefer `--identity-seed-file PATH` to avoid history exposure. The direct value is never printed or saved; `restart` cannot reuse it because only the seed-file path is persisted. The seed only matters when the identity key does not yet exist.
+- `--identity-seed-file PATH`: Read the srv.us identity seed from a file (overrides `NULLGATE_IDENTITY_SEED`; other providers ignore it). The file must hold nonempty UTF-8 text; only the path is saved for `restart`, never the seed value. `restart` revalidates the saved file before stopping the running session. The seed only matters when the identity key does not yet exist.
+- `--public-access`: Allow connections without credentials (unsafe on public endpoints). Off by default; only `restart` reuses a saved setting, a fresh `start` always defaults to authenticated access.
 - `--no-public-access`: Require authentication.
-- `--tcp-forwarding`: Enable SSH TCP tunneling (`ssh -L`).
-- `--no-tcp-forwarding`: Disable SSH TCP tunneling.
+- `--tcp-forwarding`: Allow SSH TCP tunneling (`ssh -L`; enabled by default on fresh `start`).
+- `--no-tcp-forwarding`: Disable SSH TCP tunneling. `restart` reuses the saved effective setting.
 - `--restrict-file-transfer`: Keep SFTP and SCP inside the workspace.
 - `--no-restrict-file-transfer`: Allow host-visible file transfers.
+- `--foreground`: Stay in the foreground and supervise gateway and transport instead of exiting after readiness. The parent handles SIGINT and SIGTERM and stops both children, exiting nonzero with recent log tails if either child dies.
+- `--json`: Emit machine-readable JSON on stdout (the only stdout in JSON mode). `start --foreground --json` prints one readiness object, flushes it, then supervises.
+
+A fresh `start` uses documented defaults and the current directory when no
+workspace is given; only `restart` reuses saved workspace, provider, port,
+and security settings. Only the hidden external-launcher flags `--notte-api`
+(boolean) and `--notte-user VALUE` are accepted for compatibility; any other
+unknown flag fails normally.
 
 ### Status
 
@@ -99,16 +111,26 @@ Display operational status, running PIDs, connection URLs, and security settings
 
 ```bash
 nullgate status
+nullgate status --json
 ```
 
+When stdout is not a TTY, `status` emits only a directly usable SSH fallback
+command plus a `password: VALUE` line when a generated password exists; with no
+live target it prints `stopped` or `pending`. `--json` is the stable full
+machine interface.
+
 ### Connect
 
 Print client connection strings and OpenSSH client configuration directives:
 
 ```bash
 nullgate connect
+nullgate connect --json
 ```
 
+On an interactive TTY `connect` keeps the setup instructions; piped output
+emits only the directly usable fallback command.
+
 ### Logs
 
 Stream or print daemon logs:
@@ -130,7 +152,10 @@ nullgate stop
 
 ### Restart
 
-Restart daemon instances reusing active or saved workspace settings:
+Restart daemon instances reusing the saved workspace, provider, port, and
+security settings from the previous start. A direct `--identity-seed` value
+from the original start is intentionally not persisted, so `restart` cannot
+reuse it; only the seed-file path is saved and revalidated.
 
 ```bash
 nullgate restart
@@ -149,10 +174,12 @@ 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.
+Unknown flags fail normally; only the hidden external-launcher flags
+`--notte-api` (boolean) and `--notte-user VALUE` are accepted as no-ops.
 
 ## Authentication and Security Boundaries
 
-- **Authentication Baseline**: Access requires authorized SSH keys in `~/.ssh/authorized_keys` or a high-entropy secret created in the runtime directory.
+- **Authentication Baseline**: Authenticated access is the default. Pass `--public-access` to allow connections without credentials (unsafe on public endpoints). Without it, srv.us secure startup uses authorized SSH keys from `~/.ssh/authorized_keys` and/or a generated high-entropy password stored in the runtime directory.
 - **Public access (`--public-access`)**: Bypasses authentication checks entirely; any incoming connection with network access is accepted.
 - **Upterm Transport**: Relies on authorized SSH public keys or `--public-access` (Upterm does not support password authentication). The relay itself is trusted for inbound multiplexing.
 - **Filesystem Confinement**: SFTP and SCP access cannot escape the designated workspace directory.
@@ -166,7 +193,7 @@ remain accepted, but new scripts should use the names documented above.
 |---|---|
 | `NULLGATE_PASSWORD` | Gateway-process credential; normally managed internally by `nullgate start` |
 | `NULLGATE_STATE_DIR` | Directory holding runtime state and logs (defaults to `~/.local/state/nullgate`) |
-| `NULLGATE_IDENTITY_SEED` | Seed value used for deterministic Ed25519 key derivation |
+| `NULLGATE_IDENTITY_SEED` | Seed for deterministic Ed25519 key derivation; only used when creating the identity file, never when it already exists |
 | `NULLGATE_TUNNEL_HOST` | Host address for srv.us ingress (default: `srv.us`) |
 | `NULLGATE_TUNNEL_PORT` | Port for srv.us ingress (default: `22`) |
 | `NULLGATE_CLOUDFLARED_TOKEN` | Credential token for `cloudflared` tunnels |
@@ -174,6 +201,42 @@ remain accepted, but new scripts should use the names documented above.
 | `NULLGATE_VERSION` | Install a specific published version instead of the stable release; accepts `1.0.1` or `v1.0.1` |
 | `NULLGATE_DIST_URL` | Override the public release channel used by `install.sh` |
 | `NULLGATE_INSTALL_URL` | Override the installer URL used by `nullgate upgrade` |
+| `NO_COLOR` | Set to any value to disable ANSI color output (non-TTY output never uses color) |
+
+## Automation/CI
+
+- Noninteractive runs never prompt: with stdin closed or piped, `start` skips
+  the key prompt and generates the password for srv.us secure mode. Upterm
+  secure mode without authorized keys fails immediately instead of hanging.
+- Readiness is decisive: `start` returns success only after the gateway
+  listens, the transport stays alive, and (for srv.us) a hostname is
+  announced. On timeout or failure both processes are stopped, recent
+  transport logs go to stderr, and the exit code is nonzero.
+- `start --foreground` keeps the parent alive supervising both children,
+  handles SIGINT/SIGTERM by stopping them, and exits nonzero with recent log tails if
+  either child dies. Background start remains the default.
+- `start`, `status`, and `connect` accept `--json` for machine-readable
+  output. JSON is the only stdout in JSON mode and carries the operational
+  fields agents need: version, provider, running state and PIDs, port,
+  workspace, URL, host, user, proxy command, auth mode, TCP forwarding, and
+  file-transfer mode. `--json` is the stable agent contract; human output may
+  change. `start --foreground --json` prints one readiness object,
+  flushes it, then supervises.
+- Piped output is compact: successful `start`, `status`, and `connect` with a
+  target emit only a directly usable SSH fallback command plus one
+  `password: VALUE` line when a generated password exists. With no live
+  usable target, `status` prints `stopped` or `pending`.
+- Identity seeds: `--identity-seed-file PATH` keeps the value out of argv
+and history (flag overrides `NULLGATE_IDENTITY_SEED`); `--identity-seed
+VALUE` is also accepted but is visible in argv and shell history. Both apply
+only to the srv.us provider, fail before launch when absent, unreadable, or
+empty (direct value: nonempty after stripping), pass the seed only to the
+srv.us child environment (every other child gets a seed-free environment even
+when the parent exported one), and never print or persist the value. Only the
+seed-file path is saved for `restart`, which revalidates the saved srv.us seed
+file before stopping anything; a direct `--identity-seed` from the original
+start is intentionally not persisted, so `restart` cannot reuse it. The seed
+only takes effect when the identity key does not yet exist.
 
 ## Development
 

nullgate-1.2.5/src/nullgate/__init__.py

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

{nullgate-1.2.2 → nullgate-1.2.5}/src/nullgate/commands.py

@@ -118,7 +118,7 @@ def build_parser() -> argparse.ArgumentParser:
         dest="allow_tcp_forwarding",
         action=argparse.BooleanOptionalAction,
         default=None,
-        help="Allow SSH port forwarding.",
+        help="Allow SSH port forwarding (enabled by default; --no-tcp-forwarding disables).",
     )
     start_parser.add_argument(
         "--allow-tcp-forwarding",
@@ -161,6 +161,43 @@ def build_parser() -> argparse.ArgumentParser:
         help="Cloudflare tunnel token (for the cloudflared provider).",
     )
     start_parser.add_argument("--token", dest="token", help=argparse.SUPPRESS)
+    seed_group = start_parser.add_mutually_exclusive_group()
+    seed_group.add_argument(
+        "--identity-seed",
+        dest="identity_seed",
+        metavar="VALUE",
+        default=None,
+        help="srv.us identity seed value (visible in argv/history; ignored by other providers).",
+    )
+    seed_group.add_argument(
+        "--identity-seed-file",
+        dest="identity_seed_file",
+        metavar="PATH",
+        default=None,
+        help="File holding the srv.us identity seed (overrides NULLGATE_IDENTITY_SEED; ignored by other providers).",
+    )
+    start_parser.add_argument(
+        "--foreground",
+        dest="foreground",
+        action="store_true",
+        help="Stay in the foreground and supervise gateway and transport.",
+    )
+    start_parser.add_argument(
+        "--json",
+        dest="json",
+        action="store_true",
+        help="Emit machine-readable JSON on stdout.",
+    )
+    start_parser.add_argument(
+        "--notte-api", dest="notte_api", action="store_true", help=argparse.SUPPRESS
+    )
+    start_parser.add_argument(
+        "--notte-user",
+        dest="notte_user",
+        metavar="VALUE",
+        default=None,
+        help=argparse.SUPPRESS,
+    )
 
     sub.add_parser(
         "stop",
@@ -169,19 +206,31 @@ def build_parser() -> argparse.ArgumentParser:
         help="Stop SSH access (aliases: down, shut).",
     )
 
-    sub.add_parser(
+    status_parser = sub.add_parser(
         "status",
         aliases=["ps", "inspect"],
         description="Show service health, connection details, and security settings.",
         help="Show current status (aliases: ps, inspect).",
     )
+    status_parser.add_argument(
+        "--json",
+        dest="json",
+        action="store_true",
+        help="Emit machine-readable JSON on stdout.",
+    )
 
-    sub.add_parser(
+    connect_parser = sub.add_parser(
         "connect",
         aliases=["ssh", "enter"],
         description="Show how to connect with SSH.",
         help="Show SSH connection instructions (aliases: ssh, enter).",
     )
+    connect_parser.add_argument(
+        "--json",
+        dest="json",
+        action="store_true",
+        help="Emit machine-readable JSON on stdout.",
+    )
 
     logs_parser = sub.add_parser(
         "logs",
@@ -238,7 +287,10 @@ def build_parser() -> argparse.ArgumentParser:
 
 def main(argv: Sequence[str] | None = None) -> int:
     parser = build_parser()
-    args = parser.parse_args(argv)
+    supplied = list(sys.argv[1:] if argv is None else argv)
+    if supplied in (["--help"], ["api", "--help"]):
+        supplied = ["start"]
+    args = parser.parse_args(supplied)
 
     handlers = {
         "start": session.cmd_open,