Show usage hint when shell starts disconnected (#81)#82
Open
mkrueger wants to merge 3 commits into
Open
Conversation
…n with no args Issue #81: a first-time user launching `cosmosdbshell` lands at the prompt with no indication that authentication is required or how to perform it. The legacy MS Learn doc says "it prompts you for authentication" but in fact it does not — the user has to type `connect <endpoint>`, which is not discoverable from the welcome banner. Two surgical changes: 1. ShellInterpreter.RunAsync now prints a one-line yellow hint after the ready banner when the shell starts in DisconnectedState, telling the user to run `connect <endpoint>` (or `help connect`). 2. ConnectCommand.PrintConnectionInfoAsync now follows the existing "Not connected" line with a small usage block listing the connect examples taken from the command's CosmosExample metadata, plus a pointer to `help connect` for the full option list. Reusing ExamplesWithDescriptions keeps a single source of truth shared with the help system. Adds three tests under ConnectCommandTests: - The new ftl strings resolve to non-empty values. - The connect command exposes example variants beyond the bare `connect` no-arg form so the hint helper has something to print. - The hint helper runs against a fresh ShellInterpreter without throwing. No command-surface changes; file-redirected and MCP output are unaffected since the hint is written via AnsiConsole only when stdin is interactive.
There was a problem hiding this comment.
Pull request overview
This PR improves first-run discoverability for authentication in the Cosmos DB Shell by adding user-facing hints when the shell starts disconnected and when connect is run with no arguments while disconnected (refs #81).
Changes:
- Adds a yellow “not connected” hint on startup when the shell begins in
DisconnectedState. - Enhances
connect(no args, disconnected) to print a short usage block populated from the command’s[CosmosExample]metadata. - Adds tests to guard localization keys and ensure the new hint helper has examples and runs without throwing.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| CosmosDBShell/lang/en.ftl | Adds new localized strings for the disconnected startup hint and connect usage header/footer. |
| CosmosDBShell/Azure.Data.Cosmos.Shell.Core/ShellInterpreter.cs | Prints a startup hint when the shell launches in DisconnectedState. |
| CosmosDBShell/Azure.Data.Cosmos.Shell.Commands/ConnectCommand.cs | Adds PrintConnectUsageHint and invokes it when connect is run while disconnected. |
| CosmosDBShell.Tests/CommandTests/ConnectCommandTests.cs | Adds tests for the new localization keys and a smoke test for the hint helper. |
The localized strings were passed directly to AnsiConsole.MarkupLine, so a future translation containing '[' or ']' would be parsed as Spectre markup. The example/description lines in the same helper already use Markup.Escape; apply the same to the header and footer for consistency. Addresses Copilot review feedback on PR #82.
Contributor
Author
|
Changed output a bit: 
|
sevoku
approved these changes
May 16, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Refs #81.
A first-time user launching
cosmosdbshelllands at the prompt with no indication that authentication is required or how to perform it. Theconnectcommand works, but its existence isn't surfaced anywhere by the welcome banner.This PR adds two small, surgical hints — no command-surface changes:
1. Disconnected startup hint
After the existing
Cosmos DB shell ready.banner, when the shell starts inDisconnectedState, print a one-line yellow hint pointing atconnect/help connect.2. Better
connectwith no args while disconnectedWhen a user runs
connectwithout arguments while not connected, follow the existingNot connected to any Cosmos DB account.line with a small usage block listing the connect examples taken straight from the command's[CosmosExample]metadata, plus a pointer tohelp connect. ReusingCommandFactory.ExamplesWithDescriptionskeeps a single source of truth shared with the help system, so adding new credential flavors automatically updates this hint.What it looks like
Before:
After:
Tests
Three new tests under
ConnectCommandTests:shell-not_connected_hint,command-connect-not_connected-usage-header,command-connect-not_connected-usage-footer) resolve to non-empty values — guards against typos in the localization references.connectno-arg form so the hint helper has something to print.ShellInterpreterwithout throwing.(Local
dotnet testwas blocked by the VS Code LSP integration holding the shell binary; full suite verified once locally before that, and CI will re-run on the PR.)Out of scope (worth a separate issue/PR)
connectflow on launch (would require an interactive prompt — bigger change to the shell startup contract).MicrosoftDocs/azure-docsto fix the "prompts you for authentication" line on Microsoft Learn.