bug(cli): openshell gateway start removed in v0.0.37 with no migration guide — "unrecognized subcommand 'start'"

[ascerra]

Agent Diagnostic

• Discovered when CI pipelines began failing after v0.0.37 was released on May 8: openshell gateway start returns error: unrecognized subcommand 'start'
• Confirmed v0.0.36 supports gateway start and works correctly
• Traced the removal to PR refactor(cli): remove gateway lifecycle management #1221 (refactor(cli): remove gateway lifecycle management), which removed gateway start, gateway stop, and gateway destroy in favor of systemd/Homebrew/Helm-managed gateway processes
• Reviewed the v0.0.37 release notes, README, installation docs, quickstart, manage-gateways page, and release-notes page — none mention the removal of gateway start or provide a migration path from the previous CLI-managed gateway lifecycle
• No CHANGELOG.md, MIGRATION.md, BREAKING_CHANGES.md, or UPGRADING.md exists in the repository
• The install.sh script resolves latest by default, so any automation without a version pin silently received v0.0.37 and broke
• Workaround: pinning OPENSHELL_VERSION=v0.0.36 restores gateway start functionality

Description

openshell gateway start was the documented way to start an OpenShell gateway in v0.0.36 and every prior release. In v0.0.37, PR #1221 removed gateway start, gateway stop, and gateway destroy entirely. The replacement is platform-managed gateway lifecycle (systemd on Linux, Homebrew services on macOS, Helm on Kubernetes).

The v0.0.37 release notes label this a "breaking release" but the breakage warning covers protobuf shape changes and database migration — not the removal of gateway start. The PR appears as one line item among 100+ changes (refactor(cli): remove gateway lifecycle management) with no explicit callout. No migration guide, deprecation notice, or upgrade instructions exist anywhere:

• Release notes: no mention of gateway start removal
• docs/about/installation.mdx: describes the new systemd/Homebrew model as if it was always this way
• docs/sandboxes/manage-gateways.mdx: no migration note
• docs/about/release-notes.mdx: links to GitHub Releases, no curated changelog
• README.md: quietly removed gateway start from the key commands table
• No CHANGELOG.md, MIGRATION.md, BREAKING_CHANGES.md, or UPGRADING.md exists in the repo

Any automation using install.sh without OPENSHELL_VERSION pin silently received v0.0.37 and broke, because the script resolves latest by default.

Actual: openshell gateway start returns error: unrecognized subcommand 'start' on v0.0.37.

Expected: Either (a) gateway start continues to work with a deprecation warning pointing to the new flow, or (b) the release notes and docs explicitly document the removal and the replacement commands for each platform.

Reproduction Steps

1. Install OpenShell v0.0.37:

   curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh | OPENSHELL_VERSION=v0.0.37 sh

2. Verify version:

   openshell --version
   # openshell 0.0.37

3. Run:

   openshell gateway start

4. Observe: error: unrecognized subcommand 'start'
5. For comparison, install v0.0.36:

   curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh | OPENSHELL_VERSION=v0.0.36 sh
   openshell gateway start  # succeeds

Environment

• OS: Ubuntu 24.04 (GitHub Actions ubuntu-latest), also Fedora 42 (local)
• Docker: Docker Engine 27.x (GitHub Actions default)
• OpenShell: v0.0.37 (broken), v0.0.36 (working)
• Architecture: x86_64-unknown-linux-musl

Logs

$ openshell --version
openshell 0.0.37

$ openshell gateway start
error: unrecognized subcommand 'start'

Usage: openshell gateway [OPTIONS] [COMMAND]

For more information, try '--help'.

Agent-First Checklist

• I pointed my agent at the repo and had it investigate this issue
• I loaded relevant skills (e.g., debug-openshell-cluster, debug-inference, openshell-cli)
• My agent could not resolve this — the diagnostic above explains why

[drew]

Sorry to hear your automation broke. OpenShell is still alpha software so we expect some contract changes to land with minimal or no notice. As we move to beta we'll start to provide stability guarantees for APIs and scripts..

To address items raised in this issue, I have

• Updated our install script to require explicit opt-in to upgrade when 0.0.36 or below is installed
• Updated 0.0.37 release notes to include better upgrade guidance
• Updated 0.0.36 release notes to provide a pinned install script so you can easily install 0.0.36 again
• Added a ticket, feat(docs): publish versioned Fern docs for releases #1296, to publish versioned documentation