Description

Description

Three small UX issues found while running every read-only openshell
subcommand on OpenShell 0.0.39. All are local to the OpenShell CLI but
they surface during NemoClaw doc-testing workflows so filing them in
this module is appropriate.

(E3) `openshell sandbox ssh-config ` returns exit 0 with a
     fully-formed SSH config block even when `` is a sandbox that
     does not exist. There is no existence check.

       $ openshell sandbox ssh-config nonexistent-sandbox-xyz
       Host openshell-nonexistent-sandbox-xyz
           User sandbox
           StrictHostKeyChecking no
           UserKnownHostsFile /dev/null
           ...
           ProxyCommand /localhome/.../openshell ssh-proxy
                        --gateway-name nemoclaw
                        --name nonexistent-sandbox-xyz

     A user scripting "for s in $(openshell sandbox list); do
     openshell sandbox ssh-config $s ...; done" who fat-fingers a name
     gets a clean config block and may believe the sandbox exists.

(E4) `openshell logs  --tail 20` is rejected with an error that
     doesn't tell the user what the right invocation looks like:

       $ openshell logs test --tail 20
       error: unexpected argument '20' found

       Usage: openshell logs [OPTIONS] [NAME]

       For more information, try '--help'.
       exit 2

     The actual flag is either `--tail` (boolean, "stream live logs") or
     `-n 20` (integer, line count). Neither is suggested in the error.
     Compare with NemoClaw's clean validation errors (e.g.
     `nemoclaw  logs --tail abc` →
     "Expected an integer but received: abc").

(E5) `openshell doctor` with no subcommand prints help and exits 0
     instead of running the default check:

       $ openshell doctor
       Diagnose gateway issues
       USAGE
         doctor [COMMAND]
       COMMANDS
         check  Validate system prerequisites for running a gateway
       ...
       (exit 0)

       $ openshell doctor check
       Checking system prerequisites...
         Docker ............. ok (version 29.5.0)
         DOCKER_HOST ........ (not set, using default socket)
       All checks passed.

     The top-level OpenShell `--help` describes `doctor` as "Diagnose
     gateway issues" with no hint that you have to type `doctor check`
     for it to do anything. The NemoClaw `troubleshooting.md` page
     references `openshell doctor` as if running it directly was the
     diagnostic action. With no `check` arg the command silently
     no-ops by printing help.

Device:        ipp2-1558 (10.176.178.100), x86_64 server, 32 vCPU / 125 GB RAM, NVIDIA A100 80GB PCIe
OS:            Ubuntu 24.04.4 LTS (Linux 6.17.0-23-generic)
Architecture:  x86_64
OpenShell CLI: 0.0.39
NemoClaw:      v0.0.44

(E3)
  $ openshell sandbox list                   # confirm sandbox names
  $ openshell sandbox ssh-config bogus-xyz   # exit 0, prints config
  $ echo "Exit: $?"                          # 0

(E4)
  $ openshell logs test --tail 20            # exit 2
  $ openshell logs --help | grep -- '--tail'
  → --tail is boolean "Stream live logs"; line count is `-n `.

(E5)
  $ openshell doctor                         # exit 0, prints help only
  $ echo "Exit: $?"                          # 0
  $ openshell doctor check                    # actually runs checks

(E3) ssh-config returns non-zero (or warns prominently on stderr) when
     the named sandbox does not exist. Suggested: same NotFound error
     that `openshell sandbox get bogus-xyz` already prints.

(E4) The error message tells the user what shape of invocation is
     valid. Either:
       error: --tail is a boolean flag for live streaming;
              use `-n ` (or `--lines `) for a fixed number of
              lines.
     or accept `--tail ` for compatibility with the line-count idiom.

(E5) `openshell doctor` without a subcommand defaults to `doctor
     check` so the verb the docs use ("openshell doctor") actually
     does the thing the docs imply. Help-only output should also exit
     non-zero so scripts can tell the difference.

(E3) Generates SSH config for non-existent sandbox; exit 0.
(E4) Generic clap error, no suggestion, exit 2.
(E5) Prints help, exit 0, no diagnostics run.

$ openshell --version
openshell 0.0.39

$ openshell sandbox list
NAME        CREATED              PHASE
test        2026-05-15 07:26:14  Error
hermes-bug  2026-05-18 07:17:19  Ready

$ openshell sandbox ssh-config nonexistent-sandbox-xyz ; echo "Exit: $?"
Host openshell-nonexistent-sandbox-xyz
    User sandbox
    StrictHostKeyChecking no
    UserKnownHostsFile /dev/null
    GlobalKnownHostsFile /dev/null
    LogLevel ERROR
    ServerAliveInterval 15
    ServerAliveCountMax 3
    ProxyCommand /localhome/local-glennz/.local/bin/openshell ssh-proxy --gateway-name nemoclaw --name nonexistent-sandbox-xyz
Exit: 0

$ openshell sandbox get nonexistent-sandbox-xyz ; echo "Exit: $?"
Error: × status: NotFound, message: "sandbox not found", ...
Exit: 1

$ openshell logs test --tail 20 ; echo "Exit: $?"
error: unexpected argument '20' found
Usage: openshell logs [OPTIONS] [NAME]
Exit: 2

$ openshell doctor ; echo "Exit: $?"
Diagnose gateway issues
USAGE
  doctor [COMMAND]
COMMANDS
  check  Validate system prerequisites for running a gateway
  help   Print this message or the help of the given subcommand(s)
Exit: 0

(E3) In `openshell sandbox ssh-config`, look up the sandbox in the
     gateway state before printing the block. If not found, exit 1
     with the same "sandbox not found" message used by
     `openshell sandbox get`.

(E4) In the clap definition for `openshell logs`, change the error path
     for unexpected positional after `--tail` to a custom message that
     names `-n ` as the line-count alternative. Or accept
     `--tail ` as a numeric value (interpreting `--tail` alone as
     the boolean stream).

(E5) Make `openshell doctor` default to `doctor check` when no
     subcommand is given. Help output, when explicitly requested,
     should remain the way it is. The cli-selection-guide / docs do
     not need to change.

Bug Details

[NVB#6186965]