NVIDIA / NVIDIA/OpenShell

feat(cli): improve provider discoverability for agents and developers

Open
#2,549 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

state:stale
Dominant language
Rust
Stars
8.7k
Forks
1.3k
Avg merge
2d 11h
Merged PRs (30d)
253

Description

Problem Statement

AI agents building OpenShell workflows cannot discover the provider credential-hiding path. The provider system is powerful but invisible — agents take the path of least resistance (--env) because --provider requires multi-step setup knowledge that isn't in their context.

Human developers face the same problem: the CLI help for sandbox create doesn't prioritize --provider over --env for credentials, error messages don't suggest providers when connections fail, and there's no command to bridge from "I have these env vars" to "here are the providers I should use."

Proposed Design

1. openshell provider suggest command

New subcommand that matches env var names to built-in profile credential declarations:

$ openshell provider suggest --env JIRA_API_TOKEN=... --env MLFLOW_TRACKING_TOKEN=...

Suggested providers:
  JIRA_API_TOKEN        →  jira (built-in profile)
  MLFLOW_TRACKING_TOKEN →  mlflow (built-in profile)

To set up:
  openshell provider create --name my-jira --type jira --credential JIRA_API_TOKEN
  openshell provider create --name my-mlflow --type mlflow --credential MLFLOW_TRACKING_TOKEN

This gives agents a direct command to discover the right path without reading docs.

2. Updated CLI help text

Reorder openshell sandbox create --help to recommend --provider before --env for credentials. Currently --env appears without context about its security implications.

3. Connection failure hints

When a sandbox connection to a host fails and that host matches a built-in profile's endpoint, include a hint in the error message suggesting the matching profile.

Dependencies
  • Depends on NVIDIA/OpenShell#2547 (built-in Jira/MLflow profiles) — provider suggest needs profiles to match against
  • Better experience with NVIDIA/OpenShell#2548 (CLI credential warnings) — complementary discoverability mechanisms
  • Better experience with NVIDIA/OpenShell#2545 (providers v2 default-on) — suggested provider path works without extra setup

Motivation

In opendatahub-io/agent-ops#7, the AI agent building the demo workflow did not know about providers v2. It passed all credentials as --env because that path is obvious and immediately works. provider suggest would have bridged the gap.

Agent Investigation

  • Built-in profile credential env var names available via builtin_profiles() in crates/openshell-providers/src/profiles.rs
  • openshell provider list-profiles already exists — suggest would add env-var-to-profile matching
  • CLI help templates in crates/openshell-cli/src/main.rs (PROVIDER_EXAMPLES, sandbox create help)

Checklist

  • Searched for existing issues — no issue tracks provider discoverability for agents
  • Design includes three complementary discoverability mechanisms

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with builtin_profiles() in crates/openshell-providers/src/profiles.rs and the existing provider list-profiles command, then read the CLI help templates in crates/openshell-cli/src/main.rs. The work is complete when provider suggest matches environment variable names to built-in profiles, sandbox create help prioritizes --provider, and matching connection failures include a profile hint.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
cli, security
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.